Bank Payout

Step 1 - Initiate

This API method is used to initiate a disbursement/payout request for which you will receive a JSON response.

POST {base url}/api/v1/payouts/

Headers

Name	Type	Description
Authorization*		Bearer Token
Token*	String	{{secret key}}
Content-Type*	String	application/json

201: Created

The JSON response includes a {{execution_url}} to be utilized in (Step 2).

Payload

{
    "client": {
        "email": "[e-mail]",
        "phone": "751123456"
    },
    "payment": {
        "currency": "NGN",
        "amount": "10",
        "description": "Test Payout bank transfer ACCESS_BANK "
    },
    "brand_id": "{{brand id}}"
}

Response

{
  "payment": {
    "is_outgoing": true,
    "payment_type": "payout",
    "amount": 10,
    "currency": "NGN",
    "net_amount": 10,
    "fee_amount": 0,
    "pending_amount": 0,
    "pending_unfreeze_on": null,
    "description": "Test Payout bank transfer ACCESS_BANK",
    "paid_on": null,
    "remote_paid_on": null,
    "owned_bank_account_id": null,
    "owned_bank_account": null,
    "owned_bank_code": null
  },
  "client": {
    "client_type": null,
    "email": "[e-mail]",
    "phone": "751123456",
    "full_name": "",
    "personal_code": "",
    "legal_name": "",
    "brand_name": "",
    "registration_number": "",
    "tax_number": "",
    "bank_account": "",
    "bank_code": "",
    "street_address": "",
    "city": "",
    "zip_code": "",
    "country": "",
    "state": "",
    "shipping_street_address": "",
    "shipping_city": "",
    "shipping_zip_code": "",
    "shipping_country": "",
    "shipping_state": "",
    "cc": [],
    "bcc": [],
    "delivery_methods": [
      {
        "method": "email",
        "options": {}
      },
      {
        "method": "text_message",
        "options": {
          "custom_message": ""
        }
      }
    ]
  },
  "transaction_data": {
    "payment_method": "",
    "flow": "payform",
    "extra": {},
    "country": "",
    "attempts": []
  },
  "reference_generated": "182",
  "reference": "",
  "status": "initialized",
  "status_history": [
    {
      "status": "initialized",
      "timestamp": 1688378279
    }
  ],
  "sender_name": "",
  "recipient_card_country": "",
  "recipient_card_brand": null,
  "execution_url": "https://gate.paytota.com/po/8a5dc927-d393-4c18-8dce-1ff357e51235/imalipay_payouts/",
  "brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
  "company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
  "is_test": false,
  "user_id": null,
  "created_on": 1688378279,
  "updated_on": 1688378279,
  "type": "payout",
  "id": "8a5dc927-d393-4c18-8dce-1ff357e51235"
}

Curl

curl --location --globoff '{{base_url}}/api/v1/payouts/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Secret Key}}' \
--data-raw '{
    "client": {
        "email": "[e-mail]",
        "phone": "751123456"
    },
    "payment": {
        "currency": "NGN",
        "amount": "10",
        "description": "Test Payout bank transfer ACCESS_BANK "
    },
    "brand_id": "{{brand id}}"
}'

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{{base_url}}/api/v1/payouts/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "client": {
        "email": "[e-mail]",
        "phone": "751123456"
    },
    "payment": {
        "currency": "NGN",
        "amount": "10",
        "description": "Test Payout bank transfer ACCESS_BANK "
    },
    "brand_id": "{{brand id}}"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {{Secret Key}}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

NodeJs

