Pay API
Accept card & mobile money payments on your website
Authentication
All requests use the base URL https://merchant.ladill.com/api/v1
and a Bearer API key. Create a key with the Pay scope in account.ladill.com → Developers.
Authorization: Bearer your_keyCreate a payment
/payments
Initialise a payment. Returns an access_code + public_key for the inline popup (LadillPay.inline), plus a hosted authorization_url as a fallback.
Parameters
amount
|
number required | Amount to charge, in GHS (e.g. 50.00). Omit only if you send line_items instead. |
currency
|
string optional | ISO currency code. Defaults to GHS. |
customer_email
|
string optional | Buyer email — used for the receipt. |
reference
|
string optional | Your own order reference, echoed back on the payment and webhook. |
description
|
string optional | What the buyer is paying for. |
callback_url
|
string optional | Where to return the buyer after a hosted-checkout payment. |
metadata
|
object optional | Any key/value data to attach to the payment. |
curl -X POST https://merchant.ladill.com/api/v1/payments \
-H "Authorization: Bearer your_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 50.00,
"currency": "GHS",
"customer_email": "buyer@example.com",
"reference": "order_1234"
}'{
"reference": "LP-8F2A31C9",
"status": "pending",
"amount_minor": 5000,
"currency": "GHS",
"access_code": "acc_live_…",
"public_key": "pk_live_…",
"authorization_url": "https://pay.ladill.com/…"
}Fetch a payment
/payments/{reference}
Retrieve a payment by its reference to confirm the status (pending, paid, failed) — use this to reconcile after the buyer returns.
curl -X GET https://merchant.ladill.com/api/v1/payments/{reference} \
-H "Authorization: Bearer your_key"{
"reference": "LP-8F2A31C9",
"status": "paid",
"amount_minor": 5000,
"platform_fee_minor": 175,
"merchant_amount_minor": 4825,
"currency": "GHS",
"paid_at": "2026-08-19T12:04:38+00:00"
}Payment webhooks
Set your webhook URL in merchant.ladill.com → Payments API. Ladill POSTs a signed payment.success (and payment.failed) event to your URL; verify it with HMAC-SHA512 of the raw request body using your signing secret, compared against the X-Ladill-Signature header.
Errors
Errors use standard HTTP status codes with a JSON error message.
401 |
Invalid or missing API key. |
402 |
Insufficient wallet balance — top up to continue. |
422 |
Validation failed (missing or invalid parameters). |
429 |
Rate limit exceeded — retry after the seconds in retry_after. |
500 |
Send failed at the provider — safe to retry; charges are refunded. |