Send money to a card

Sending funds to cards involves processing payments to a debit or credit card. This can be done in two ways:
Through a 100% API direct integration (only available for PCI-compliant merchants).
By performing prior card tokenization using the Hosted Fields library.
The flow you will integrate is as follows:

transfer out perú diagrama inglés flujo payment disbursement to bank accounts (4)

Product in beta version 🔐👨‍💻

We are working on our beta version. Stay tuned for its official release! You can also contact your account manager for more information.

Direct Integration (100% API)

Important

This processing method requires your merchant to be PCI Compliance.

1. (Optional) Obtain a one-time or subscription payment token

Before requesting the transfer of funds, you can tokenize the recipient's card. This can be done through the following services:

Get Card Payout Token: Generates a unique payment token for a transaction.

Get Subscription Token: Generates a subscriptionId, allowing funds to be sent multiple times to the subscribed card.

The following is an example of the token request:

{
  "card": {
    "name": "Juan Hernández",
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "29"
  },
  "paymentType": "FD"
}

Note: If your merchant not PCI Compliance, you must use Kushki JS Hosted Fields to obtain a token from the front-end without handling sensitive data.

2. Request the Transfer of Funds to a Card

To send funds to a card, you must provide the card and recipient details, the amount, and the clientTransactionId , a unique identifier on your side. Check here for the full structure in our API reference.

Examples

JavaScript

Python

PHP

If the request is successful, you will receive the following response:

{
  "responseCode": "00",
  "responseText": "Approved and completed successfully",
  "ticketNumber": "XXXXXXX",
  "transactionReference": "XXXXXXXX",
  "otherDetails": {}
}

In case of an error, you will receive a response containing the code field and the details object, where you can check the reason for the rejection.

{
  "code": "E001",
  "details": {
    "Origin": "PushFundsService",
    "Message": "paymentType: must be a valid value."
  }
}

To send funds to tokenized (subscribed) cards, check here for the structure

3. Check the Transaction Status

You can verify the status of a transaction in two ways:

1. Check via the API Get Transaction Status
You only need to send the transactionReference or clientTransactionId. The response will include the following information:

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

2. Webhook Configuration
You can set up a webhook to receive notifications for approved or declined transactions.
Check here for the full webhook structure.

You can also include the webhook object in the direct fund transfer request via API to receive transaction status notifications.

Integration via Kushki.js Hosted Fields

This is an ideal integration for non-PCI compliance merchants.

With Hosted Fields, you can securely collect card and cardholder information through fields hosted on Kushki's infrastructure. It returns a payout token that allows you to continue with the payment flow from the back-end

With the implementation of this library, you can obtain two types of tokens:

One-time payment token:: for making a single payment to a card

Subscription token: can be reused for multiple payments to a credit or debit card. You will receive a suscriptionId instead of a token.

1. Import Kushki.js Hosted Fields into your application

Option 1 - CDN

Import the Kushki.js Hosted Fields library into your application via a <script> tag within the <body> tag. Once imported, you will be able to access the resources described later to create a card payout flow with Kushki..

You need to import both the kushki.min.js library (which contains the code necessary to store your merchant credentials) and the card.min.js library (which contains the functionality needed for the card payout flow).

Option 2 - NPM

Install the Kushki.js Hosted Fields library as an npm package inside your application with the following code:

npm install --save @kushki/js-sdk

Option 3 - YARN

yarn install @kushki/js-sdk

Create an instance of KushkiOptions

To use the Kushki.js Hosted Fields library, you first need to create an instance of KushkiOptionswhich allows you to declare the merchant's public key and select the environment (test or production) using the init() method.

When your merchant account is ready to process real payments, make sure to replace the test key with the production key

Add the following code to your application:

Check the reference for more information about the KushkiOptions instance.

2. Initialize the Form on the Front-End

Follow the steps below to render server-side fields on your site. This way, your users will be able to send money to cards.

Step 1. Define containers for the server-side fields.

Before calling the initCardPayoutToken(), method, it is required to place the necessary elements to render each field server-side.

Step 2. Create an instance of CardPayoutOptions with the transaction information

Render Server-Side Fields with the initCardPayoutToken Method

After creating an instance of kushkiOptions, you need to call the initCardPayoutToken() function to initialize an instance of ICardPayouts

Check the reference for the hosted fields library for more information on form initialization.

Styles

Follow the same methodology used in Estilos de Token de Tarjeta. he key difference is that these styles specifically apply to the fields required for this tokenization method. Also, note that the isSubscription field is a checkbox, so specific styles must be applied for this type of input. For more details, click here.

Events

Use the same approach as in Eventos de Token de Tarjeta. However, these events apply to the specific fields required for this tokenization method. For more details, clic here.

3. Request a Card Payout Token

