Transaction Details & Status
Learn how to check transaction status and retrieve transaction information using Marz Pay
Transaction Status Check
Overview
Check the status of any transaction using the transaction ID, reference, or UUID. This is essential for tracking payment status and handling webhooks.
Transaction Identifiers
Primary Identifiers
- • UUID: Unique transaction identifier
- • Reference: Your custom reference
- • Provider Reference: Provider's transaction ID
Additional Identifiers
- • Airtel Reference: Airtel-specific ID
- • Provider Transaction ID: Provider's internal ID
- • Provider Reference ID: Alternative reference
API Example
curl -X GET https://wallet.wearemarz.com/api/v1/transactions/{transaction_id} \
-H "Authorization: Basic YOUR_API_CREDENTIALS" \
-H "Content-Type: application/json"Response (Webhook Format)
{
"event_type": "collection.completed",
"transaction": {
"uuid": "4e7aba5d-4681-4acc-91b6-4744228fcbcd",
"reference": "PAY_001",
"status": "completed",
"amount": {
"formatted": "1,000.00",
"raw": "1000",
"currency": "UGX"
},
"provider": "mtn",
"phone_number": "+256700000000",
"description": "Payment for services",
"created_at": "2024-01-01T12:00:00.000000Z",
"updated_at": "2024-01-01T12:00:00.000000Z"
},
"collection": {
"provider": "mtn",
"phone_number": "+256700000000",
"amount": {
"formatted": "1,000.00",
"raw": 1000,
"currency": "UGX"
},
"mode": "mtnuganda",
"provider_reference": "PAY_001"
},
"business": {
"uuid": "5ed723af-456a-47d6-9791-e4ffe478a462",
"name": "Your Business Name"
},
"metadata": {
"sandbox_mode": false,
"environment": "production",
"timestamp": "2024-01-01T12:00:00.000000Z",
"webhook_id": null
}
}Error Response
{
"status": "error",
"message": "Transaction not found.",
"error_code": "TRANSACTION_NOT_FOUND"
}Transaction History
Overview
Retrieve transaction history and filter transactions by status, date range, or provider. This is useful for reconciliation and reporting.
Filter Options
- • Filter by status: pending, completed, failed, cancelled
- • Filter by date range: from and to dates
- • Filter by provider: MTN, Airtel, Banks, Crypto
- • Filter by amount range: minimum and maximum
API Example
curl -X GET "https://wallet.wearemarz.com/api/v1/transactions?status=completed&from=2024-01-01&to=2024-01-31&provider=mtn" \
-H "Authorization: Basic YOUR_API_CREDENTIALS" \
-H "Content-Type: application/json"Event Types
Collection Events
- • collection.completed
- • collection.failed
- • collection.pending
- • collection.cancelled
Disbursement Events
- • disbursement.completed
- • disbursement.failed
- • disbursement.pending
- • disbursement.cancelled
Transaction Statuses
Pending
Payment is being processed by the provider
Completed
Payment was successful and funds transferred
Failed
Payment failed due to an error
Cancelled
Payment was cancelled by user or system
Best Practices
Store Transaction References
Always store transaction UUIDs and references in your database for easy lookup and reconciliation.
Implement Webhooks
Set up webhooks to receive real-time transaction status updates instead of polling the API.
Handle Status Changes
Always handle transaction status changes gracefully and update your system accordingly.
Monitor Transaction Health
Regularly check transaction statuses and implement monitoring for failed or stuck transactions.
Common Issues
Transaction Not Found
If a transaction is not found, check that you're using the correct identifier (UUID, reference, or provider reference).
Try: UUID, reference, airtel_reference, provider_reference, provider_transaction_id, provider_reference_id
Status Not Updating
If transaction status is not updating, check webhook configuration and ensure your endpoint is accessible.
Stuck Transactions
If transactions remain in pending status for too long, contact support for manual intervention.