API
Return URL & statuses
When the payment reaches a final state, the checkout page sends the customer to your return URL with extra query parameters. Any parameters already in your URL are kept.
https://shop.example.com/pay/return?order_id=ORD-1001&pp_status=completed&transaction_ref=k3J9x…&pp_id=k3J9x…| Parameter | Meaning |
|---|---|
pp_status | Payment status when the customer left checkout. |
pp_id | The payment ID from create charge. |
transaction_ref | Same value as pp_id, kept for older clients. |
Treat these parameters as a hint only. Anyone can type
pp_status=completed into a URL. Call verify-payment on your server before you fulfil.
Payment statuses
| Status | Meaning | Final? |
|---|---|---|
initiated | Created. The customer has not submitted a payment yet. | no |
pending | The customer submitted a payment and it is waiting for SMS or gateway confirmation. | no |
completed | Paid and confirmed. The only status you should fulfil on. | yes |
canceled | The customer cancelled, or an admin cancelled the payment. | yes |
expired | A sender-number checkout was not confirmed within its wait window (15 minutes). | yes* |
refunded | Marked as refunded by an admin or the refund API. | yes |
* Expired sender-number checkouts are deleted by the cron job. After that, verify-payment returns INVALID_PP_ID. Treat that response for an unpaid order as "not paid", and create a new charge if the customer tries again.