API ReferenceTransfers
Create a transfer
POST /v1/transfers : submit a payout to a beneficiary.
POST /v1/transfers
Headers
| Header | Required | Value |
|---|---|---|
Authorization | yes | Bearer sk_... |
Idempotency-Key | yes | unique per operation |
Content-Type | yes | application/json |
Body
| Field | Type | Required | Notes |
|---|---|---|---|
customer_id | string | yes | Customer ULID |
beneficiary_id | string | yes | Verified beneficiary ULID |
amount_minor | int | yes | Positive integer minor units |
currency | string | yes | ISO 4217 |
narration | string | no | Statement note for the recipient |
quote_id | string | no | FX quote id (cross-border only) |
Request
curl https://api.ouipay.africa/v1/transfers \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: trf-001" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "01M2S17...",
"beneficiary_id": "01M2S17...",
"amount_minor": 250000,
"currency": "NGN",
"narration": "Invoice 8842 payout"
}'Response 201
The transfer object. status: "pending": the transaction is recorded and funds held; settlement follows
the provider webhook.
Errors
| HTTP | error.code | Cause |
|---|---|---|
| 400 | VALIDATION | Invalid field |
| 403 | PIN_REQUIRED | PIN step-up needed (pin_stepup) |
| 422 | COMPLIANCE_DENIED | Screening blocked (compliance) |
| 422 | LIMIT_EXCEEDED | Above the tier limit (limits) |
| 422 | INSUFFICIENT_FUNDS | Wallet cannot cover amount+fee |