Get Payout Status

Check the status of a disbursement to see if it has been completed, failed, or is still processing.

Endpoint

1GET /api/v1/disbursements/:id

Path Parameters

Parameter	Type	Description
`id`	string	Payout ID from the execute disbursement response

Response

1{
2  "payout": {
3    "id": "payout-uuid",
4    "merchantId": "merchant-uuid",
5    "gateway": "MTN_MOMO",
6    "amount": "5000.00",
7    "currency": "XAF",
8    "status": "SUCCESS",
9    "recipient": {
10      "msisdn": "+237612345678"
11    },
12    "gatewayReference": "MTN_REF_123456789",
13    "gatewayFee": "50.00",
14    "platformFee": "100.00",
15    "totalAmount": "5150.00",
16    "createdAt": "2024-01-15T10:00:00.000Z",
17    "completedAt": "2024-01-15T10:01:00.000Z",
18    "error": null
19  }
20}

Response Fields

Field	Type	Description
`payout.id`	string	Unique identifier for the payout
`payout.merchantId`	string	Your merchant ID
`payout.gateway`	string	Payment gateway used (MTN_MOMO, ORANGE_MONEY)
`payout.amount`	string	Payout amount
`payout.currency`	string	Currency code
`payout.status`	string	Current status (PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED)
`payout.recipient.msisdn`	string	Recipient phone number
`payout.gatewayReference`	string	Reference from the mobile money provider
`payout.gatewayFee`	string	Fee charged by the gateway
`payout.platformFee`	string	ZoPay platform fee
`payout.totalAmount`	string	Total amount paid (amount + fees)
`payout.createdAt`	string	Payout creation timestamp
`payout.completedAt`	string	Payout completion timestamp (null if still processing)
`payout.error`	object \| null	Error details if payout failed

Status Values

PENDING: Payout initiated, awaiting processing
PROCESSING: Payout is being processed by the gateway
SUCCESS: Payout completed successfully
FAILED: Payout failed (check the error field for details)
CANCELLED: Payout was cancelled

Example Request

1const payoutId = 'payout-uuid-from-execute-response';
2
3const response = await fetch(`https://api.zopay.com/api/v1/disbursements/${payoutId}`, {
4  method: 'GET',
5  headers: {
6    'x-zo-key': apiKey,
7    'x-zo-timestamp': timestamp,
8    'x-zo-nonce': nonce,
9    'x-zo-origin': origin,
10    'x-zo-signature': signature,
11    'x-zo-version': '1.0'
12  }
13});
14
15const data = await response.json();
16console.log('Payout Status:', data.payout.status);
17console.log('Amount:', data.payout.amount);

Polling Strategy

If a payout is in PROCESSING status, you may want to poll this endpoint periodically until it reaches a final state (SUCCESS, FAILED, or CANCELLED). However, we recommend using webhooks instead of polling for better efficiency.

ℹ️

Best Practice: Instead of polling, set up webhooks to receive real-time notifications when payouts complete. This is more efficient and reduces API calls.

Error Handling

If a payout fails, the error field will contain details about what went wrong. Common error scenarios include:

Invalid recipient phone number
Insufficient funds in your account
Gateway service unavailable
Recipient account not found or inactive

Next Steps

Learn more about:

Listing all payouts
Setting up webhooks for real-time notifications

PreviousExecute

NextList Payouts

Parameter

Type

Description

id

string

Payout ID from the execute disbursement response

Response

1{
2  "payout": {
3    "id": "payout-uuid",
4    "merchantId": "merchant-uuid",
5    "gateway": "MTN_MOMO",
6    "amount": "5000.00",
7    "currency": "XAF",
8    "status": "SUCCESS",
9    "recipient": {
10      "msisdn": "+237612345678"
11    },
12    "gatewayReference": "MTN_REF_123456789",
13    "gatewayFee": "50.00",
14    "platformFee": "100.00",
15    "totalAmount": "5150.00",
16    "createdAt": "2024-01-15T10:00:00.000Z",
17    "completedAt": "2024-01-15T10:01:00.000Z",
18    "error": null
19  }
20}

Response Fields

Field

Type

Description

payout.id

string

Unique identifier for the payout

payout.merchantId

string

Your merchant ID

payout.gateway

string

Payment gateway used (MTN_MOMO, ORANGE_MONEY)

payout.amount

string

Payout amount

payout.currency

string

Currency code

payout.status

string

Current status (PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED)

payout.recipient.msisdn

string

Recipient phone number

payout.gatewayReference

string

Reference from the mobile money provider

payout.gatewayFee

string

Fee charged by the gateway

payout.platformFee

string

ZoPay platform fee

payout.totalAmount

string

Total amount paid (amount + fees)

payout.createdAt

string

Payout creation timestamp

payout.completedAt

string

Payout completion timestamp (null if still processing)

payout.error

object | null

Error details if payout failed

Example Request

1const payoutId = 'payout-uuid-from-execute-response';
2
3const response = await fetch(`https://api.zopay.com/api/v1/disbursements/${payoutId}`, {
4  method: 'GET',
5  headers: {
6    'x-zo-key': apiKey,
7    'x-zo-timestamp': timestamp,
8    'x-zo-nonce': nonce,
9    'x-zo-origin': origin,
10    'x-zo-signature': signature,
11    'x-zo-version': '1.0'
12  }
13});
14
15const data = await response.json();
16console.log('Payout Status:', data.payout.status);
17console.log('Amount:', data.payout.amount);

Polling Strategy

ℹ️

Best Practice: Instead of polling, set up webhooks to receive real-time notifications when payouts complete. This is more efficient and reduces API calls.