API ReferenceBeneficiaries
Create a beneficiary
POST /v1/beneficiaries : register and verify a payout destination.
POST /v1/beneficiaries
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 |
type | string | yes | bank_account, mobile_money, wallet |
bank_code | string | cond. | Required for bank_account |
account_number | string | cond. | Required for bank_account |
currency | string | yes | ISO 4217 |
country | string | no | ISO 3166-1 alpha-2 (cross-border) |
Request
curl https://api.ouipay.africa/v1/beneficiaries \
-H "Authorization: Bearer sk_test_..." \
-H "Idempotency-Key: ben-001" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "01M2S17...",
"type": "bank_account",
"bank_code": "058",
"account_number": "0123456789",
"currency": "NGN"
}'Response 201
Returns the beneficiary object
with the resolved account_name.
Errors
| HTTP | error.code | Cause |
|---|---|---|
| 400 | VALIDATION | Invalid field |
| 422 | VERIFICATION_FAILED | Account could not be verified |