Naira collections

Create a collection

Bank details for one customer payment. When the customer pays exactly the amount, it reaches your balance as USDT at the rate quoted now, minus the collection fee.

curl --request POST \
  --url 'http://localhost:4188/api/v1/collections' \
  --header "X-Api-Key: $RIMOSWAP_KEY" \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "cus_1001",
    "amount": "50000",
    "customer": {
      "first_name": "Adaeze",
      "last_name": "Okafor",
      "bvn": "22212345678",
      "nin": "12345678901"
    }
  }'

{
  "collection": {
    "id": "co_311",
    "amount": "50000",
    "currency": "NGN",
    "fee": "100",
    "credit_coin": "USDT",
    "credit_amount": "32.94",
    "bank_account": {
      "bank_name": "Wema Bank",
      "account_number": "8123456789",
      "account_name": "OBIEX-ADAEZE OKAFOR"
    },
    "expires_at": "2026-10-25 15:31:00",
    "status": "awaiting_payment",
    "customer_id": "cus_1001",
    "test": false,
    "created_at": "2026-10-25 15:01:00"
  }
}

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

• customer_idstringrequired

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

  Example: "cus_1001"

• amountstringrequired

  Naira the customer will send. Minimum 1,000.

  Example: "50000"

• customer.first_namestringrequired

  The payer’s first name, as on their bank account.

  Example: "Adaeze"

• customer.last_namestringrequired

  The payer’s last name.

  Example: "Okafor"

• customer.bvnstringrequired

  The payer’s 11-digit BVN.

  Example: "22212345678"

• customer.ninstringrequired

  The payer’s 11-digit NIN.

  Example: "12345678901"

Good to know

• Ask the customer to send exactly amount before expires_at. A different amount is held for review, not credited automatically.
• The payer’s names, BVN and NIN are checked by our bank partner for this payment only. Collect them with your customer’s consent. Rimoswap does not store them.
• To hold naira, swap the USDT to NGN when it arrives.

Webhooks

Sends collection:completed, collection:expired, collection:failed to the key's webhook URL. Verifying them.

Errors

• 422 invalid_customerA name, the BVN or the NIN is missing or malformed.
• 422 collection_refusedThe bank partner refused it, usually because the identity does not match.
• 503 unavailableCollections are paused, or the answer was lost. Read it back with the same Idempotency-Key; never ask the customer to pay twice.