Skip to main content
POST
/
api
/
v1
/
payments
/
webhook
Payment Webhook
curl --request POST \
  --url https://api.example.com/api/v1/payments/webhook \
  --header 'Content-Type: application/json' \
  --data '
{
  "transactionId": "<string>",
  "status": "<string>",
  "phoneNumber": "<string>",
  "amount": "<string>",
  "description": "<string>"
}
'
{
  "status": "<string>",
  "transaction_id": "<string>",
  "error": "<string>"
}

​
Overview

This endpoint receives payment status updates from Africa’s Talking payment gateway. It is called automatically by Africa’s Talking when a payment is completed, failed, or cancelled.
This endpoint is designed to be called by Africa’s Talking servers only. You should configure this URL in your Africa’s Talking dashboard webhook settings.

​
Request Format

The webhook receives application/x-www-form-urlencoded form data with the following fields:
​
transactionId
string
The transaction ID from Africa’s Talking payment gateway
​
status
string
Payment status from Africa’s Talking. Values:
  • Success - Payment completed successfully
  • Failed - Payment failed
​
phoneNumber
string
The phone number that was charged
​
amount
string
The payment amount
​
description
string
Additional information (typically present on failed payments)

​
Response

​
status
string
Status of webhook processing:
  • webhook_processed - Successfully processed
  • webhook_error - Error occurred during processing
​
transaction_id
string
The transaction ID that was processed
​
error
string
Error message (only present if status is webhook_error)

​
Example Webhook Payload (Success)

curl -X POST https://api.voicepact.com/api/v1/payments/webhook \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "transactionId=ATXid_sample123456789" \
  -d "status=Success" \
  -d "phoneNumber=+254712345678" \
  -d "amount=5000.0"

​
Example Webhook Payload (Failed)

curl -X POST https://api.voicepact.com/api/v1/payments/webhook \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "transactionId=ATXid_sample123456789" \
  -d "status=Failed" \
  -d "phoneNumber=+254712345678" \
  -d "amount=5000.0" \
  -d "description=Insufficient funds"

​
Example Response

{
  "status": "webhook_processed",
  "transaction_id": "ATXid_sample123456789"
}

​
Webhook Behavior

​
On Success Status

  • Payment status updated to LOCKED in database
  • confirmed_at timestamp set to current UTC time
  • Payment funds are held in escrow for the contract

​
On Failed Status

  • Payment status updated to FAILED in database
  • Failure reason stored from the description field
  • User may need to retry payment

​
Configuration

To configure this webhook in Africa’s Talking:
  1. Log into your Africa’s Talking account
  2. Navigate to Payments → Settings → Callbacks
  3. Set the Payment Notification URL to: 
    https://api.voicepact.com/api/v1/payments/webhook

​
Security Considerations

  • The webhook endpoint accepts requests from Africa’s Talking servers
  • Transaction IDs are validated against existing payment records
  • Only known payments are updated
  • All webhook events are logged for audit purposes

​
Testing

You can test webhook processing locally by:
  1. Initiating a test payment using the checkout endpoint
  2. Using the Africa’s Talking sandbox to simulate payment completion
  3. Checking your server logs for webhook receipt confirmation

​
Troubleshooting

​
Payment Not Updating

  • Verify the webhook URL is correctly configured in Africa’s Talking
  • Check that the transaction ID exists in your database
  • Review server logs for webhook processing errors

​
Duplicate Webhooks

  • Africa’s Talking may retry webhook delivery
  • The endpoint is idempotent and safe to call multiple times
  • Same transaction ID will update the same payment record

Build docs developers (and LLMs) love

Get started for freeTalk to us