Card Out

Card Outs (card payouts) let you push money directly to a recipient's debit card. Use it for disbursements, winnings payouts, refunds to card, or any flow where you need to send funds to a specific card number.

Keep in mind!

Token generation requires your Private Key (Private-Merchant-Id). Never expose it in client-side or frontend code — always call the token endpoint from your backend.

Two payout modes

Mode	Description
One-time payout	Tokenize the card once and push funds immediately.
Subscription payout	Register the card as a subscription and push funds on demand at any time using the `subscriptionId`.

One-time payout flow

Request a card payout token

Call POST /payouts/card/v1/tokens with the recipient's card data and the paymentType. Returns a one-time token.

{
  "card": {
    "name": "Carlos Ramirez",
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "29"
  },
  "paymentType": "FD"
}

Response:

{
  "token": "8122eb4bda29476f8dc71b6426a7fd5d",
  "maskedPan": "495703XXXXXX0454",
  "brand": "VISA"
}

Push funds

Call POST /payouts/card/v1/pushFunds with the token (or card data directly), amount, and recipient details.

{
  "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"
}

A successful push returns transactionStatus: "APPROVAL" with a ticketNumber and transactionReference.

Verify the transaction

Call GET /payouts/card/v1/transaction/{transactionReference} to confirm the final status.

{
  "transactionStatus": "APPROVAL",
  "ticketNumber": "951738256068368362",
  "transactionReference": "763274a1-b47b-493f-934f-047801cc04a0",
  "amount": 250.00,
  "processor": {
    "code": "00",
    "message": "Approved and completed successfully"
  }
}

Subscription payout flow

Use subscriptions when you need to push funds to the same card multiple times (e.g., regular payouts, recurring winnings).

Create a subscription token

Call POST /payouts/card/v1/subscriptions/tokens with the card data. Returns a subscriptionId you store on your side.

{
  "card": {
    "name": "Carlos Ramirez",
    "number": "4111111111111111",
    "expiryMonth": "03",
    "expiryYear": "27"
  },
  "paymentType": "FD"
}

Response:

{
  "subscriptionId": "956a8eb60epa4993b378e34488610e7f",
  "maskedPan": "495703XXXXXX0454",
  "brand": "VISA"
}

Push funds using the subscription

Call POST /payouts/card/v1/subscriptions/pushFunds/{subscriptionId} whenever you want to disburse funds — no card data needed again.

{
  "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"
}

Delete the subscription (when done)

Call DELETE /payouts/card/v1/token/{subscriptionId} to remove the registered card when no further payouts are needed.

Payment types

Peru supports two paymentType values:

Value	Description
`FD`	Funds Disbursement — general-purpose fund push
`OG`	Online Gambling — for gaming/lottery platforms

Push funds request fields

Field	Required	Description
`token`	One of `token` or `card`	One-time token from the payout token endpoint.
`card`	One of `token` or `card`	Card data directly (name, number, expiryMonth, expiryYear).
`paymentType`	Yes	`FD` or `OG`.
`amount.currency`	Yes	Always `PEN` for Peru.
`amount.totalAmount`	Yes	Amount to push to the card.
`clientTransactionId`	Yes	Your unique UUID for this transaction — used for idempotency and status lookup.
`recipient.address`	No	Recipient's street address.
`recipient.city`	No	Recipient's city.
`recipient.country`	No	Recipient's country code (e.g., `"PER"`).
`recipient.zipCode`	No	Recipient's postal code.
`webhooks`	No	Array of URLs to notify on transaction status changes.
`fullResponse`	No	Pass `"v2"` to receive full transaction details including BIN info, approval code, and amounts.
`metadata`	No	Custom key-value pairs for your own tracking.

Webhooks

Include a webhooks array in your push funds request to receive real-time notifications:

{
  "webhooks": ["https://yoursite.com/kushki/notify"]
}

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Get Card Payout Token

Tokenize a card for a one-time payout. Returns a single-use token and masked PAN.

Push Funds

Send funds to a card using a token or card data directly. Supports webhooks and full response.

Get Subscription Token

Push Funds (Subscription)

Send funds to a previously registered subscription card without re-submitting card data.

Get Transaction Status

Check the status of a card payout by transaction reference.

Delete Subscription

Remove a registered card subscription permanently.

Got a suggestion on this documentation? Contact us.

Two payout modes#

One-time payout flow#

Subscription payout flow#

Payment types#

Push funds request fields#

Webhooks#

Authentication#

Using the API#

Available Endpoints#

Two payout modes

One-time payout flow

Subscription payout flow

Payment types

Push funds request fields

Webhooks

Authentication

Using the API

Available Endpoints