Payment disbursement to bank accounts

August 08, 2024

Disburse payments to your customers' or vendor's bank accounts

Payment disbursement 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 disbursement 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 disbursement process in Peru is carried out through the following flow: Merchant > Kushki > Processor > User.

Parameters	Details
Processing Hours	Monday to Friday from 7:00 to 20:00. Saturdays from 7:00 to 14:30. Sundays and holidays no transactions are processed.
Processing days	Monday to Saturday
Time to approve a transaction to BCP accounts	Up to 40 minutes
Time to approve a transaction to other banks	Amount less than S/. 420,000.00: If transactions are completed before 12:00 noon, payment is made the same day. After 12:00 noon, they are paid the next business day.
Notification of final status	The bank will notify once the funds have been credited to the recipient
Minimum amount per transaction	S/. 1.00
Maximum amount per transaction	To BCP accounts: no maximum limit
To other banks: S/. 420,000.00
Available accounts (for receiving money)	Business accounts and personal accounts

Supported currencies

The transfer out service in Peru is available in local currency (PEN).

Flow

The flow that you will integrate is shown below:

Flujo transfer out Peru

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":"John Doe",
      "documentNumber":"19885521",
      "accountNumber":"06",
      "accountType":"CA",
      "bankId":"002",
      "totalAmount":30,
      "documentType":"RUC",
      "currency":"PEN",
      "paymentDescription": "A short description of the payment",
      "mail": "user@example.com"
    })

};
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"
payload = {
    "documentNumber": "70274647",
    "accountNumber": "00230513322677808816",
    "accountType": "CA",
    "bankId": "002",
    "totalAmount": 30,
    "documentType": "DNI",
    "currency": "PEN",
    "paymentDescription": "A short description of the payment",
    "name": "Prueba Peru",
    "mail": "user@example.com"
}
headers = {
    "Public-Merchant-Id": "",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

<?php
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-uat.kushkipagos.com/payouts/transfer/v1/tokens",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'documentNumber' => '70274647',
    'accountNumber' => '00230513322677808816',
    'accountType' => 'CA',
    'bankId' => '002',
    'totalAmount' => 30,
    'documentType' => 'DNI',
    'currency' => 'PEN',
    'paymentDescription' => 'A short description of the payment',
    'name' => 'Prueba Peru',
    'mail' => 'user@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Content-Type: application/json",
    "Public-Merchant-Id: "
  ],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

3. Initialize the transaction

In this step, you should have obtained a token, and then you will be able to start the distribution process with Kushki. You will need to make a call to our initialization endpoint to process the 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":100,
        "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\": 100,\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": 100,
    "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 when the money has been deposited in the bank account.

API

In our API, you can use our Get Status endpoint 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.

Account number: 00316301312597216937 Identification number: 70015100 Identification type: DNI Account type: CA Bank identification number:003

6. Prepare your certification

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

Display messages on screen according to Kushki’s answers.
Save and log all Kushki responses (required in case support is needed).
If webhook notifications are received successfully, respond to the request with a status 200.
Make sure that in the body of the request all the fields required in the API reference are included.

Accept webhooks

Handle postpaid events the right way.