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

# Payins

> Collect money from customers: mobile money in Cameroon, bank transfer in Nigeria.

A **payin** collects money from your customer into your One Pay balance.

| Method | Country | How the customer pays |
| - | - | - |
| `mobile_money` | Cameroon | A prompt on their phone (MTN or Orange), confirmed with their PIN |
| `bank_transfer` | Nigeria | A bank transfer to a one-time account, on a payment page |

## The life of a payin

```
pending → processing → succeeded → (settled)
                    ↘ failed
```

| Status | Meaning |
| - | - |
| `pending` | Created, not yet with the operator |
| `processing` | The customer has been asked to pay |
| `succeeded` | Paid. `net_amount` is credited to your **pending** balance |
| `failed` | Not paid: `failure.code` and `failure.message` say why |
| `reversed` | Paid, then taken back (rare: a dispute or an operator error) |

`settled_at` is set when the money becomes **available** for payouts: in
live mode once the partner's records confirm it, usually within minutes;
in test mode at once.

> [!TIP]
>
> Rely on the `payin.succeeded` [webhook](https://pay.onemarketc.com/docs/guides/webhooks.md) to deliver an
> order, never on the customer coming back to your site.

## Mobile money (Cameroon)

```bash theme={null}
curl https://onepay-api-eiy9.onrender.com/v1/payins \
  -H "Authorization: Bearer $ONEPAY_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XAF",
    "method": "mobile_money",
    "customer": { "phone": "+237650000001" },
    "reference": "order-1042",
    "description": "Order 1042",
    "metadata": { "cart_id": "c_123" }
  }'
```

| Field | Required | Rules |
| - | - | - |
| `amount` | Yes | Whole francs; more than the fee |
| `currency` | Yes | `XAF` |
| `method` | Yes | `mobile_money` |
| `customer.phone` | Yes | Cameroon mobile number, international format: `+2376…` |
| `reference` | No | Your own reference, up to 255 characters |
| `description` | No | Up to 500 characters; the customer sees it |
| `metadata` | No | Up to 20 keys of your own, returned as sent |

The operator is chosen from the number (MTN or Orange): you do not send it.

**What the customer sees.** The prompt on the customer's phone names your
business, then the description: *Kola Trade: Order 1042*. The name is your
account's name, or the **name customers see** you set for the app in the
dashboard (API keys & webhooks → Apps → Edit). Accents are removed, as many
phones cannot show them.

## Bank transfer (Nigeria)

```bash theme={null}
curl https://onepay-api-eiy9.onrender.com/v1/payins \
  -H "Authorization: Bearer $ONEPAY_KEY" \
  -H "Idempotency-Key: order-77" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 7500000,
    "currency": "NGN",
    "method": "bank_transfer",
    "customer": { "email": "ada@example.com", "name": "Ada Obi" },
    "return_url": "https://adastores.ng/thanks"
  }'
```

`amount` is in kobo: `7500000` is ₦75 000. `customer` is optional; the
payment page asks for anything missing. `return_url` (https) is where the
customer lands after paying.

The answer has a `next_action`. **Send your customer to its `url`**: the page
shows a one-time bank account to transfer to.

```json theme={null}
"next_action": {
  "type": "redirect_to_url",
  "url": "https://checkout.onepay.test/sim_26752679b1814a60a77d386003fdaa21"
}
```

`next_action` becomes `null` once the payin is finished. If the customer
transfers a different amount than asked, the payin is held for review
instead of succeeding.

## Reading payins

* `GET /v1/payins/{id}`: one payin.
* `GET /v1/payins`: newest first, [a page at a time](https://pay.onemarketc.com/docs/essentials/conventions.md#lists).

A payin of another account, or of the other mode, answers
`404 payin_not_found`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.