Payment requests
Ask another iSmartPay account for money, and find out when they answer.
You send one with the same POST /v1/collections you use for mobile money. The only difference is provider.
A key can send and cancel payment requests. It can never approve one. Approving is always a person, signed in as the payer.
Before you start
- Your business needs a handle, the public name people use to find it. An owner claims it in the console. Without one, sending is refused with
422 requester_handle_required. - Your key needs
collections.write.
Send
POST /v1/collections
Idempotency-Key: req-4410
{
"reference": "req-4410",
"amount": "25.00",
"currency": "GHS",
"provider": "ismartpay",
"payer": { "type": "handle", "value": "@ama" },
"note": "Lunch",
"expiresIn": 3600
}
providerisismartpay.payer.typeishandleormsisdn.handleonly works withismartpay, andismartpaytakes no other type.expiresInis how many seconds the payer has to answer. Leave it out for 15 minutes. By default the shortest is 60 seconds and the longest is 24 hours, though iSmartPay can change that. Anything outside the range is400with the range inmessage. It only works withismartpay.noteis optional, at most 50 characters.- Asking your own account is
422 payer_is_requester.
You get a 202 and the collection, like any other:
{
"reference": "req-4410",
"amount": "25.00",
"currency": "GHS",
"status": "accepted",
"provider": "ismartpay",
"expiresAt": "2026-10-28T13:00:00Z",
"createdAt": "2026-10-28T12:00:00Z"
}
expiresAt is when the request ends if nobody answers.
An unknown handle looks like a request nobody answers
If the handle or number has no iSmartPay account, you still get a 202. The request then sits there until it expires. This is on purpose: otherwise a key could try handles one by one to find out who has an account. For the same reason, GET /v1/party-lookups refuses ismartpay.
Check the handle with whoever you are asking, not with the API.
What happens next
| What the payer does | status |
failureReason |
|---|---|---|
| Nothing yet | accepted |
|
| Approves, transfer running | dispatched |
|
| Transfer done | settled |
|
| Declines | failed |
declined |
| You cancel it | failed |
cancelled |
Does nothing until expiresAt |
expired |
expired |
A request starts accepted. After the payer approves it can show dispatched while the transfer runs, then settled. You may not see dispatched, so do not wait for it.
Read the collection with GET /v1/collections/{reference}, or subscribe to collection.accepted and collection.status_changed. You get collection.accepted when the request is sent and collection.status_changed when the payer answers or it expires. A settled request is a collection.status_changed. It is not a transfer.received.
See Payment statuses.
Cancel
POST /v1/collections/req-4410/cancel
Idempotency-Key: cancel-4410
This withdraws a request that is still open. You get the collection back with status failed and failureReason cancelled. Cancelling twice returns the same answer.
- A request that was already approved, declined or expired is
409 request_not_open. - A collection that is not an
ismartpayrequest is409 not_a_payment_request. - A reference that is not yours is
404.
Limits
To keep people from being spammed, there are limits on how many requests you can send. Over one of them, you get 429 request_limit_reached, and message says which. It carries no Retry-After, so wait before you try again rather than retrying at once. Other 429s are your key’s rate limit, and those do carry Retry-After.
When you are the payer
If another account asks your business for money, you get a payment_request.received webhook:
{
"id": "evt_5b1e7c3a9d2f4e6a8c0b1d3f5e7a9c2b",
"type": "payment_request.received",
"createdAt": "2026-10-28T12:00:00Z",
"data": {
"requestId": "7c1f0b3e-5a52-4d0e-8c11-6f0d2b7a9e10",
"reference": "req-4410",
"requesterName": "Ama Mensah",
"requesterKind": "consumer",
"amount": "25.00",
"currency": "GHS",
"note": "Lunch",
"expiresAt": "2026-10-28T13:00:00Z"
}
}
requesterNameis a person’s full name. For a business it is the display name, which is its@handlewhen it has not set one.requesterKindisconsumerorbusiness.referenceis the one the requester chose.requestIdis iSmartPay’s own id.- It is sent once per request. It only tells you the request arrived. A key cannot answer it.
The developer console cannot answer a request yet. It has no wallet PIN and no approve screen. Until it does, a request sent to your business will expire unless the requester cancels it. This is a known gap. If your business also has the iSmartPay Business console, an owner, admin or operator can approve or decline there with the wallet PIN.
People on your team set up webhook endpoints in the console. An endpoint receives this event, and GET /v1/events shows it, when your business’s key scope allows collections.read. If an endpoint was set up before payment requests arrived, edit or save it once in the console. Until then it does not get the event. See Webhooks.
Permissions
| To | The key needs |
|---|---|
| Send or cancel a request | collections.write |
| Read a request | collections.read |
Get payment_request.received |
collections.read |
Errors
As well as the common errors:
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_input |
A field is wrong, or expiresIn is outside the allowed range. Read message. |
| 422 | requester_handle_required |
Your business has no handle. Claim one in the console. |
| 422 | payer_is_requester |
You asked your own account. Check the payer. |
| 429 | request_limit_reached |
You are over a sending limit. message names it. Wait, then try again. |
| 409 | request_not_open |
The request is no longer open, so it cannot be cancelled. |
| 409 | not_a_payment_request |
Only ismartpay collections can be cancelled this way. |
| 503 | provider_unavailable |
Payment requests are temporarily unavailable. Try again shortly. |