Naira bank payouts

Create a bank payout

Pay naira from your NGN balance to any Nigerian bank account. The account is checked with the bank first. The full amount arrives; the fee comes from your balance on top.

curl --request POST \
  --url 'http://localhost:4188/api/v1/bank-payouts' \
  --header "X-Api-Key: $RIMOSWAP_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Content-Type: application/json' \
  --data '{
    "bank_code": "058",
    "account_number": "0123456789",
    "account_name": "Adaeze Okafor",
    "amount": "20000",
    "customer_id": "cus_1001",
    "narration": "Wallet withdrawal"
  }'

{
  "bank_payout": {
    "id": "bp_41",
    "amount": "20000",
    "fee": "50",
    "total_debit": "20050",
    "currency": "NGN",
    "bank_name": "GTBank",
    "account_name": "ADAEZE OKAFOR",
    "account_last4": "6789",
    "reference": "RST-8KX2P4QD7M1A",
    "status": "queued",
    "customer_id": "cus_1001",
    "test": false
  }
}

Authorizations

• X-Api-Keystringheaderrequired

  Your API key. Test keys start rmo_test_, live keys rmo_live_.

• Idempotency-Keystringheaderrequired

  16 to 80 letters, digits, _ or -. Reuse it when you retry: a retry then returns the original instead of doing it twice.

Body

application/json

• bank_codestringrequired

  From GET /v1/banks.

  Example: "058"

• account_numberstringrequired

  10 digits.

  Example: "0123456789"

• amountstringrequired

  Naira. Minimum 100.

  Example: "20000"

• account_namestring

  Who you expect the account to belong to. Refused (422 name_mismatch) if the bank says otherwise.

  Example: "Adaeze Okafor"

• customer_idstring

  Your own id for this customer: letters, digits and _ . : @ - (64 at most). Never a name, phone number or email.

  Example: "cus_1001"

• narrationstring

  Your note for your records, up to 100 characters.

  Example: "Wallet withdrawal"

• sandbox_outcomestring

  Test keys only: "failed" makes it fail.

  Options: failed

Good to know

• Pass account_name and a payout to a different name is refused before anything moves.
• To pay naira from crypto, swap to NGN first.

Webhooks

Sends bank_payout:processing, bank_payout:completed, bank_payout:failed to the key's webhook URL. Verifying them.

Errors

• 422 name_mismatchThe bank holds a different name. Nothing was sent.
• 422 insufficient_balanceNot enough NGN for the amount and fee.
• 422 daily_limitOver your daily payout limit.