1. Online Payments
  • Developer Docs Ecuador 🇪🇨
  • Online Payments
    • Release Notes
    • Card Payments
      • Request a card token
      • Make a charge or deferred charge
      • Refund a transaction
      • Void a transaction
      • Request deferred options
      • Validate OTP
      • Bin Info V2
      • Bin Info
    • One Click and Scheduled Payments
      • Request a recurring charge token
      • Create a recurring charge
      • Update recurring charge card data
      • Make an One-click payment
      • Cancel a recurring charge
      • Update a recurring charge
      • Add a temporary charge or discount
      • Get recurring charge Info
    • Chargebacks
      • Query chargebacks
      • Request chargeback export
    • Subscription Transactions
      • Get subscription transactions
    • Transfer in
      • Request a Transfer In token
      • Init Transaction
      • Get Status
    • Cash in
      • Request a cash in token
      • Init Transaction
      • Update a cash in transaction
      • Transaction Status
      • Delete a cash in transaction
    • Smartlinks
      • Create a Smartlink
      • Update a Smartlink
      • Get a Smartlink
      • Delete a smartlink
    • Analytics
      • Get transactions list v1
      • Get transactions list v2
    • Status
      • Get gateway status
      • Get platform status
    • Commissions
      • Get Commission Configuration
    • Payment Credentials
      • Create a credential
      • Search credentials
      • Activate or deactivate
      • Delete credential
      • Update credential
      • Regenerate a credential
      • Advanced search
    • Payment Button
      • Create a payment button
    • Settlement
      • Query settlement
  • Appian - Submerchant Register
    • Submerchant Validation in Batch
    • Query submerchant status by requestId/submerchantId
    • Get submerchantIds
    • Get credentials for submerchants
  • Schemas
    • threeDomainSecure
    • webhooks
    • Card-old
    • Channel
    • Amount-cash-in
    • ChargebackListResponse
    • StatusComponent
    • SettlementDateRangeRequest
    • SubscriptionTransactionsResponse
    • Card
    • currency
    • networkToken
    • ChargebackItem
    • ErrorResponse
    • SettlementTicketRequest
    • SubscriptionTransaction
    • Subscription
    • Amount
    • ErrorResponse400
    • SettlementResponse
    • extraTaxes
    • Country
    • ErrorResponse401
    • SettlementRecord
    • Language
    • Deferred
    • ErrorResponse403
    • Metadata
    • payment_method
    • ErrorResponse500
    • ContactDetails
    • documentType
    • orderDetails
    • Shipping Address
    • Billing-Address
    • payment_submethod
    • SubscriptionUpdate
    • product
    • SubscriptionAdjustmentRequest
    • threeDomainSecure
    • webhooks
    • headers
    • webhooksChargeback
    • citMit
    • network
    • binInfo
    • messageFields
    • UnexpectedErrorResponse
    • ExternalReferenceId
    • transactionType
BienvenidaPerú 🇵🇪México 🇲🇽Ecuador 🇪🇨
Colombia 🇨🇴Chile 🇨🇱
BienvenidaPerú 🇵🇪México 🇲🇽Ecuador 🇪🇨
Colombia 🇨🇴Chile 🇨🇱
  1. Online Payments

Card Payments

The Card API lets you tokenize card data and process payments securely in Ecuador. All sensitive card information is handled by Kushki — your server only sends the token.
Keep in mind!
Token generation and charges require your Private Key (Private-Merchant-Id). Never expose it in client-side or frontend code — always call the token endpoint from your backend.

Payment flow#

1
Request a card token
Call POST /card/v1/tokens from your backend with the card data and transaction amount. The response returns a one-time token valid for a single charge.
{
  "card": {
    "name": "Juan Pérez",
    "number": "4242424242424242",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "123"
  },
  "totalAmount": 100.00,
  "currency": "USD"
}
⚠️ Token expiry: Tokens are single-use and expire after a short window. Use them immediately — never store them.
2
Make a charge
Call POST /card/v1/charges with the token and the amount breakdown. Include contactDetails and, optionally, orderDetails for fraud scoring.
{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": {
    "subtotalIva": 89.29,
    "subtotalIva0": 0,
    "ice": 0,
    "iva": 10.71,
    "currency": "USD"
  },
  "contactDetails": {
    "documentType": "CID",
    "documentNumber": "1712345678",
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "user@example.com"
  }
}
A successful charge returns a ticketNumber and transactionReference. Store both for reconciliation, voids, and refunds.
3
Handle the response
Check the code/message fields. On approval, deliver the goods or service. On decline, surface the error to the buyer and allow a retry with a new token.

Currencies#

Ecuador operates in US Dollars (USD). Send the full amount breakdown so taxes are reported correctly:
FieldDescription
subtotalIvaAmount subject to IVA (VAT).
subtotalIva0Amount not subject to IVA.
iceSpecial consumption tax (ICE), if applicable.
ivaIVA (VAT) amount.
currencyAlways USD.

Document types#

TypeDescription
CIDCédula de identidad.
RUCRegistro Único de Contribuyentes.
PASSPORTPassport (foreign cardholders).

Deferred charges (Installments)#

Ecuador supports deferred payments (pagos diferidos): corriente, diferido con interés, and diferido sin interés, with optional grace months.
1
Check available plans
Call GET /card/v1/deferred/{bin} with the card BIN to retrieve the deferred options the issuer allows (months, creditType, graceMonths).
2
Submit the deferred charge
Send POST /card/v1/charges including the deferred object:
{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "amount": { "subtotalIva": 89.29, "subtotalIva0": 0, "ice": 0, "iva": 10.71, "currency": "USD" },
  "deferred": {
    "creditType": "03",
    "graceMonths": 2,
    "months": 12
  }
}

OTP validation (3D Secure)#

For transactions that require cardholder authentication, validate the one-time password with POST /rules/v1/secureValidation before completing the charge.

Void and Refund#

OperationEndpointWhen to use
VoidDELETE /v1/charges/{ticketNumber}Cancel a charge the same day, before settlement.
RefundDELETE /v1/refund/{ticketNumber}Return funds after the transaction has settled.

BIN info#

Look up card metadata (brand, bank, type) before charging:
GET /card/v1/bin/{bin} — BIN info.
GET /deferred/v2/bin/{bin} — BIN info v2, including deferred eligibility.

Recurring charges#

To link a charge to an external subscription in Ecuador, send externalSubscriptionID in POST /card/v1/charges. In Ecuador this field is used without originalTransactionID or citMit.

Authentication#

All requests are authenticated with your Private-Merchant-Id header. Generate tokens and charges only from your backend.

Available Endpoints#

MethodPathDescription
POST/card/v1/tokensRequest a card token
POST/card/v1/chargesMake a charge or deferred charge
GET/card/v1/deferred/{bin}Request deferred options
POST/rules/v1/secureValidationValidate OTP
GET/card/v1/bin/{bin}BIN info
GET/deferred/v2/bin/{bin}BIN info v2
DELETE/v1/charges/{ticketNumber}Void a transaction
DELETE/v1/refund/{ticketNumber}Refund a transaction
Modified at 2026-07-10 16:48:01
Previous
Release Notes
Next
Request a card token
Built with