Payins
A payin represents an inbound payment from a customer to your merchant wallet. Payve supports three payment methods:
| Method | How it works |
|---|---|
bank_transfer | A virtual account is provisioned; customer sends a bank transfer to that account |
card | Customer enters debit/credit card details; PIN and OTP are collected inline |
mobile_money | Customer dials a USSD code or enters a PIN to authorise via their mobile wallet |
The payin object
json
{
"id": "3e4c8f20-...",
"publicId": "pin_01j9abc123",
"status": "succeeded",
"currency": "NGN",
"amount": "100000",
"method": "bank_transfer",
"merchantReference": "ORDER-9987",
"authorization": {
"mode": "virtual_account",
"accountNumber": "0123456789",
"bankName": "Payve Test Bank",
"accountName": "Payve Merchant Virtual",
"expiresAt": "2025-01-16T10: 00: 00Z"
},
"requiresAuthorization": false,
"createdAt": "2025-01-15T10: 00: 00Z",
"updatedAt": "2025-01-15T10: 02: 30Z"
}Fields
| Field | Type | Description |
|---|---|---|
id | string | Internal UUID |
publicId | string | Public-facing ID with pin_ prefix |
status | string | See statuses |
currency | string | ISO 4217 currency code |
amount | string | Amount in minor units |
method | string | bank_transfer, card, or mobile_money |
merchantReference | string | Your own reference for this payment |
authorization | object | Method-specific auth instructions (see below) |
requiresAuthorization | boolean | Whether the customer must take an action |
createdAt | string | ISO 8601 timestamp |
Statuses
| Status | Description |
|---|---|
received | Payin created, waiting for customer action |
pending | Payment submitted, awaiting channel confirmation |
succeeded | Payment confirmed and wallet credited |
failed | Payment failed at the channel |
expired | No payment received within the expiry window |
Initiate a payin
POST/v1/payins