Pagos con tarjeta
¡Ten en cuenta!
Private-Merchant-Id). Nunca la expongas en código de cliente o frontend: llama siempre al endpoint de token desde tu backend.Flujo de pago
Solicita un token de tarjeta
Llama a
POST /card/v1/tokens desde tu backend con los datos de la tarjeta y el monto de la transacción. La respuesta devuelve un token de un solo uso, válido para un único cargo.{
"card": {
"name": "Juan Pérez",
"number": "4242424242424242",
"expiryMonth": "08",
"expiryYear": "28",
"cvv": "123"
},
"totalAmount": 100.00,
"currency": "USD"
}⚠️ Expiración del token: Los tokens son de un solo uso y expiran en poco tiempo. Úsalos de inmediato y nunca los almacenes.
Realiza un cargo
Llama a Un cargo exitoso devuelve un
POST /card/v1/charges con el token y el desglose del monto. Incluye contactDetails y, de forma opcional, orderDetails para el scoring antifraude.{
"token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
"amount": {
"subtotalIva": 89.29,
"subtotalIva0": 0,
"ice": 0,
"iva": 10.71,
"currency": "USD"
},
"contactDetails": {
"documentType": "CI",
"documentNumber": "1712345678",
"firstName": "Juan",
"lastName": "Pérez",
"email": "user@example.com"
}
}ticketNumber y un transactionReference. Guarda ambos para conciliación, anulaciones y reembolsos.Procesa la respuesta
Revisa los campos
code/message. Si se aprueba, entrega el bien o servicio. Si se rechaza, muestra el error al comprador y permite reintentar con un token nuevo.Monedas
USD). Envía el desglose completo del monto para que los impuestos se reporten correctamente:| Campo | Descripción |
|---|---|
subtotalIva | Monto sujeto a IVA. |
subtotalIva0 | Monto no sujeto a IVA. |
ice | Impuesto a los Consumos Especiales (ICE), si aplica. |
iva | Monto del IVA. |
currency | Siempre USD. |
Tipos de documento
| Tipo | Descripción |
|---|---|
CI | Cédula de identidad. |
RUC | Registro Único de Contribuyentes. |
PAS | Pasaporte (tarjetahabientes extranjeros). |
Cargos diferidos
corriente, diferido con interés y diferido sin interés, con meses de gracia opcionales.Consulta los planes disponibles
Llama a
GET /card/v1/deferred/{bin} con el BIN de la tarjeta para obtener las opciones de diferido que permite el emisor (months, creditType, graceMonths).Envía el cargo diferido
Envía
POST /card/v1/charges incluyendo el objeto deferred:{
"token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
"amount": { "subtotalIva": 89.29, "subtotalIva0": 0, "ice": 0, "iva": 10.71, "currency": "USD" },
"deferred": {
"creditType": "03",
"graceMonths": 2,
"months": 12
}
}Validación de OTP (3D Secure)
POST /rules/v1/secureValidation antes de completar el cargo.Anulación y reembolso
| Operación | Endpoint | Cuándo usarla |
|---|---|---|
| Anulación | DELETE /v1/charges/{ticketNumber} | Cancelar un cargo el mismo día, antes de la liquidación. |
| Reembolso | DELETE /v1/refund/{ticketNumber} | Devolver los fondos después de que la transacción se liquidó. |
Información del BIN
GET /card/v1/bin/{bin} — información del BIN.GET /deferred/v2/bin/{bin} — información del BIN v2, incluye la elegibilidad para diferidos.Cargos recurrentes
externalSubscriptionID en POST /card/v1/charges. En Ecuador este campo se usa sin originalTransactionID ni citMit.Autenticación
Private-Merchant-Id. Genera los tokens y los cargos únicamente desde tu backend.Endpoints disponibles
| Método | Ruta | Descripción |
|---|---|---|
POST | /card/v1/tokens | Request a card token |
POST | /card/v1/charges | Make a charge or deferred charge |
GET | /card/v1/deferred/{bin} | Request deferred options |
POST | /rules/v1/secureValidation | Validate 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-09-11 14:47:09