Card Out
¡Ten en cuenta!
Private-Merchant-Id). Nunca la expongas en código de cliente o de frontend: llama siempre al endpoint de token desde tu backend.Dos modos de dispersión
| Modo | Descripción |
|---|---|
| Dispersión única | Tokeniza la tarjeta una vez y envía los fondos de inmediato. |
| Dispersión por suscripción | Registra la tarjeta como suscripción y envía fondos on demand en cualquier momento con el subscriptionId. |
Flujo de dispersión única
Solicita un token de card payout
Llama a Respuesta:
POST /payouts/card/v1/tokens con los datos de la tarjeta del destinatario y el paymentType. Devuelve un token de un solo uso.{
"card": {
"name": "Carlos Ramirez",
"number": "4111111111111111",
"expiryMonth": "12",
"expiryYear": "29"
},
"paymentType": "FD"
}{
"token": "8122eb4bda29476f8dc71b6426a7fd5d",
"maskedPan": "495703XXXXXX0454",
"brand": "VISA"
}Envía los fondos
Llama a Un envío exitoso devuelve
POST /payouts/card/v1/pushFunds con el token (o los datos de la tarjeta directamente), el monto y los datos del destinatario.{
"token": "8122eb4bda29476f8dc71b6426a7fd5d",
"paymentType": "FD",
"amount": {
"currency": "PEN",
"totalAmount": 250.00
},
"clientTransactionId": "a3f8d721-1b2c-4e5f-9a0d-123456789abc",
"recipient": {
"address": "Av. Larco 1301",
"city": "Lima",
"country": "PER",
"zipCode": "15046"
},
"fullResponse": "v2"
}transactionStatus: "APPROVAL" con un ticketNumber y un transactionReference.Verifica la transacción
Llama a
GET /payouts/card/v1/transaction/{transactionReference} para confirmar el estado final.{
"transactionStatus": "APPROVAL",
"ticketNumber": "951738256068368362",
"transactionReference": "763274a1-b47b-493f-934f-047801cc04a0",
"amount": 250.00,
"processor": {
"code": "00",
"message": "Approved and completed successfully"
}
}Flujo de dispersión por suscripción
Crea un token de suscripción
Llama a Respuesta:
POST /payouts/card/v1/subscriptions/tokens con los datos de la tarjeta. Devuelve un subscriptionId que guardas de tu lado.{
"card": {
"name": "Carlos Ramirez",
"number": "4111111111111111",
"expiryMonth": "03",
"expiryYear": "27"
},
"paymentType": "FD"
}{
"subscriptionId": "956a8eb60epa4993b378e34488610e7f",
"maskedPan": "495703XXXXXX0454",
"brand": "VISA"
}Envía fondos con la suscripción
Llama a
POST /payouts/card/v1/subscriptions/pushFunds/{subscriptionId} cada vez que quieras dispersar fondos: no necesitas volver a enviar los datos de la tarjeta.{
"paymentType": "FD",
"amount": {
"currency": "PEN",
"totalAmount": 250.00
},
"clientTransactionId": "b7e9c432-2d3e-5f6a-0b1c-234567890bcd",
"recipient": {
"address": "Av. Larco 1301",
"city": "Lima",
"country": "PER",
"zipCode": "15046"
},
"fullResponse": "v2"
}Elimina la suscripción (cuando termines)
Llama a
DELETE /payouts/card/v1/token/{subscriptionId} para eliminar la tarjeta registrada cuando ya no necesites más dispersiones.Tipos de pago
paymentType:| Valor | Descripción |
|---|---|
FD | Dispersión de fondos: envío de fondos de propósito general |
OG | Juegos en línea: para plataformas de juegos y lotería |
Campos de la solicitud push funds
| Campo | Requerido | Descripción |
|---|---|---|
token | Uno de token o card | Token de un solo uso del endpoint de payout token. |
card | Uno de token o card | Datos de la tarjeta directamente (name, number, expiryMonth, expiryYear). |
paymentType | Sí | FD o OG. |
amount.currency | Sí | Siempre PEN para Perú. |
amount.totalAmount | Sí | Monto a enviar a la tarjeta. |
clientTransactionId | Sí | Tu UUID único para esta transacción: se usa para idempotencia y para consultar el estado. |
recipient.address | No | Dirección del destinatario. |
recipient.city | No | Ciudad del destinatario. |
recipient.country | No | Código de país del destinatario (por ejemplo, "PER"). |
recipient.zipCode | No | Código postal del destinatario. |
webhooks | No | Array de URLs a notificar cuando cambia el estado de la transacción. |
fullResponse | No | Envía "v2" para recibir el detalle completo de la transacción, incluidos datos del BIN, código de aprobación y montos. |
metadata | No | Pares clave-valor personalizados para tu propio seguimiento. |
Webhooks
webhooks en tu solicitud push funds para recibir notificaciones en tiempo real:{
"webhooks": ["https://yoursite.com/kushki/notify"]
}Autenticación
Uso de la API
🟢 Producción
🧪 Sandbox (UAT)
https://api.kushkipagos.com/Endpoints disponibles
Solicitar un token de Card Out
Tokeniza una tarjeta para una dispersión única. Devuelve un token de un solo uso y el PAN enmascarado.Enviar fondos
Envía fondos a una tarjeta con un token o con los datos de la tarjeta directamente. Admite webhooks y full response.Solicitar un token de suscripción
Registra una tarjeta para dispersiones recurrentes. Devuelve un subscriptionId para envíos futuros.Enviar fondos (suscripción)
Envía fondos a una tarjeta ya registrada como suscripción sin volver a enviar los datos de la tarjeta.¿Tienes una sugerencia sobre esta documentación? Escríbenos.
Modified at 2026-09-07 16:54:15