Payouts

Transactpay’s Payouts API enables fast, secure disbursements to bank accounts. It includes tools to validate recipients, initiate payments (single or bulk), and track payout status.

---

🔍 1. Name Enquiry – Validate Recipient Account

Use this endpoint to verify a recipient’s account name before sending money.

• Method: POST

• Endpoint:

  HTTP

  https://payment-api-service.transactpay.ai/payout/name-enquiry

🛠 Required Headers

Header	Type	Required	Description
api-key	string	✅ Yes	Your Transactpay public API key
encryption	string	✅ Yes	Use RSA (PKCS#1 v1.5) to encrypt data

📦 Sample Payload for NGN

JSON

{
  "bankCode": "000033", //6 digit NIP Bank Code
  "accountNumber": "0000000000"
}

✅ Sample Response for NGN

JSON

{
    "bankCode": "000033",
    "accountNumber": "0000000000",
    "accountName": "ACCOUNT NAME"
}

📦 Sample Payload for KES

JSON

{
  "bankCode": "MPESA", 
  "accountNumber": "[phone]"
}

✅ Sample Response for KES

JSON

{
    "bankCode": "MPESA",
    "accountNumber": "254123456789",
    "accountName": "ACCOUNT NAME"
}

⚠️

Note:

Ensure the payload is encrypted using RSA/PKCS#1 v1.5.

---

🚀 2. Initiate Payout – Send Money to Bank Account(s)

This endpoint allows single or multiple payouts in one request.

• Method: POST

• Endpoint:

  HTTP

  https://payment-api-service.transactpay.ai/payout/initiate

📦 Sample Payload for NGN Payouts

JSON

{
    "payoutDetails": [
        {
            "clientReference": "yourReference", //for merchant reference
            "accountNumber": "0000000000",
            "bankCode": "000033", //6 digit NIP Bank Code
            "amount": 5000,
            "description": "Vendor Payment",
            "accountName": "John Doe",
            "creditCurrency": "NGN",
            "debitCurrency": "NGN"
        }
    ]
}

📦 Sample Payload for KES Payouts

JSON

{
    "payoutDetails": [
        {
            "clientReference": "YourReference", //for merchant reference
            "accountNumber": "254111111111",
            "bankCode": "KES",
            "amount": 5000,
            "description": "Vendor Payment",
            "accountName": "John Doe",
            "creditCurrency": "KES",
            "debitCurrency": "KES"
        }
    ]
}

📦 Sample Payload for GHS Payout

JSON

{
    "payoutDetails": [
        {
            "clientReference": "YourReference", //for merchant reference
            "accountNumber": "0240000000",
            "bankCode": "MTN",
            "amount": 5000,
            "description": "Vendor Payment",
            "accountName": "John Doe",
            "creditCurrency": "GHS",
            "debitCurrency": "GHS"
        }
    ]
}

📦 Sample Payload for XOF Payout

📘

XOF Account Number Format

For XOF payouts, the accountNumber must not include the country calling code.

For example, if the full phone number is 22612345678, send only the local account number:

JSON

{
  "accountNumber": "012345678"
}

Do not send:

JSON

{
  "accountNumber": "22612345678"
}

The accountNumber should contain the local recipient number without the country calling code.

JSON

{
    "payoutDetails": [
        {
            "clientReference": "YourReference", //for merchant reference
            "accountNumber": "012345678",
            "bankCode": "286",
            "amount": 5000,
            "description": "Vendor Payment",
            "accountName": "John Doe",
            "creditCurrency": "XOF",
            "debitCurrency": "XOF"
        }
    ]
}

ℹ️

Payout Providers

GHS

Use the following codes when initiating payouts in Ghanaian Cedis (GHS).

Code	Provider Name	Description
MTN	MTN Mobile Money	MTN Ghana mobile money wallet
VOD	Telecel Cash (formerly Vodafone Cash)	Telecel Ghana mobile money wallet
ATM	AirtelTigo Money	AirtelTigo mobile money wallet

XOF

Use the following provider codes when initiating payouts in West African CFA Franc (XOF).

Country	Provider Code	Provider Name
Benin	286	MTN Benin
Benin	418	Moov Benin
Burkina Faso	238	Moov Burkina Faso
Burkina Faso	240	Orange Burkina Faso
Côte d’Ivoire	432	MTN Côte d’Ivoire
Côte d’Ivoire	434	Moov Côte d’Ivoire
Côte d’Ivoire	430	Orange Côte d’Ivoire
Côte d’Ivoire	428	Wave Côte d’Ivoire
Mali	354	Moov Mali
Mali	352	Orange Mali
Senegal	340	Mix Senegal
Senegal	620	Orange Money Senegal
Senegal	618	Wave Senegal
Togo	164	TMoney Togo

✅ Sample Response

JSON

{
    "data": [
        {
            "accountName": "John Doe",
            "accountNumber": "0000000000",
            "bankCode": "000033",
            "bankId": 0,
            "amount": 5000.0,
            "description": "Vendor Payment",
            "category": null,
            "payoutReference": "PGW-PAYOUT-123BFF4569804335B4E649FAB51F3D42",
            "creditCurrency": "NGN",
            "debitCurrency": "NGN",
            "beneficiayAddress": null
        }
    ],
    "batchId": 13726,
    "batchReference": "PGW-BATCH-1A238E91B41230A4A9C080456E805B79",
    "status": "success",
    "statusCode": "00",
    "message": "Your payout has been logged for processing"
}

👍

Supports bulk disbursements using multiple objects in payoutDetails.

---

🔄 3. Payload Status – Track Payout Progress

Use this endpoint to check the status of a previously submitted payout.

• Method: GET

• Header Value: Your-Secret-Key

• Endpoint Format:

  HTTP

  https://payment-api-service.transactpay.ai/payout/requery?clientReference=yourReference

Replace {yourReference} with the actual reference from the initiate response.

✅ Sample Response

JSON

{
    "message": "Payout details received successfully",
    "code": "00",
    "status": true,
    "data": {
        "accountNumber": "0000000000",
        "accountName": "John Doe",
        "bankName": "Transactpay Bank",
        "providerReference": "999999200617171025595259900000",
        "amount": 5000.00,
        "responseMessage": "Transaction successful",
        "responseCode": "00",
        "clientReference": "yourReference",
        "status": "Successful"
    }
}

✅

Best Practice:

Always verify the status before confirming success in your application.