Card#
Follow a step-by-step guide on how an online card payment works.Credit cards have global coverage and are one of the most popular ways to pay online. There are different types of cards and several steps in the process. Learn how it works, the parties involved, and the stages of a payment process behind the scenes.Due to our risk policies, the available payment methods and the integration type may vary once you complete the affiliation. We will tell you how to proceed if this process applies to your merchant.
Steps of the Payment Process#
A payment process usually consists of 4 stages: Data verification, authentication, authorization, and capture.1. Data Verification#
At this stage, the card details are verified to be correct (for example, that the expiration date is not expired, or that the number obeys the Luhn's algorithm). In this step, it cannot be yet warranted that the card is valid.2. Authentication (optional)#
In some instances, depending on the country's regulations, bank requirements, or by choice of the merchant, the customer may be required to authenticate a purchase by entering a password. This may be a one-time authentication (via SMS, email, or a physical device that generates passwords) or another mechanism agreed with the card-issuing entity.3. Authorization#
At this stage, the bank (or the card issuer) checks whether there are sufficient funds for the account associated with the card. If so, retains that amount in the customer account to guarantee it to the merchant.4. Capture#
This is when money is moved from the issuing bank (or financial entity) to the merchant's account.Using the API#
To use the API you must ask for your Kushki Sandbox, composed of a Public-Merchant-Id and a Private-Merchant-Id.The current version of the Kushki API rests at: https://api.kushkipagos.com/
The testing version rests at: https://api-uat.kushkipagos.com/
Endpoints#
Idempotency#
Kushki's API supports idempotent requests to safely retry operations without the risk of executing the same transaction twice. This feature is especially useful when network issues, timeouts, or client retries might otherwise create duplicate records.How it works#
To perform an idempotent request, include the header Idempotency-Key with a unique value when calling one of the supported endpoints.Kushki stores the resulting status code and response body only if the original request succeeds.
If the same key is sent again within the validity window, the same successful response is returned.
If the original request failed with a 4XX or 5XX error, no idempotency record is stored, and the client can safely retry the entire process with the same Idempotency-Key.
Rules#
Valid for: 24 hours. After this period, if the same Idempotency-Key is sent again, a new transaction will be generated.
Maximum length: 56 characters.
Uniqueness: must be unique per transaction type.
Scope: applies only to supported endpoints (see below).
Generation: clients are responsible for generating keys. We recommend UUIDv4 or another random string generator with sufficient entropy.
Supported endpoints#
The Idempotency-Key header is currently supported in Ecuador for:Void a transaction (one-time charges).
Refund a transaction (one-time charges).
Error scenarios#
5XX errors (server-side issues)#
No idempotency record is stored.
The client may retry with the same Idempotency-Key.
Retrying is at the integrator's discretion.
4XX errors (client-side issues)#
No idempotency record is stored.
The client may retry with the same Idempotency-Key after correcting the input.
Retrying is at the integrator's discretion.
Best practices#
Always generate a new Idempotency-Key for each unique transaction attempt.
Use a UUID or another strong random string generator to ensure uniqueness.
