---
title: Payment requests
description: Ask another iSmartPay account for money, and find out when they answer.
---

:::note[In a nutshell]
A payment request asks another iSmartPay account to pay you. The payer answers in iSmartPay, with their PIN. A customer does it in the iSmartPay app. A business does it in the iSmartPay Business console, under Wallet, then Payment requests. Nothing moves until they approve.
:::

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

```http
POST /v1/collections
Idempotency-Key: req-4410
```

```json
{
  "reference": "req-4410",
  "amount": "25.00",
  "currency": "GHS",
  "provider": "ismartpay",
  "payer": { "type": "handle", "value": "@ama" },
  "note": "Lunch",
  "expiresIn": 3600
}
```

- `provider` is `ismartpay`.
- `payer.type` is `handle` or `msisdn`. `handle` only works with `ismartpay`, and `ismartpay` takes no other type.
- `expiresIn` is 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 is `400` with the range in `message`. It only works with `ismartpay`.
- `note` is optional, at most 50 characters.
- Asking your own account is `422 payer_is_requester`.

You get a `202` and the collection, like any other:

```json
{
  "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](/guides/payment-statuses).

## Cancel

```http
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 `ismartpay` request is `409 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 `429`s 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:

```json
{
  "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"
  }
}
```

- `requesterName` is a person's full name. For a business it is the display name, which is its `@handle` when it has not set one.
- `requesterKind` is `consumer` or `business`.
- `reference` is the one the requester chose. `requestId` is 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](/guides/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](/guides/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. |
