Developers
HomeMerchantsDevelopers

Payouts - API Integration Guide

Integrate payouts seamlessly into your application with our robust API. Disburse funds securely to bank accounts, cards, or saved tokens using the N-Genius platform. Our comprehensive guide walks you through authentication, endpoints, and automation — so you can streamline your payment workflows with confidence.

Overview

Use the Payouts API to programmatically disburse funds to recipients via bank accounts, cards, saved tokens, or historical order references. Each payout is initiated by your server and processed securely via the N-Genius platform.

Authentication

All payout requests require a valid Bearer token obtained via the Authentication API. 

POST /identity/auth/access-token
Content-Type: application/vnd.ni-identity.v1+json

{
  "credentials": {
    "apiKey": "YOUR_API_KEY",
    "apiSecret": "YOUR_API_SECRET"
  }
}

Step-by-Step Integration

  1. Authenticate: Retrieve an access token
  2. Check your balance: Ensure your merchant account has sufficient payout funds
  3. Submit a Payout: Create the payout request with all required parameters
  4. Track Payout: Use the transaction reference to monitor status and outcome

API Endpoints

Action Endpoint
Authenticate /identity/auth/access-token
Check Balance /payouts/utilities
Merchant Payout Profile /payouts/utilities
Submit Payout /payouts/request
Track Transaction /transactions/{orderRef}

Payout Request Example

POST {BaseURL}/payouts/merchants/{OutletRef)/payouts



  
    

      Header
      Value
    

  
  
    

      Authorization
      Bearer {accessToken}
    

    

      Content-Type
      application/vnd.ni-payouts.v1+json
    

    

      Accept
      application/vnd.ni-payouts.v1+json
    

  


{
    "invoiceNumber": "invoice-23425667",
    "beneficiaryType": "CARD",
    "beneficiaryName": "Test User",
    "beneficiaryAccountNumber": "4093191766216474",
    "beneficiaryCountry": "AE",
    "beneficiaryAccountCurrency": "AED",
    "beneficiaryAddress": "Dubai",
    "beneficiaryEmail": "[email protected]",
    "beneficiaryMobileNumber": "0501234567",
    "transactionAmount": 0.5,
    "transactionCurrency": "AED",
    "transactionGroup": "Group 1",
    "transactionDescription": "Test transaction",
    "transactionPurposeCode": "CCP",
    "ultimateSenderName": "Network International LLC",
    "ultimateSenderAddress": "Dubai",
    "ultimateSenderCountry": "AE",
    "ultimateSenderPostCode": "000000",
    "ultimateSenderAddressType": "BIZZ"
}

Payout Response Example

{
    "reference": "ZYH2507024438RGE",
    "transactionType": "PAYOUT",
    "createdAt": "2025-07-02T08:33:48.443Z",
    "createdBy": "Payout Test 1 ",
    "status": "UNDER_SCREENING",
    "invoiceNumber": "invoice-23425667",
    "beneficiaryName": "Test User",
    "beneficiaryAccountNumber": "409319******6474",
    "beneficiaryBic": "ADCBAEAAXXX",
    "beneficiaryBankName": "ABU DHABI COMMERCIAL BANK",
    "beneficiaryAccountCurrency": "AED",
    "beneficiaryCountry": "AE",
    "beneficiaryAddress": "Dubai",
    "beneficiaryEmail": "[email protected]",
    "beneficiaryMobileNumber": "0501234567",
    "transactionAmount": 0.5,
    "transactionCurrency": "AED",
    "transactionGroup": "Group 1",
    "transactionDescription": "Test transaction",
    "transactionPurposeCode": "CCP",
    "ultimateSenderName": "Network International LLC",
    "ultimateSenderAddress": "Dubai",
    "ultimateSenderCountry": "AE",
    "ultimateSenderPostCode": "000000",
    "ultimateSenderAddressType": "BIZZ",
    "beneficiaryType": "CARD",
    "errors": {},
    "events": [
        {
            "eventName": "VALIDATION_PASSED",
            "timestamp": "2025-07-02T08:33:48.444Z",
            "payload": {}
        },
        {
            "eventName": "SCREENING_INITIATED",
            "timestamp": "2025-07-02T08:33:54.881325834Z",
            "payload": {}
        }
    ],
    "payoutFee": {
        "feeAmount": 0.1,
        "totalFee": 0.11,
        "calculationTime": "2025-07-02T08:33:54.881299834Z",
        "vatPercentage": 5,
        "applicableFeeType": "FIXED_FEE"
    },
    "depositOrWithdrawalIndicator": "Withdrawal",
    "holdForApproval": false
    }

Payout Destination Types

  • ACCOUNT: Direct to bank account (IBAN)
  • CARD: Credit/debit card (e.g., Visa, Mastercard)
  • SAVED_CARD: Vault token or previously stored card
  • ORDER_REF: Refund to source of a prior order

Purpose Codes

Each payout must include a purposeCode aligned with your merchant use case.

Code Description
REFRefund to original payment source
COMPartner/affiliate commission payout
LOALoan disbursement
RIMExpense reimbursements
DIVDividend or shareholder payments

Errors & Responses

  • 🟥 400 Bad Request: Missing or malformed field
  • 🟥 401 Unauthorized: Invalid or expired access token
  • 🟥 402 Payment Required: Insufficient balance
  • 🟥 422 Validation Error: Invalid beneficiary info or blocked payout type. Refer to the Field Validation Reference guide.

Developer Tools