Execute Collection
After creating a quote, use this endpoint to process the actual payment from the customer.
Endpoint
1POST /api/v1/wallets/collectRequest Body
1{
2 "quote_id": "quote-uuid",
3 "idempotency_key": "unique-payment-123"
4}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 transactions |
💡
Idempotency Key: Always use a unique idempotency key for each collection attempt. If you retry a request with the same idempotency key, ZoPay will return the original transaction result instead of creating a duplicate payment.
Response
1{
2 "transaction_id": "txn-uuid",
3 "status": "VERIFYING",
4 "gateway_reference": "MTN_REF_123456789",
5 "correlation_id": "corr-uuid"
6}Response Fields
| Field | Type | Description |
|---|---|---|
transaction_id | string | Unique transaction identifier |
status | string | Current transaction status (PENDING, VERIFYING, SUCCESS, FAILED) |
gateway_reference | string | Reference from the mobile money provider |
correlation_id | string | Correlation ID for tracking |
Example Request
1const response = await fetch('https://api.zopay.com/api/v1/wallets/collect', {
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: `payment-${Date.now()}-${Math.random()}`
15 })
16});
17
18const result = await response.json();
19console.log('Transaction ID:', result.transaction_id);
20console.log('Status:', result.status);Idempotency
The idempotency_key ensures that if you retry a request with the same key, the same transaction will be returned instead of creating a duplicate. Always use a unique identifier for each payment attempt.
Transaction Status
After executing a collection, the transaction status will be VERIFYING initially. You should:
- Store the
transaction_idin your database - Set up webhooks to receive status updates
- Poll the status endpoint if needed: Get Transaction Status
Error Handling
Common errors you might encounter:
400 Bad Request: Invalid quote_id or expired quote409 Conflict: Duplicate idempotency_key402 Payment Required: Insufficient balance or payment declined