To obtain a card payment token, call th requestCardPayoutToken method on the previously initialized ICardPayouts instance. This method will also validate whether the fields contain valid values; if not, it will throw an exception.

This method returns a CardPayoutTokenResponse, object, which you must send to your backend to proceed with the fund transfer.

Option 1. Subscription Token If theisSubscription field is checked, the response will be of type CardPayoutSubscriptionTokenResponse and will include a subscriptionId.

Option 2. One-Time Token: : Otherwise, it will return a CardPayoutUniqueTokenResponse with a one-time-use token.

4. Configure Your Backend

The backend is responsible for receiving the token (or subscription ID) obtained from your front-end and initiating the payment process with Kushki.

When the user submits the card and cardholder details through the form you've specified, your front-end will return a token or a suscriptionId. With this token, you will need to call our Push Funds endpoints to process the payment to the card.

One-Time Payment Token

If it is a one-time payment token, you should call the payouts/card/v1/pushFunds. service. Make sure you include the token in the body, along with the amount and other necessary information.

JavaScript

Python

PHP

You can find more information in the API Reference.

Subscription Token

If it is a subscription token, you should call the service /payouts/card/subscriptions/pushFunds/{subscriptionId}. Make sure to include the subscriptionId as a path parameter and in the body, provide the amount and other information as shown in the following example.

JavaScript

Python

PHP

You can find more information in the API Reference.

Optional: Delete a Subscribed Card

This step allows you to remove a previously subscribed card by sending the subscriptionId. Once deleted, no further fund transfers can be made to that card. More information here.

Test Your Integration

There are test cards you can use in the UAT environment to ensure your integration is ready.

Visa

Valid Card

Declines: 4242424242424242

Approves: 4957030420210454

Invalid Card: 4104920120500001

Mastercard

Valid Card:5252525252525252

Invalid Card:5204750000000003

Simulate response scenarios using specific amounts

During testing, you can simulate different error scenarios by sending specific values in the totalAmount field. This applies to both the Push Funds operation and Push Funds in subscriptions.

The following table shows the behavior by brand and amount:

Brand	Amount (`totalAmount`)	Response	Code	Message	Note
VISA	10	DECLINE	501	Transaction declined. Please contact your card issuer.
MASTERCARD	10	DECLINE	501	Transaction declined. Please contact your card issuer.
VISA	20	DECLINE	504	The entered card has been reported.
MASTERCARD	20	DECLINE	514	The entered card number is not valid.
VISA	30	DECLINE	541	This card has been reported as lost.
MASTERCARD	30	DECLINE	543	This card has been reported as stolen.
VISA	40	ERROR	E027	A timeout occurred when sending the request to the card network.	Timeout with declined transaction
MASTERCARD	40	ERROR	E027	A timeout occurred when sending the request to the card network.	Timeout with declined transaction
VISA	50	ERROR	E027	A timeout occurred when sending the request to the card network.	Timeout with approved transaction
MASTERCARD	50	ERROR	E027	A timeout occurred when sending the request to the card network.	Timeout with approved transaction

These test amounts should only be used in sandbox environments to simulate specific payment engine responses. Any other amount will be treated as approved.

Direct Integration (100% API)#

1. (Optional) Obtain a one-time or subscription payment token#

2. Request the Transfer of Funds to a Card#

Examples#

3. Check the Transaction Status#

Integration via Kushki.js Hosted Fields#

1. Import Kushki.js Hosted Fields into your application#

Option 1 - CDN#

Option 2 - NPM#

Option 3 - YARN#

Create an instance of KushkiOptions#

2. Initialize the Form on the Front-End#

Step 1. Define containers for the server-side fields.#

Step 2. Create an instance of CardPayoutOptions with the transaction information#

Render Server-Side Fields with the initCardPayoutToken Method#

Styles#

Events#

3. Request a Card Payout Token#

4. Configure Your Backend#

One-Time Payment Token#

Subscription Token#

Optional: Delete a Subscribed Card#

Test Your Integration#

Visa#

Mastercard#

Simulate response scenarios using specific amounts#

Direct Integration (100% API)

1. (Optional) Obtain a one-time or subscription payment token

2. Request the Transfer of Funds to a Card

Examples

3. Check the Transaction Status

Integration via Kushki.js Hosted Fields

1. Import Kushki.js Hosted Fields into your application

Option 1 - CDN

Option 2 - NPM

Option 3 - YARN

Create an instance of KushkiOptions

2. Initialize the Form on the Front-End

Step 1. Define containers for the server-side fields.

Step 2. Create an instance of CardPayoutOptions with the transaction information

Render Server-Side Fields with the initCardPayoutToken Method

Styles

Events

3. Request a Card Payout Token

4. Configure Your Backend

One-Time Payment Token

Subscription Token

Optional: Delete a Subscribed Card

Test Your Integration

Visa

Mastercard

Simulate response scenarios using specific amounts