Authentication issues
401 Unauthorized
Cause: Invalid or missing API key.
Solution: Check that you are including the
API key
Solution: Check that you are including the
Authorization: Bearer YOUR_SECRET_KEY header. Verify your key is active in the Dashboard.API key
403 Forbidden
Cause: Your API key does not have permission for this endpoint.
Solution: Verify your account is verified and KYC is approved. Contact support if the issue persists.
Permissions
Solution: Verify your account is verified and KYC is approved. Contact support if the issue persists.
Permissions
Collection issues
Collection stuck on pending
Cause: Customer has not approved the payment on their phone.
Solution: Ask the customer to check their phone for the mobile money prompt and enter their PIN. Collections expire after 30 minutes.
Collection
Solution: Ask the customer to check their phone for the mobile money prompt and enter their PIN. Collections expire after 30 minutes.
Collection
Collection failed
Cause: Insufficient funds, invalid phone number, or network error.
Solution: Verify the phone number format (e.g., +256700123456). Check the error response for details.
Collection
Solution: Verify the phone number format (e.g., +256700123456). Check the error response for details.
Collection
Disbursement issues
Disbursement failed
Cause: Invalid recipient details or insufficient wallet balance.
Solution: Verify the recipient’s phone number and network. Ensure your MarzPay wallet has sufficient funds. Failed disbursements are automatically reversed.
Disbursement
Solution: Verify the recipient’s phone number and network. Ensure your MarzPay wallet has sufficient funds. Failed disbursements are automatically reversed.
Disbursement
Webhook issues
Webhook not received
Cause: Endpoint not returning 200, or webhook not configured in Dashboard.
Solution: Verify your webhook URL in Settings > Webhooks. Ensure your endpoint returns HTTP 200 and is accessible over HTTPS.
Webhook
Solution: Verify your webhook URL in Settings > Webhooks. Ensure your endpoint returns HTTP 200 and is accessible over HTTPS.
Webhook
Invalid webhook signature
Cause: Wrong webhook secret or payload tampered.
Solution: Verify you are using the correct webhook signing secret from the Dashboard. Always verify signatures before processing.
Webhook
Solution: Verify you are using the correct webhook signing secret from the Dashboard. Always verify signatures before processing.
Webhook
API errors
Debugging steps
1
Check the error response
Read the
error.code and error.message fields in the API response.2
Verify your API key
Confirm you are using the correct key (sandbox vs production) and it is active.
3
Test in the playground
Reproduce the issue in the API Playground.
4
Check webhook logs
Review your server logs for webhook delivery attempts and responses.
Still having issues? Contact support at info@wearemarz.com or via WhatsApp.
API Playground - Test endpoints live to isolate issues