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.
If you want a hosted page and no server flow, use a payment link instead.

Choose a method

Coverage lists which methods work in which currency.

Create a pay-in

POST /v1/payins
string
required
A unique key for this pay-in. Reuse it on every retry.
string
required
NGN, GHS or KES.
integer
required
The amount you expect, in minor units.
string
required
virtual_account, bank_transfer, card, mobile_money or eft.
object
required
The payer.
string
required
Your own reference for this payment, such as an order id. Up to 255 characters.
object
Needed when method is card: number, expiryMonth (MM), expiryYear (YY or YYYY), cvv, and optional holderName.
string
Needed when method is mobile_money. The payer’s number in international format.
string
Needed when method is mobile_money: mtn, airtel, m-pesa, vodacom or orange.
string
Needed when method is eft. Where the payer returns to.
object
Your own key-value data.
Response · 202

Response fields

integer
Use this in URLs: GET /v1/payins/{id}.
string
The pin_ id.
string
pending, processing, successful or failed.
string | null
Extra detail: expired, overpaid, underpaid and others. See Statuses.
string
The amount you asked for, in minor units.
string | null
After the pay-in succeeds, the net amount credited to your wallet.
string
Payve’s fee, taken from the credit.
string
Any tax withheld, with its kind in taxType.
object | null
What the payer needs in order to pay. Its shape depends on mode.
boolean
true when you must submit a PIN or one-time code next.
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.
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.
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

Sending card numbers through your own server brings your systems into PCI DSS scope. If you do not want that, use a payment link: 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:
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.
Never store a card number, CVV, PIN or one-time code, and never write them to logs.

Check a pay-in

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

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

Fulfil on successful, and check subStatus. A pay-in from a payment link can be successful with subStatus: underpaid, which credited nothing.
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.