Payment Distribution to Bank Accounts

August 15, 2024

Distribute payments to your customers or vendor's bank accounts.

Payment distribution by wire transfer consists of sending money to your customers’ accounts. In other words, if you have their bank details, you can use your Kushki distribution account and send the money to their accounts by wire transfer, using whatever logic you prefer.

This is ideal for:

Payments for suppliers or sellers
Marketplaces
Delivery applications

Operation details

The dispersion process in Mexico is done in the following way: Merchant > Kushki > Processor > User.

Parameter	Detail
Minimum amount	1 MXN
Maximum amount	No limit
Transaction approval time	Immediate (same bank and other banks)
Processing days	7 days a week
Processing hours	24/7
Types of recipient accounts available for sending wire transfers	- CLABE account - Debit card - Cell phone number**. (`accountType` and `accountNumber` parameters must be sent in the token request.)

** To send payments by cell phone number, the recipient of the transfer must have previously associated their deposit account to their cell phone number in their bank , either physically (bank branch) or electronically (bank’s mobile application).

Process Flow

The flow that you will integrate is shown below:

Transfer Out Mexico Flow

Here you will learn how to integrate money distributions by wire transfer.

1. Obtain the list of partner banks

The first step is to check the list of banks available to make the wire transfer. To do so, you must use this endpoint, which will show you the banking institutions available to make the transaction.

Javascript
Python
PHP

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

In response to this call, you will receive the name and code of the available banks. The latter must be sent in the transfer out token request.

2. Tokenize the information

After obtaining the bank code of the account where the transfer will be received, you have to request a token by using our transfer out token request endpoint.

Javascript
Python
PHP

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 you Public Key
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "name":"Juan Castro"
      "documentNumber":"ABCED12340013",
      "accountNumber":"646180110400000007",
      "accountType":"CB",
      "bankId":"0090",
      "totalAmount":1000,
      "documentType":"CURP",
      "currency":"MXN",
      "paymentDescription": "A short description of the payment"
    })

};
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 enviroment 

payload = "{\n  \"name\": \"Juan Castro\",\n \"documentNumber\": \"ABCED12340013\",\n  \"accountNumber\": \"646180110400000007\",\n  \"accountType\": \"CB\",\n  \"bankId\": \"0090\",\n  \"totalAmount\": 1000,\n  \"documentType\": \"CURP\",\n  \"currency\": \"MXN\",\n  \"paymentDescription\": \"A short description of the payment\" \n}"
headers = {
  'Public-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'))

// Submit your code to send the token 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('{
  "name": "Juan Castro"
  "documentNumber": "ABCED12340013",
  "accountNumber": "646180110400000007",
  "accountType": "CB",
  "bankId": "0090",
  "totalAmount": 1000,
  "documentType": "CURP",
  "currency": "MXN"
  "paymentDescription": "A short description of the payment"
}');
$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 received to the next request

3. Initialize the transaction

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

Javascript
Python
PHP

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":1000,
        "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\": 1000,\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": 1000,
    "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 close to being processed, you can check the transaction status via webhooks or manually, by using our API

Webhook

The transaction status is automatically notified at the time when the money has been deposited in the bank account. The webhook response will contain the variables processorStatus and processorStatusDescription within the metadata object with the final status of the distribution:

  "metadata": {
       "processorStatus": "LIQUIDADO",
       "contractID": "AB123",
       "processorStatusDescription": null
   },

See here the complete structure of the webhook of distribution by wire transfer.

API

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

5. Test your integration

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

Approved transaction

Account number: 646180110400000007
Identification number: 123456789
Identification type: CURP or RFC
Account type: CB

Cancelled transaction

Account number: 646180206800000003
Identification number: CADM9108029F4
Identification type: CURP or RFC
Account type: CB

Returned transaction

Account number: 646180206800000003
Identification number: CADM9108029G5
Identification type: CURP o RFC
Account type: CB

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.
All Kushki responses must be saved and recorded (required in case 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 to the customer. You can find our logo in various formats here.
Make sure that in the body of the request all the fields required in the API Reference are included.

Accept webhooks

Manage correctly post-payment events.