# Ask How to Pay In

> Coming soon, upon request — this feature is turned on for your tenant by the Aurea team. [Contact us](https://www.aureahub.com/contact)

Give the user the account to pay and the exact amount to send, so the payment is recognised as theirs.

## Overview

- The bank ramp's account in each local currency is shared by every user of your tenant, and a bank transfer does not say who sent it. So each instruction has its own **exact amount**: `amountToPay` is the amount asked for plus a few smallest units, unique among your open instructions in that asset. A payment of exactly that amount before `payBy` is the user's.
- Tell the user to send **exactly** `amountToPay` to `payTo` before `payBy`. A different amount, or a payment after `payBy`, is not credited automatically: it waits for your tenant's review and is assigned by hand.
- KES: a bank transfer to `payTo.accountNumber` at `payTo.institution`, or an M-Pesa payment to the paybill `payTo.paybillNumber` with `payTo.accountNumber` as the account number. USD accounts have a rail each: name it with `rail` (`ach`, `fedwire` or `swift`) when there are several.
- `delivery`: `{ "kind": "balance" }` (the default) keeps the money on the user's balance; `{ "kind": "stablecoin", "asset", "network", "address" }` converts it and sends it to that address — follow it with [Stablecoin Deliveries](https://docs.aureahub.com/docs/local-deliveries.md).
- `expectedCredit` is what lands after the bank ramp's collection fee and your tenant's markup.
- A stablecoin `delivery` needs the user registered ([Register for the Local Rails](https://docs.aureahub.com/docs/local-verification-register.md)), even where your tenant does not ask for verification: `403` `BANK_RAMP_KYC_REQUIRED` otherwise.
- `422` `BANK_RAMP_ASSET_NOT_ENABLED` when pay-ins of the currency are not enabled, or `BANK_RAMP_LIMIT_EXCEEDED` / `BANK_RAMP_VELOCITY_EXCEEDED` past your tenant's 24-hour limits.
- `503` `BANK_RAMP_INSTRUCTION_CAPACITY` when no unique amount is free now: ask again shortly.
- Status changes are sent as `ramp.instruction.updated`.

Called with the user's access token, in one environment (`isTestnet`). See [Bank Ramp: Local Rails](https://docs.aureahub.com/docs/guide-bank-local.md).

## Endpoint

### `POST /v1/ramp/bank/customer/instructions`

Authentication: bearer token required.

Gives the user the account to pay and the exact amount to send, before a deadline. Send an Idempotency-Key header: the same key with the same body answers with the first answer, with the response header idempotency-replayed: true (see Idempotency).

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `asset` | string | yes | The local currency to pay in: `KES`, `MWK`, `USD`… |
| `amount` | string | yes | What the user wants to pay, as decimal text in major units ([Amount Units](https://docs.aureahub.com/docs/amounts.md)) |
| `rail` | string | no | USD only: `ach`, `fedwire` or `swift` |
| `delivery` | object | no | `{ "kind": "balance" }` (default) or `{ "kind": "stablecoin", "asset": "USDC", "network": "solana", "address": "…" }`; `network` is `ethereum`, `solana` or `tron` |
| `isTestnet` | boolean | no | `true` for the sandbox; `false` or omitted for production |

**Responses**

`201` Instruction

```json
{
  "id": "6b1f2d9e-3c4a-4e8b-9f21-7a5d0c3e8b14",
  "environment": "production",
  "asset": "KES",
  "requestedAmount": "15000.00",
  "amountToPay": "15000.37",
  "expectedCredit": "14775.36",
  "status": "open",
  "delivery": {
    "kind": "balance"
  },
  "payTo": {
    "asset": "KES",
    "rail": null,
    "institution": "Example Bank",
    "accountName": "Your Company Ltd",
    "accountNumber": "0123456789",
    "paybillNumber": "444174",
    "routingNumber": null,
    "bankCode": null,
    "bankAddress": null
  },
  "payBy": "2026-10-24T09:00:00.000Z",
  "matchedAt": null,
  "createdAt": "2026-10-23T09:00:00.000Z"
}
```

`403` Not verified

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "The user's verification with the bank ramp is not complete.",
  "details": {
    "code": "BANK_RAMP_KYC_REQUIRED"
  }
}
```

`422` Past the limit

```json
{
  "statusCode": 422,
  "error": "ValidationError",
  "message": "This would take this user KES past its limit of 300000.00 in 24 hours (290000.00 used).",
  "details": {
    "code": "BANK_RAMP_LIMIT_EXCEEDED",
    "asset": "KES"
  }
}
```

`403` No tenant

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "This request needs a tenant: an admin token without one has no bank ramp customer.",
  "details": {
    "code": "TENANT_REQUIRED"
  }
}
```

---

Web version: https://docs.aureahub.com/#local-instruction-create