Transaction Status

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

Endpoint

1GET /api/v1/wallets/transactions/:id

Path Parameters

Parameter	Type	Description
`id`	string	Transaction ID from the execute collection response

Response

1{
2  "transaction": {
3    "id": "txn-uuid",
4    "merchantId": "merchant-uuid",
5    "gateway": "MTN_MOMO",
6    "amount": "10000.00",
7    "currency": "XAF",
8    "status": "SUCCESS",
9    "gatewayReference": "MTN_REF_123456789",
10    "gatewayFee": "50.00",
11    "platformFee": "100.00",
12    "createdAt": "2024-01-15T10:00:00.000Z",
13    "completedAt": "2024-01-15T10:01:00.000Z"
14  }
15}

Response Fields

Field	Type	Description
`id`	string	Transaction identifier
`merchantId`	string	Your merchant ID
`gateway`	string	Payment gateway used (MTN_MOMO, ORANGE_MONEY)
`amount`	string	Transaction amount
`currency`	string	Currency code
`status`	string	Transaction status (PENDING, VERIFYING, SUCCESS, FAILED, CANCELLED)
`gatewayReference`	string	Reference from mobile money provider
`gatewayFee`	string	Fee charged by gateway
`platformFee`	string	ZoPay platform fee
`createdAt`	string	Transaction creation timestamp
`completedAt`	string	Transaction completion timestamp (null if pending)

Example Request

1const transactionId = 'txn-uuid-from-execute-response';
2
3const response = await fetch(`https://api.zopay.com/api/v1/wallets/transactions/${transactionId}`, {
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('Status:', data.transaction.status);
17console.log('Amount:', data.transaction.amount);

Transaction Statuses

PENDING: Transaction has been initiated but not yet processed
VERIFYING: Payment is being verified with the mobile money provider
SUCCESS: Payment completed successfully
FAILED: Payment failed (check error details in response)
CANCELLED: Transaction was cancelled by user or system

Polling vs Webhooks

While you can poll the status endpoint, we recommend using webhooks to receive real-time notifications when transaction status changes. This is more efficient and provides better user experience.

Best Practices

Use webhooks for real-time status updates
Only poll status if webhook delivery fails
Implement exponential backoff when polling
Cache transaction status in your database
Handle all possible status values in your code

PreviousExecute Collection

NextHosted Checkout

Parameter

Type

Description

id

string

Transaction ID from the execute collection response

Response

1{
2  "transaction": {
3    "id": "txn-uuid",
4    "merchantId": "merchant-uuid",
5    "gateway": "MTN_MOMO",
6    "amount": "10000.00",
7    "currency": "XAF",
8    "status": "SUCCESS",
9    "gatewayReference": "MTN_REF_123456789",
10    "gatewayFee": "50.00",
11    "platformFee": "100.00",
12    "createdAt": "2024-01-15T10:00:00.000Z",
13    "completedAt": "2024-01-15T10:01:00.000Z"
14  }
15}

Response Fields

Field

Type

Description

id

string

Transaction identifier

merchantId

string

Your merchant ID

gateway

string

Payment gateway used (MTN_MOMO, ORANGE_MONEY)

amount

string

Transaction amount

currency

string

Currency code

status

string

Transaction status (PENDING, VERIFYING, SUCCESS, FAILED, CANCELLED)

gatewayReference

string

Reference from mobile money provider

gatewayFee

string

Fee charged by gateway

platformFee

string

ZoPay platform fee

createdAt

string

Transaction creation timestamp

completedAt

string

Transaction completion timestamp (null if pending)

Example Request

1const transactionId = 'txn-uuid-from-execute-response';
2
3const response = await fetch(`https://api.zopay.com/api/v1/wallets/transactions/${transactionId}`, {
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('Status:', data.transaction.status);
17console.log('Amount:', data.transaction.amount);