Choose a method
Coverage lists which methods work in which currency.
Create a pay-in
POST /v1/payins
Needed when
method is card: number, expiryMonth (MM), expiryYear (YY or YYYY), cvv, and optional holderName.Response · 202
Response fields
Extra detail:
expired, overpaid, underpaid and others. See
Statuses.Virtual account pay-ins
Avirtual_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.
If no route can issue a one-off account in that currency, the request fails with
channel_unavailable.
Bank transfer pay-ins
Abank_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.
virtual_account: it gives each payment its own account and its own expiry.
Card pay-ins
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.
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 sendsamount. Payve credits your wallet with creditedAmount, which is the amount received less feeAmount and any taxAmount.
Idempotency
Sending the sameIdempotency-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.

