1. Card
Español
  • Español
  • English
  • Bienvenida
    • Home Page
  • Perú 🇵🇪
    • Kushki Developer Portal 🚀
    • Perú 🇵🇪
    • Libraries & SDKs (Online Payments)
      • Release notes
      • Mobile
        • Kushki Android
        • Kushki iOS 
        • Kushki iOS ARM Setup
      • Web
        • Kushki.js 🌐
        • kushki.js-hosted-fields
          • kushki.js Hosted Fields
          • Guía de migración a Kushki.js 2.0
          • Antifraud
            • Interfaces
              • SecureInitRequest
              • SecureInitResponse
              • SiftScienceObject
            • Methods
              • requestInitAntiFraud
              • requestSecureInit
              • requestValidate3DS
          • Card
            • CarApplePay interface
              • ICardApplePay Interface
            • Card-Interface
              • ICard Interface
              • ICardSubscriptions Interface
            • Errors
              • Error list
            • Interfaces
              • Amount
              • ApplePayGetTokenOptions Interface
              • ApplePayOptions Interface
              • ApplePayPaymentContact
              • AppleTokenResponse
              • BrandByMerchantResponse Interface
              • CardFieldValues
              • CardInfo
              • CardOptions
              • CardTokenResponse
              • DeferredByBinOptionsResponse
              • DeferredInputValues
              • DeferredValuesResponse
              • DeviceTokenRequest
              • Field
              • FieldInstance
              • Fields
              • FieldValidity
              • FormValidity
              • MasterCardBrandingRequest
              • SecureDeviceTokenOptions
              • Styles
              • TokenResponse
              • VisaBrandingRequest
            • Methods
              • initApplePayButton
              • initCardToken
              • initSecureDeviceToken
              • requestBrandsByMerchant method
              • requestDeviceToken method
              • requestInitCardBrandingAnimation
            • Types
              • CssProperties
              • Currency
              • FieldTypeEnum
          • Card Payouts
            • Card Payouts Interface
              • ICardPayouts
            • Enumerations
              • Enumeration `InputModelEnum`
            • Errors
              • Errors
            • Interfaces
              • CardPayoutOptions
              • CardPayoutSubscriptionTokenResponse
              • CardPayoutUniqueTokenResponse
              • Field
              • Fields
              • FieldValidity
              • Interface FormValidity
              • Interface `Styles`
            • Methods
              • initCardPayoutToken
            • Type Aliases
              • CardPayoutTokenResponse
              • InputTypeEnum
            • Types
              • CssProperties
          • Kushki
            • Methods
              • init function
              • requestBankList function
              • requestCommissionConfiguration function
            • Classes
              • KushkiError
            • Interfaces
              • CommissionConfigurationRequest
              • IKushki
              • KushkiOptions
    • Raíz
    • Schemas
      • API Raw Card Present
        • metadata
        • extra_taxes
        • card
        • sub_merchant
        • pos_details
        • enc_tlv
        • deferred
        • contact_details
        • card_details
        • amount
      • Chargebacks
      • Commissions
      • Gateway Status
      • ChargebackListResponse
      • StatusComponent
      • currency
      • one-and-two-step-payment
      • webhooksChargeback
      • ChargebackItem
      • webhooks
      • networkToken
      • webhooksItem
      • transactionType
      • ErrorResponse400
      • threeDomainSecure
      • ErrorResponse401
      • product
      • ErrorResponse403
      • payment_submethod
      • ErrorResponse500
      • payment_method
      • paymentMethod
      • orderDetails
      • Shipping Address
      • headers
      • extraTaxes
      • documentType
      • currency
      • currency-cash-in
      • currency-CL
      • binInfo
      • UnexpectedErrorResponse
      • citMit
      • SubscriptionUpdate
      • messageFields
      • network
      • SubscriptionAdjustmentRequest
      • Subscription
      • Submerchant
      • Shipping-Address
      • Promotions
      • Metadata
      • Language
      • InvalidBinResponse
      • GetConfigurationRequest
      • ErrorResponse
      • Deferred
      • Country
      • ContactDetails
      • ChargesVoidCardResponse
      • Channel
      • Card
      • Billing-Address
      • BadRequestResponse
      • Amount
      • Amount-cash-in
      • Amount-CL
  • México 🇲🇽
    • Bienvenidos
    • ONLINE PAYMENTS
      • CARD
        • CARD
        • 1. Request a card token
        • 2. Make a charge or deferred charge
        • 3. Void a transaction
        • 4. Refund a transaction
        • 5. Request deferred options
        • 6. Authorize payments
        • 7. Reauthorize payments
        • 8. Capture an authorized payment
        • 9. Bin Info
        • 10. Bin Info V2
        • 11. Validate OTP
        • 12. Verify Account
        • 12. Verify Account
        • 6. Authorize payments
        • 10. Bin Info V2
        • 8. Capture an authorized payment
        • 3. Void a transaction
        • 4. Refund a transaction
        • 7. Reauthorize payments
        • 1. Request a card token
        • 9. Bin Info
        • 5. Request deferred options
        • 2. Make a charge or deferred charge
        • 11. Validate OTP
      • CASH IN
        • 1. Request a cash in token
        • 2. Init Transaction
        • 3. Transaction Status
        • 1. Request a cash in token
        • 2. Init Transaction
        • 3. Transaction Status
      • TRANSFER IN
        • 1. Request a Transfer In token
        • 2. Init Transaction
        • 4. Get Status Copy
        • 1. Request a Transfer In token
        • 4. Get Status Copy
        • 2. Init Transaction
      • TRANSFER OUT
        • 1. Get Bank List
        • 2. Request a Transfer Out token
        • 3. Init Transaction
        • 4. Get Status
        • 5. Wallet Balance
        • 5. Wallet Balance
        • 1. Get Bank List
        • 4. Get Status
        • 2. Request a Transfer Out token
        • 3. Init Transaction
      • ONE-CLICK & SCHEDULED PAYMENTS
        • 1. Request a recurring charge token
        • 2. Create a recurring charge
        • 3. Update recurring charge card data
        • 4. Make an One-click payment
        • 5. Cancel a recurring charge
        • 6. Update a recurring charge
        • 7. Add a temporary charge or discount
        • 8. Authorize payments Copy
        • 9. Capture an authorized payment Copy
        • 10. Get recurring charge Info
        • 1. Request a recurring charge token
        • 8. Authorize payments Copy
        • 3. Update recurring charge card data
        • 6. Update a recurring charge
        • 10. Get recurring charge Info
        • 2. Create a recurring charge
        • 5. Cancel a recurring charge
        • 9. Capture an authorized payment Copy
        • 4. Make an One-click payment
        • 7. Add a temporary charge or discount
      • PAYMENT BUTTON
        • 1. Create a payment button
        • 1. Create a payment button
      • SMARTLINKS V2
        • 1. Create a Smartlink
        • 2. Get a Smartlink
        • 3. Delete a Smartlink
        • 4. Update a Smartlink
        • 1. Create a Smartlink
        • 4. Update a Smartlink
        • 2. Get a Smartlink
        • 3. Delete a Smartlink
      • PAYMENT CREDENTIALS
        • 1. Create a credential
        • 2. Search credentials
        • 3. Advanced search
        • 4. Activate or deactivate
        • 5. Delete credential
        • 6. Update credential
        • 7. Regenerate a credential
        • 3. Advanced search
        • 6. Update credential
        • 5. Delete credential
        • 2. Search credentials
        • 4. Activate or deactivate
        • 7. Regenerate a credential
        • 1. Create a credential
      • COMMISSIONS
        • 1. Get Commission Configuration
        • 1. Get Commission Configuration
      • GATEWAY STATUS
        • 1. Get gateway status
        • 1. Get gateway status
      • ANALYTICS
        • 1. Get transactions list
        • 1. Get transactions list
    • CARD PRESENT PAYMENTS (BILLPOCKET)
      • Get token
      • States
      • Validate token
      • Municipalities
      • Collect payments
      • Tax companies
      • Capture an authorized payment
      • Commercial activities
      • Refund
      • Create checkout
      • Get status
      • Get checkout details
      • Collect card payments
      • Print Ticket
      • Collect card payments v2
      • Cancel Push Notification
      • Get transaction status
      • Add or update CLABE account
      • Configure payment link
      • Get payment link configuration
      • Create payment link
      • Update payment link
      • List payment links
      • Delete payment link
      • Add CLABE account
      • Get token
      • Get transaction list
      • Get transaction list v2
      • Get transaction list v3
      • Get transaction list v4
      • Create user
    • CARD PRESENT PAYMENTS (API RAW) Copy Copy
      • error-catalog
      • Test data
      • One-time payments
        • Single payment
      • Two-step-payments
        • Authorization and capture
      • Voids & Refunds
        • Void & Reverse
        • Refund a transaction
      • Card information
        • Balance inquiries
        • Get BIN Info
        • BIN info V2
        • Request deferred options
      • Query Transactions
        • Transaction Search
  • Ecuador 🇪🇨
    • Bienvenidos
    • ONLINE PAYMENTS
      • Card
        • Overview
        • Request a card token
          POST
        • Make a charge or deferred charge
          POST
        • Void a transaction
          DELETE
        • Request deferred options
          GET
        • Validate OTP
          POST
        • Refund a transaction
          DELETE
        • Bin Info
          GET
        • Bin Info V2
          GET
      • One Click Charges
        • Overview
        • Request a recurring charge token
        • Create a recurring charge
        • Make an One-click payment
        • Cancel a recurring charge
        • Add a temporary charge or discount
        • Get recurring charge Info
        • Update a recurring charge
        • Update recurring charge card data
      • Transfer in
        • Overview
        • Get Bank List
        • Request a Transfer In token
        • Init Transaction
        • Get Status
      • Cash in
        • Overview
        • Request a cash in token
        • Init Transaction
        • Transaction Status
        • Update a cash in transaction
        • Delete a cash in transaction
      • Chargebacks
        • Overview
        • Query chargebacks
        • Request chargeback export
      • Smartlinks
        • Overview
        • Create a Smartlink
        • Update a Smartlink
        • Get a Smartlink
        • Delete a smartlink
        • Get a Smartlink
        • Delete a Smartlink
        • Update a Smartlink
        • Create a Smartlink
      • Payment Button
        • Overview
        • Create a payment button
      • Payment Credentials
        • Overview
        • Regenerate a credential
        • Activate or deactivate
        • Update credential
        • Search credentials
        • Delete credential
        • Create a credential
        • Advanced search
      • Gateway Status
        • Overview
        • Get gateway status
      • Analytics
        • Overview
        • Get transactions list v2
        • Get transactions list v1
      • Commissions
        • Commissions
        • Get Commission Configuration
  • Colombia 🇨🇴
    • ANALYTICS
      • Get transactions list v1
      • Get transactions list v2
    • CARD-OUTS
      • Request a cash out token
      • Init Transaction
      • Update a cash out transaction
      • Delete a cash out transaction
      • Transaction Status
    • CARD
      • Bin Info
      • Bin Info V2
      • Request deferred options
      • Request a card token
      • Make a charge or deferred charge
      • Create payment (tokenless)
      • Authorize payments
      • Preauthorization (tokenless)
      • Capture an authorized payment
      • Reauthorize payments
      • Refund a transaction
      • Void a transaction
      • Verify Account
      • Validate OTP
    • TRANSFER IN
      • Get Bank List
      • Request a Transfer In token
      • Init Transaction
      • Get Status
    • TRANSFER OUT
      • Get Bank List
      • Get Bank List V2
      • Request a Transfer Out token
      • Init Transaction
      • Get Status
      • Void a transaction
      • Balance for Payouts
    • CASH-IN
      • Request a cash in token
      • Init Transaction
      • Update a cash in transaction
      • Delete a cash in transaction
      • Transaction Status
    • CASH-OUT
      • Request a cash out token
      • Init Transaction
      • Update a cash out transaction
      • Delete a cash out transaction
      • Transaction Status
    • COMMISSIONS
      • Get Commission Configuration
    • GATEWAY-STATUS
      • Get gateway status
      • Get platform status
    • ONE-CLICK & SCHEDULED PAYMENTS
      • Request a recurring charge token
      • Update recurring charge card data
      • Update a recurring charge
      • Add a temporary charge or discount
      • Get recurring charge Info
      • Create a recurring charge
      • Make an One-click payment
      • Cancel a recurring charge
      • Authorize payments
      • Capture an authorized payment
    • PAYMENT-BUTTON
      • Create a payment button
    • PAYMENT-CREDENTIALS
      • Advanced search
      • Delete credential
      • Regenerate a credential
      • Search credentials
      • Activate or deactivate
      • Update credential
      • Create a credential
    • SMARTLINKS-V2
      • Create a Smartlink
      • Get a Smartlink
      • Update a Smartlink
      • Delete a smartlink
    • TRANSFER-IN
      • Get Bank List
      • Request a Transfer In token
      • Init Transaction
      • Get Status
    • TRANSFER-OUT
      • Balance for Payouts
      • Get Bank List
      • Get Bank List V2
      • Request a Transfer Out token
      • Init Transaction
      • Get Status
      • Void a transaction
  • Chile 🇨🇱
    • Bienvenidos
    • CARD PRESENT PAYMENTS (API RAW) Copy
      • One-time payments
      • Two-step-payments
      • Voids & Refunds
      • Card information
      • Query Transactions
    • Online Payments
      • Card Async
        • Request a card async token
        • Authorize payments
        • Get Status
        • Capture an authorized payment
        • Init Transaction
      • Async Card Recurring Charges
        • Request an async card recurring charge token
        • Init an async card recurring charge
        • Capture an authorized payment
        • Authorize payments
        • Capture an authorized payment
        • Authorize payments
      • Card
        • Bin Info
        • Bin Info V2
        • Request deferred options
        • Request a card token
        • Make a charge or deferred charge
        • Create payment (tokenless)
        • Authorize payments
        • Capture an authorized payment
        • Reauthorize payments
        • Void a transaction
        • Refund a transaction
        • Voucher
        • Validate OTP
        • Verify Account
      • Chargebacks
        • Query chargebacks
        • Request chargeback export
      • Transfer In
      • Transfer Out
      • Cash In
      • Smartlinks V2
      • Analytics
        • Get transactions list v1
        • Get transactions list v2
      • Gateway Status
        • Get gateway status
      • Commissions
      • Payment Credentials
      • Payment Button
      • Platform Status
      • Subscription Transactions
      • Preauthorization (tokenless)
  1. Card

Overview

Gemini_Generated_Image_kt6is6kt6is6kt6i.png

API Base URL#

EnvironmentURL
Production:https://api.kushkipagos.com
UAT:https://api-uat.kushkipagos.com

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.
WARNING

To keep in mind!#

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
Etapas de pago con tarjeta EN
1
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 can not be yet warranted that the card is valid.
2
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
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
4. Capture
This is when money is moved from the issuing bank (or financial entity) to the merchant's account
Read more on our documentation page.

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#

We dispose various endpoints to start your payment flows, find our products available:
Request a card token
Make a charge or deferred charge
Void a transaction
Refund a transaction
Request deferred options
Validate OTP
Bin Info
Bin Info V2

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.

Header#

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:
Void a transaction (one-time charges, preauthorizations, and subscription charges).
Refund a transaction (one-time charges, preauthorizations, and subscription charges).
Subscription preauthorizations.

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.
TIP
Got a suggestion on this documentation? Contact Us.
Modified at 2026-04-15 21:33:25
Previous
Bienvenidos
Next
Request a card token
Built with