Payment Distribution to Bank Accounts

October 23, 2024

Distribute payments to your customers' bank accounts.

Distributing payments by wire transfer means delivering money to bank accounts. Put another way, if you already have your customers’ or assistants’ bank information or cell phone number (if you had configured Transfiya), you can use your Kushki Payout account to deposit money directly in their accounts through wire transfer by using the logic you prefer.

This is ideal for:

• Payments for suppliers or sellers
• Marketplaces
• Delivery applications

Operation details by Transfiya

It is a solution for Colombia, which allows real-time business-to-customer (B2C) bank transfers between the main banking entities in Colombia.

Unlike ACH cycles, if the user is registered with Transfiya, might occur the following scenarios:

• Transfer by bank account number: the money is transfer in real time to the account. If the account number does not exist or despite belonging to a financial institution with Transfiya, the account is not associated with this service, the transaction will be rejected.
• Transfer by cell phone number: if the user only has one account associated with the cell phone number, the transfer will be made immediately. In case of having more than one, the user has 12 hours to authorize the transaction in any of the [available banks](https ://www.transfiya.com.co/home). The money is instantly transferred to the user’s account after it has been approved.

The disbursement process by Transfiya is carried out following the flow that appears below: Merchant > Kushki > Transfiya > Bank > User.

What happens if the user has several accounts associated with the same cell phone number?

If the user has more than one account associated with the cell phone number, all the transfers made to a natural person, will be accepted from any of the banking entities associated with their cell phone number in Transfiya. They will have 12 hours to accept the transfer.

Operation details by bank

The disbursement process in Colombia is carried out following the flow that appears below: Merchant > Kushki > Bank > User.

Flow

The payment flow that you will integrate is as shown below:

Here you will learn how to start with payment disbursement.

1. Obtain the List of Associated Banks

It is important that you make sure all the banks to which you will make the transfers are in the associated banks list. We recommend you check the information of the list of associated banks using our bank list endpoint.

var request = require('request');
var bankList = [];
var options = {
  'method': 'GET',
  'url': 'https://api-uat.kushkipagos.com/payouts/transfer/v1/bankList', // Test environment
  'headers': {
    'Public-Merchant-Id': '' // Replace with your Public Key
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
  bankList = response.body;
  // Submit your code to filter the bank you need and send its id in token request
});

import requests

url = "https://api-uat.kushkipagos.com/payouts/transfer/v1/bankList" // Test environment
bankList = []

payload = {}
headers = {
  'Public-Merchant-Id': ''  // Replace with your Public Key
}

response = requests.request("GET", url, headers=headers, data = payload)

print(response.text.encode('utf8'))
bankList = response.text

// Submit your code to filter the bank you need and send its id in token request

$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-uat.kushkipagos.com/payouts/transfer/v1/bankList'); // Test environment
$request->setRequestMethod('GET');
$request->setOptions(array());
$request->setHeaders(array(
  'Public-Merchant-Id' => '' // Replace with your Public Key
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
bankList = $response->getBody();
// Submit your code to filter the bank you need and send its id in token request

2. Tokenize Data

Once you have obtained the bank code where the transfer will be received, or you have Transfiya configured and the recipient’s cell phone number, you should make the token request by using our tokenization endpoint.

Required fields to obtain the token

Please note the required fields in the body of the request depending on whether you are going to disperse to an account number directly or if you had configured Transfiya through a cellphone number:

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens', // Test environment
  'headers': {
    'Public-Merchant-Id': '', // Replace with your Public Key
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "documentNumber":"123456789",
      "accountNumber":"99999",
      "accountType":"CC",
      "bankId":"000051",
      "totalAmount":49.99,
      "documentType":"NIT",
      "currency":"COP",
      "name":"John Doe"
    })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
  // Submit your code to send the token you received to the next request
});

import requests

url = "https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens" // Test environment

payload = "{\n  \"documentNumber\": \"123456789\",\n  \"accountNumber\": \"99999\",\n  \"accountType\": \"CC\",\n  \"bankId\": \"000051\",\n  \"totalAmount\": 49.99,\n  \"documentType\": \"NIT\",\n  \"currency\": \"COP\",\n \"name\": \"John Doe\"\n}"
headers = {
  'Public-Merchant-Id': '', // Replace with your Public Key
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

// Submit your code to send the token you received to the next request

$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens'); // Test environment
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
  "documentNumber": "123456789",
  "accountNumber": "99999",
  "accountType": "CC",
  "bankId": "000051",
  "totalAmount": 49.99,
  "documentType": "NIT",
  "currency": "COP",
  "name": "John Doe"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Public-Merchant-Id' => '', // Replace with your Public Key
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
// Submit your code to send the token you received to the next request

3. Initializing the Transaction

In this step, you should have obtained a token and can start the disbursement process with Kushki. You have to make a call to our initialization endpoint to start the payment.

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api-uat.kushkipagos.com/payouts/transfer/v1/init', // Test environment
  'headers': {
    'Private-Merchant-Id': '', // Replace with your Private Key
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount":{
    "subtotalIva":0,
        "subtotalIva0":49.99,
        "iva":0
    },
    "token":"53de1cb6bbb54011a0a98053d48677e0" // Replace with the token you received
    })
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests

url = "https://api-uat.kushkipagos.com/payouts/transfer/v1/init" // Test environment

payload = "{\n  \"amount\": {\n    \"subtotalIva\": 0,\n    \"subtotalIva0\": 49.99,\n    \"iva\": 0\n  },\n  \"token\": \"53de1cb6bbb54011a0a98053d48677e0\"\n}" // Replace with the token you received
headers = {
  'Private-Merchant-Id': '', // Replace with your Private Key
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api-uat.kushkipagos.com/payouts/transfer/v1/init'); // Test environment
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 49.99,
    "iva": 0
  },
  "token": "53de1cb6bbb54011a0a98053d48677e0" // Replace with the token you received
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Private-Merchant-Id' => '', // Replace with your Private Key
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

In the response a ticket number and a status are issued for the transaction.

4. Track the Transaction Status (Optional)

Now that the transfer is about to be processed, you can find out the transaction status via Webhooks or manually, by using our API.

Webhooks

The transaction status is automatically notified at the time when the money has been deposited in the bank account.

API

You can use our Get Status in our API to manually track the status of a specific transaction.

5. Test your Integration

You may use some test identification document numbers in test mode to ensure that your integration is ready.

• Approved transaction: 123456789
• Declined transaction: 999999990

6. Prepare your Certification

Read the following guidelines for technical certification approval (required to obtain productive account credentials):

• Tax calculations must be correct.
• Messages displayed on the screen should be aligned with Kushki’s responses.
• Save and record all the responses delivered by Kushki (required if you need support).
• If there’s no requirement for sending a reference voucher to the customer’s mail, you don’t need to specify an email address in the token request.
• If webhook notifications are received correctly, respond to the request with a status 200.
• The payment button must be disabled after the first click.
• Kushki’s logo must be visible for the customer. You can find our logo in several formats here.
• Make sure that in the body of the request all the fields required in the API Reference are included.