Execute Disbursement

After creating a quote, use this endpoint to process the actual payout to the recipient.

Endpoint

1POST /api/v1/disbursements/execute

Request Body

1{
2  "quote_id": "quote-uuid",
3  "idempotency_key": "unique-payout-123",
4  "recipient": {
5    "msisdn": "+237612345678"
6  }
7}

Request Parameters

Parameter	Type	Required	Description
`quote_id`	string	Yes	Quote ID from the create quote response
`idempotency_key`	string	Yes	Unique identifier to prevent duplicate payouts
`recipient`	object	Yes	Recipient information
`recipient.msisdn`	string	Yes	Recipient phone number in E.164 format

Response

1{
2  "payout_id": "payout-uuid",
3  "status": "PROCESSING",
4  "gateway_reference": "MTN_REF_123456789",
5  "correlation_id": "corr-uuid"
6}

Response Fields

Field	Type	Description
`payout_id`	string	Unique identifier for the payout (use this to check status)
`status`	string	Current payout status (PENDING, PROCESSING, SUCCESS, FAILED, CANCELLED)
`gateway_reference`	string	Reference from the mobile money provider
`correlation_id`	string	Correlation ID for tracking the transaction

Example Request

1const response = await fetch('https://api.zopay.com/api/v1/disbursements/execute', {
2  method: 'POST',
3  headers: {
4    'x-zo-key': apiKey,
5    'x-zo-timestamp': timestamp,
6    'x-zo-nonce': nonce,
7    'x-zo-origin': origin,
8    'x-zo-signature': signature,
9    'x-zo-version': '1.0',
10    'Content-Type': 'application/json'
11  },
12  body: JSON.stringify({
13    quote_id: 'quote-uuid-from-previous-step',
14    idempotency_key: 'unique-payout-123',
15    recipient: {
16      msisdn: '+237612345678'
17    }
18  })
19});
20
21const payout = await response.json();
22console.log('Payout ID:', payout.payout_id);
23console.log('Status:', payout.status);

Idempotency

The idempotency_key ensures that if you retry a request with the same key, the payout won't be processed twice. Use a unique identifier for each payout (e.g., UUID, timestamp + merchant reference).

ℹ️

Important: Payouts are processed asynchronously. The initial response may show a status of "PROCESSING". Use the payout ID to check the status later, or set up webhooks to receive notifications when the payout completes.

Next Steps

After executing a disbursement, you can:

Check the payout status using Get Status
View all payouts using List Payouts
Set up webhooks to receive real-time notifications

PreviousCreate Quote

NextGet Status

Request Body

1{
2  "quote_id": "quote-uuid",
3  "idempotency_key": "unique-payout-123",
4  "recipient": {
5    "msisdn": "+237612345678"
6  }
7}

Request Parameters

Parameter

Type

Required

Description

quote_id

string

Yes

Quote ID from the create quote response

idempotency_key

string

Yes

Unique identifier to prevent duplicate payouts

recipient

object

Yes

Recipient information

recipient.msisdn

string

Yes

Recipient phone number in E.164 format

Response

1{
2  "payout_id": "payout-uuid",
3  "status": "PROCESSING",
4  "gateway_reference": "MTN_REF_123456789",
5  "correlation_id": "corr-uuid"
6}

Response Fields

Field

Type

Description

payout_id

string

Unique identifier for the payout (use this to check status)

status

string

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

gateway_reference

string

Reference from the mobile money provider

correlation_id

string

Correlation ID for tracking the transaction

Example Request

1const response = await fetch('https://api.zopay.com/api/v1/disbursements/execute', {
2  method: 'POST',
3  headers: {
4    'x-zo-key': apiKey,
5    'x-zo-timestamp': timestamp,
6    'x-zo-nonce': nonce,
7    'x-zo-origin': origin,
8    'x-zo-signature': signature,
9    'x-zo-version': '1.0',
10    'Content-Type': 'application/json'
11  },
12  body: JSON.stringify({
13    quote_id: 'quote-uuid-from-previous-step',
14    idempotency_key: 'unique-payout-123',
15    recipient: {
16      msisdn: '+237612345678'
17    }
18  })
19});
20
21const payout = await response.json();
22console.log('Payout ID:', payout.payout_id);
23console.log('Status:', payout.status);

Idempotency

The idempotency_key ensures that if you retry a request with the same key, the payout won't be processed twice. Use a unique identifier for each payout (e.g., UUID, timestamp + merchant reference).

ℹ️