Skip to main content
POST
/
api
/
v1
/
payments
/
checkout
Mobile Checkout
curl --request POST \
  --url https://api.example.com/api/v1/payments/checkout \
  --header 'Content-Type: application/json' \
  --data '
{
  "contract_id": "<string>",
  "amount": 123,
  "phone_number": "<string>",
  "currency": "<string>",
  "payment_type": "<string>"
}
'
{
  "payment_id": 123,
  "transaction_id": {},
  "status": "<string>",
  "amount": 123,
  "currency": "<string>",
  "created_at": "<string>"
}

​
Overview

Initiates a mobile money checkout via Africa’s Talking payment gateway. This creates a payment record and triggers a mobile money prompt on the payer’s phone.

​
Request Body

​
contract_id
string
required
The unique identifier of the contract being paid for
​
amount
float
required
Payment amount (must be greater than 0)
​
phone_number
string
required
The mobile phone number to charge (format: +254XXXXXXXXX)
​
currency
string
default:"KES"
Currency code for the payment (default: KES - Kenya Shillings)
​
payment_type
string
default:"escrow"
Type of payment (default: “escrow”)

​
Response

​
payment_id
integer
Unique identifier for the payment record
​
transaction_id
string | null
External transaction ID from Africa’s Talking payment gateway
​
status
string
Current payment status. Possible values:
  • PENDING - Payment initiated, awaiting confirmation
  • LOCKED - Payment completed and locked in escrow
  • RELEASED - Payment released to recipient
  • REFUNDED - Payment refunded to payer
  • FAILED - Payment failed
​
amount
float
Payment amount
​
currency
string
Currency code
​
created_at
string
ISO 8601 timestamp of when the payment was created

​
Example Request

curl -X POST https://api.voicepact.com/api/v1/payments/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "contract_123456",
    "amount": 5000.0,
    "currency": "KES",
    "phone_number": "+254712345678",
    "payment_type": "escrow"
  }'

​
Example Response

{
  "payment_id": 42,
  "transaction_id": "ATXid_sample123456789",
  "status": "PENDING",
  "amount": 5000.0,
  "currency": "KES",
  "created_at": "2026-03-06T10:30:00.000000"
}

​
Error Responses

​
Contract Not Found (404)

{
  "detail": "Contract not found"
}

​
Invalid Amount (422)

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}

​
Server Error (500)

{
  "detail": "Mobile checkout failed: [error details]"
}

​
Workflow

  1. Validate Contract - System checks if the contract exists
  2. Create Payment Record - A payment record is created with PENDING status
  3. Initiate Mobile Checkout - Africa’s Talking sends a mobile money prompt
  4. Return Response - Payment details returned immediately (user completes payment on phone)
  5. Webhook Confirmation - Payment status updated via webhook when user completes payment

​
Notes

  • The phone number must be in international format (e.g., +254712345678)
  • The user will receive a mobile money prompt on their phone to authorize the payment
  • Payment status starts as PENDING and is updated to LOCKED or FAILED via webhook
  • Use the Get Payment endpoint to check final payment status

Build docs developers (and LLMs) love

Get started for freeTalk to us