> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Pay-ins and virtual accounts

> Collect money from a payer by virtual account, bank transfer or card.

A pay-in collects money from a payer into one of your wallets. You create the pay-in, give the payer what they need to pay, and learn the outcome by webhook.

> [!TIP]
>
> If you want a hosted page and no server flow, use a [payment link](/guides/payment-links.md) instead.

## Choose a method

| `method` | What the payer does | Best for |
| - | - | - |
| `virtual_account` | Transfers the exact amount to a one-off account. | An order or invoice for a fixed amount. |
| `bank_transfer` | Transfers to your virtual account. | Top-ups and open amounts. |
| `card` | Pays by card, then enters a PIN or one-time code. | Card checkout that you build yourself. |

[Coverage](/essentials/coverage.md#pay-ins) lists which methods work in which currency.

## Create a pay-in

`POST /v1/payins`

**Idempotency-Key** `string` *required*

A unique key for this pay-in. Reuse it on every retry.

**currency** `string` *required*

`NGN`, `GHS` or `KES`.

**amount** `integer` *required*

The amount you expect, in minor units.

**method** `string` *required*

`virtual_account`, `bank_transfer`, `card`, `mobile_money` or `eft`.

**customer** `object` *required*

The payer.

**customer fields**

**name** `string` *required*

The payer's name, up to 255 characters.

**email** `string`

The payer's email address.

**phone** `string`

The payer's phone number.

**merchantReference** `string` *required*

Your own reference for this payment, such as an order id. Up to 255 characters.

**card** `object`

Needed when `method` is `card`: `number`, `expiryMonth` (`MM`), `expiryYear` (`YY` or `YYYY`), `cvv`, and optional `holderName`.

**phone** `string`

Needed when `method` is `mobile_money`. The payer's number in international format.

**operator** `string`

Needed when `method` is `mobile_money`: `mtn`, `airtel`, `m-pesa`, `vodacom` or `orange`.

**callbackUrl** `string`

Needed when `method` is `eft`. Where the payer returns to.

**metadata** `object`

Your own key-value data.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/payins" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Idempotency-Key: order-7781-payin" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "amount": 5000000,
    "method": "virtual_account",
    "merchantReference": "order-7781",
    "customer": {
      "name": "Chidi Okeke",
      "email": "chidi@example.com"
    }
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/payins`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Idempotency-Key': `order-${order.id}-payin`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    currency: 'NGN',
    amount: 5000000,
    method: 'virtual_account',
    merchantReference: `order-${order.id}`,
    customer: { name: 'Chidi Okeke', email: 'chidi@example.com' },
  }),
});
const { data: payin } = await res.json();
// Show payin.authorization.accountNumber and bankName to the payer.
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/payins",
    headers={
        "x-api-key": os.environ["PAYVE_API_KEY"],
        "Idempotency-Key": f"order-{order.id}-payin",
    },
    json={
        "currency": "NGN",
        "amount": 5000000,
        "method": "virtual_account",
        "merchantReference": f"order-{order.id}",
        "customer": {"name": "Chidi Okeke", "email": "chidi@example.com"},
    },
)
payin = res.json()["data"]
# Show payin["authorization"]["accountNumber"] and ["bankName"] to the payer.
```

```json Response · 202
{
  "data": {
    "id": 1851,
    "publicId": "pin_3f9a2c1d8e7b6a50",
    "status": "pending",
    "subStatus": null,
    "currency": "NGN",
    "amount": "5000000",
    "creditedAmount": "5000000",
    "feeAmount": "0",
    "feeCurrency": null,
    "taxAmount": "0",
    "taxType": null,
    "method": "virtual_account",
    "merchantReference": "order-7781",
    "requiresAuthorization": false,
    "authorization": {
      "mode": "virtual_account",
      "accountNumber": "9912345678",
      "bankName": "Example Bank",
      "accountName": "Payve / Chidi Okeke",
      "expiresAt": "2026-11-18T11:44:03.000Z"
    },
    "userMessage": null,
    "senderDetails": null,
    "createdAt": "2026-11-18T11:14:03.000Z",
    "updatedAt": "2026-11-18T11:14:03.000Z"
  }
}
```

### Response fields

**id** `integer`

Use this in URLs: `GET /v1/payins/{id}`.

**publicId** `string`

The `pin_` id.

**status** `string`

`pending`, `processing`, `successful` or `failed`.

**subStatus** `string | null`

Extra detail: `expired`, `overpaid`, `underpaid` and others. See
[Statuses](/essentials/statuses.md#sub-status).

**amount** `string`

The amount you asked for, in minor units.

**creditedAmount** `string | null`

After the pay-in succeeds, the net amount credited to your wallet.

**feeAmount** `string`

Payve's fee, taken from the credit.

**taxAmount** `string`

Any tax withheld, with its kind in `taxType`.

**authorization** `object | null`

What the payer needs in order to pay. Its shape depends on `mode`.

**requiresAuthorization** `boolean`

`true` when you must submit a PIN or one-time code next.

**senderDetails** `object | null`

The paying account, once the bank reports it.

## Virtual account pay-ins

A `virtual_account` pay-in issues a one-off bank account for one payment of one amount. Show `authorization.accountNumber`, `bankName` and `accountName` to the payer, with the exact amount and the expiry time.

| The payer sends | What happens |
| - | - |
| The expected amount | The pay-in becomes `successful`. You get `payin.successful`. |
| Less than the expected amount | The whole payment goes back to the payer. The pay-in stays `pending` so they can pay again. |
| More than the expected amount | You keep the expected amount. The excess goes back to the payer. |
| Nothing before `expiresAt` | The pay-in becomes `failed` with `subStatus: expired`. You get `payin.expired`. |

> [!WARNING]
>
> Tell the payer to send the exact amount, and not to use the account after it expires. Do not reuse
> account details from an old pay-in for a new order.

If no route can issue a one-off account in that currency, the request fails with `channel_unavailable`.

## Bank transfer pay-ins

A `bank_transfer` pay-in returns the details of a virtual account in `authorization`, in the same shape as above. In live, this is your permanent virtual account for that currency, which Payve creates the first time you need it.

> [!NOTE]
>
> Your business must have a verified BVN before Payve can create a Naira virtual account in live.
> Without one the request fails.

For a fixed-amount order, prefer `virtual_account`: it gives each payment its own account and its own expiry.

## Card pay-ins

> [!WARNING]
>
> Sending card numbers through your own server brings your systems into PCI DSS scope. If you do not
> want that, use a [payment link](/guides/payment-links.md): the hosted checkout collects the card for
> you.

A card pay-in can need one or two extra steps.

**1. Create the pay-in with the card**

Send `method: "card"` and the `card` object. If the response has `requiresAuthorization: true`, look at `authorization.mode`.

**2. Submit the PIN**

When `authorization.mode` is `pin`, collect the PIN from the payer and send it:

```bash
curl -X POST "$PAYVE_API_URL/v1/payins/1852/authorize" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "1234" }'
```

**3. Submit the one-time code**

If the response now has `authorization.mode` of `otp`, collect the code sent to the payer and call the same endpoint with `{ "otp": "123456" }`.

**4. Wait for the outcome**

The pay-in becomes `successful` or `failed`. You get `payin.successful` or `payin.failed`.

`POST /v1/payins/{id}/authorize` takes `pin`, `otp` or `birthday` (`DD/MM/YYYY`). It returns `409 resource_invalid_state` when the pay-in is not waiting for an authorisation step.

> [!WARNING]
>
> Never store a card number, CVV, PIN or one-time code, and never write them to logs.

## Check a pay-in

| Request | Does |
| - | - |
| `GET /v1/payins/{id}` | Returns the pay-in as Payve has it now. |
| `POST /v1/payins/{id}/validate` | Asks the provider for the latest state, then returns the pay-in. |
| `GET /v1/payins` | Lists pay-ins. Filter with `status`, `from`, `to`, `q`; page with `cursor`. |

Use `validate` when a payer says they have paid and no webhook has arrived.

## Fees and what you receive

The payer sends `amount`. Payve credits your wallet with `creditedAmount`, which is the amount received less `feeAmount` and any `taxAmount`.

## Idempotency

Sending the same `Idempotency-Key` again returns the pay-in you already created, with the same account details. Use a key derived from your order, such as `order-7781-payin`, so that a page reload does not open a second account.

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `400 validation_idempotency_key_required` | No `Idempotency-Key` header. | Send one. |
| `422 validation_missing_field` | A field is missing or malformed, or a method-specific field is absent. | Fix the fields named. |
| `502 channel_unknown_error` | The provider could not create the account or the charge. | Read `message`. Create a new pay-in with a new key. |
| `channel_unavailable` | No route can issue a one-off account in that currency. | Use another method. |
| `409 resource_invalid_state` | `authorize` was called on a pay-in that is not waiting for it. | Fetch the pay-in and read its status. |
| `404 resource_not_found` | The pay-in is not on your account. | Check the id. Use the numeric `id`. |

A card or mobile money charge that the provider declines does not return an HTTP error. The response is `202` with `status: failed` and the reason in `userMessage`.

## Cautions

> [!WARNING]
>
> **Fulfil on `successful`, and check `subStatus`.** A pay-in from a payment link can be
> `successful` with `subStatus: underpaid`, which credited nothing.

> [!WARNING]
>
> **Confirm with a `GET` before you hand over goods.** Treat the webhook as a prompt to look, then
> act on what `GET /v1/payins/{id}` returns.