const axios = require('axios');
let data = JSON.stringify({
  "client": {
    "email": "[e-mail]",
    "phone": "751123456"
  },
  "payment": {
    "currency": "NGN",
    "amount": "10",
    "description": "Test Payout bank transfer ACCESS_BANK "
  },
  "brand_id": "{{brand id}}"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{base_url}}/api/v1/payouts/',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{Secret Key}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python

import http.client
import json

conn = http.client.HTTPSConnection("{{base_url}}")
payload = json.dumps({
  "client": {
    "email": "[e-mail]",
    "phone": "751123456"
  },
  "payment": {
    "currency": "NGN",
    "amount": "10",
    "description": "Test Payout bank transfer ACCESS_BANK "
  },
  "brand_id": "{{brand id}}"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{Secret Key}}'
}
conn.request("POST", "/api/v1/payouts/", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

Step 2 - Execute

Utilize the {{execution_url}} obtained in step 1 to submit a second request.

POST {{execution_url}}

Headers

Name	Type	Description
Content-Type*	String	application/json
Authorization*	String	Bearer Token
Token*	String	{{secret key}}

201: Created

The supported banks(Account Institution) are below.

Nigeria

• FIRST_BANK

• ACCESS_BANK

• GT_BANK

• ZENITH_BANK

• ECOBANK

• UBA

• UNION_BANK

• STANBIC_BANK

• STERLING_BANK

• STANDARD_CHARTERTED

• FIDELITY_BANK

• WEMA_BANK

• PROVIDUS_BANK

Kenya

BOA

ABSA

STANBIC

KCB

CITIBANK

GTB

EQUITY

ECOBANK

FAMILY

Payload

For Kenya, the payment mode will be "B2B," and the country will be "Kenya."

{
    "accountNumber": "1234567890",
    "accountInstitution": "ACCESS_BANK",
    "paymentMode": "BANK_TRANSFER",
    "country": "Nigeria"
}

Response

{
	"detail": "pending",
	"status": "pending"
}

Curl

curl --location --globoff '{{execution_url}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{Secret Key}}' \
--data '{
    "accountNumber": "{{Account Number}}",
    "accountInstitution": "{{Account Institution}}"
}'

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '{{execution_url}}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "accountNumber": "{{Account Number}}",
    "accountInstitution": "{{Account Institution}}"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer {{Secret Key}}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

NodeJs

const axios = require('axios');
let data = JSON.stringify({
  "accountNumber": "{{Account Number}}",
  "accountInstitution": "{{Account Institution}}"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: '{{execution_url}}',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer {{Secret Key}}'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python

import http.client
import json

conn = http.client.HTTPSConnection("{{execution_url}}")
payload = json.dumps({
  "accountNumber": "{{Account Number}}",
  "accountInstitution": "{{Account Institution}}"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{Secret Key}}'
}
conn.request("POST", "/", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

You will receive a callback on your webhook URL regarding the status of the transaction

Successful transaction  (status = success)
Failed transaction (status = error)

Callback Example

{
  "id": "2eb911cc-2541-4f8c-9fa5-22c10ad33280",
  "type": "payout",
  "client": {
    "cc": [],
    "bcc": [],
    "city": "",
    "email": "[e-mail]",
    "phone": "700123123",
    "country": "",
    "zip_code": "",
    "bank_code": "",
    "full_name": "",
    "brand_name": "",
    "legal_name": "",
    "tax_number": "",
    "client_type": null,
    "bank_account": "",
    "personal_code": "",
    "shipping_city": "",
    "street_address": "",
    "shipping_country": "",
    "shipping_zip_code": "",
    "registration_number": "",
    "shipping_street_address": ""
  },
  "status": "success",
  "is_test": false,
  "payment": {
    "amount": 500,
    "paid_on": 1668084960,
    "currency": "UGX",
    "fee_amount": 0,
    "net_amount": 500,
    "description": "Test paytota",
    "is_outgoing": true,
    "payment_type": "payout",
    "pending_amount": 0,
    "remote_paid_on": 1668084960,
    "owned_bank_code": null,
    "owned_bank_account": null,
    "pending_unfreeze_on": null,
    "owned_bank_account_id": null
  },
  "user_id": null,
  "brand_id": "edd6c020-eac6-4b4e-9716-47928f3401de",
  "reference": "",
  "company_id": "706d0675-b131-468c-940d-bc0ea3599e7f",
  "created_on": 1668084945,
  "event_type": "payout.success",
  "updated_on": 1668084960,
  "sender_name": "",
  "execution_url": "https://gate.paytota.com/po/2eb911cc-2541-4f8c-9fa5-22c10ad33280/airtel/",
  "status_history": [
    {
      "status": "initialized",
      "timestamp": 1668084945
    },
    {
      "status": "success",
      "timestamp": 1668084960
    }
  ],
  "transaction_data": {
    "flow": "server_to_server",
    "extra": {},
    "country": "",
    "attempts": [
      {
        "flow": "server_to_server",
        "error": null,
        "extra": {},
        "country": "",
        "client_ip": "",
        "fee_amount": 0,
        "successful": true,
        "payment_method": "airtel",
        "processing_time": 1668084960
      }
    ],
    "payment_method": "airtel"
  },
  "reference_generated": "104",
  "recipient_card_brand": "airtel",
  "recipient_card_country": ""
}

Check Disbursement/Payout Status

This API method is used to query the payouts/disbursement transaction status using the transaction ID.

GET {base url}/api/v1/payouts/{id}/

Headers

Name	Type	Description
Content-Type*	String	application/js
Authorization*	String	Bearer Tok
Token*	String	{{secret key}}

200: OK