Remitflex Documentation

RemitFlex cNGN APIs move Naira and cNGN for a customer: permanent bank deposit account, one-time payins, convert between CNGN / USDC / USDT, withdraw crypto, or pay out to a Nigerian bank. These are not the same as:

Product	What it does
Solana swaps	EURC↔USDC on Solana (`/v1/swaps`)
Local fiat	Stablecoin ↔ local bank via `/v1/offramps` and `/v1/onramps` (no customer Smart Wallet)

Use local fiat for one-off bank payouts/deposits from your treasury. Use cNGN when the customer needs a linked wallet, permanent VA, or on-wallet CNGN/USDC/USDT converts.

Prerequisite: Enable cNGN for the customer with BVN (dashboard Customers → cNGN, or API below). That creates the Smart Wallet and deposit account.

Enable cNGN

Replace {customerId} with the RemitFlex customer UUID from POST or GET /customers (not a wallet address or StRails id).

curl -X POST https://api.remitflex.io/v1/cngn/customers/{customerId}/enable \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "bvn": "22222222222",
    "email": "optional@example.com",
    "phoneNumber": "+2348012345678"
  }'

Field	Rules
`bvn`	Exactly 11 digits (required)
`email`	Optional — defaults to the customer’s email
`phoneNumber`	Optional

Enablement is asynchronous. When KYC finishes, RemitFlex emits cngn.customer.enabled (or cngn.customer.failed). The customer object includes cngn: { enabled, identityMatched, status, legalName, evmWallet, virtualAccount, syncedAt } — null when cNGN has never been started. Create the customer with the BVN holder’s full legal name (first and last). On sync, RemitFlex stores the full StRails /getuserdetails profile, but only exposes legal name / VA / wallet when that KYC name matches customer.name under a strict multi-part name check (blocks BVN fishing). Single given names are not enough. On mismatch, identityMatched is false, enabled is false, PII fields are null, and RemitFlex emits cngn.customer.failed once with code: customer_name_bvn_mismatch / reason: Customer name does not match BVN holder. Until identity is verified (identityMatched: true), PII stays hidden. Reload the customer with GET /v1/customers/{customerId}, or subscribe to webhooks. Once enabled:

Need	Endpoint
Live primary Smart Wallet balances	`GET /v1/cngn/customers/{customerId}/wallets`
Cached deposit/payout history	`GET /v1/cngn/customers/{customerId}/history`

Required scopes: api:read, api:write

Permanent vs temporary virtual accounts

	Permanent deposit account	Temporary payin
Lifetime	Does not expire	~30 minutes
Amount	Any	Exact amount (includes fees)
Who can pay	Account holder (BVN match)	Third parties OK
How	On customer after enable	`POST /v1/cngn/payins`
Destination	Customer Smart Wallet (cNGN)	Default: sweep to customer Smart Wallet

Permanent credits create local cngn_deposit rows (email + cngn.deposit.* webhooks). List with GET /v1/cngn/deposits (optional ?customerId=).

Temporary payin (NGN → Smart Wallet)

curl -X POST https://api.remitflex.io/v1/cngn/payins \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sweepToOfframp": true,
    "autoSwap": false
  }'

Field	Description
`customerId`	Required — cNGN-enabled customer UUID
`amount`	Requested Naira (base). Fees are added — pay `payAmount` / `totalAmount` exactly
`sweepToOfframp`	Default `true` — sweep minted cNGN to the customer’s permanent Smart Wallet
`autoSwap`	Optional — convert cNGN → `assetSwap` before sweep
`assetSwap`	`USDC` or `USDT` (required when `autoSwap` is true)

If auto-sweep stalls, funds can remain on the temporary wallet. Check GET /v1/cngn/payins/{payinId} → sweep ({payinId} is the RemitFlex payin UUID from POST /cngn/payins), then:

curl -X POST https://api.remitflex.io/v1/cngn/payins/{payinId}/consolidate \
  -H "Authorization: Bearer $REMITFLEX_API_KEY"

`sweep.consolidate.status`	Meaning
`completed`	Temp wallet cleared (or Transfer to main verified)
`incomplete`	Submitted but temp still holds cNGN — retryable
`submitted`	Waiting for confirmation
`failed`	Consolidate failed

Until a bank accountNumber exists, status stays requested. RemitFlex sets va_created only when an account number is present. Payins appear in Transactions as cngn_payin. List payins for one customer:

curl "https://api.remitflex.io/v1/cngn/payins?customerId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $REMITFLEX_API_KEY"

Convert (cNGN ↔ USDC/USDT)

curl -X POST https://api.remitflex.io/v1/cngn/converts \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sellToken": "CNGN",
    "buyToken": "USDC",
    "amount": 5000,
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Field	Description
`customerId`	Required — cNGN-enabled customer UUID
`sellToken` / `buyToken`	`CNGN`, `USDC`, or `USDT` (must differ)
`amount`	Human-readable amount of `sellToken`
`slippage`	Optional max slippage %
`smartWalletAddress`	Optional; defaults to customer’s Smart Wallet
`destinationAddress`	Optional destination for output tokens

List: GET /v1/cngn/converts (optional ?customerId=). Get: GET /v1/cngn/converts/{convertId} ({convertId} is the RemitFlex convert UUID).

Withdrawal

Send tokens from the customer’s Smart Wallet to an external address:

curl -X POST https://api.remitflex.io/v1/cngn/withdrawals \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "internalWallet": "0xUserSmartWallet",
    "destinationWallet": "0xExternal",
    "amount": 100,
    "ticker": "CNGN",
    "network": "base"
  }'

customerId is required. List: GET /v1/cngn/withdrawals?customerId=...

Banks & account resolution

List banks and verify account names before payout:

curl https://api.remitflex.io/v1/cngn/banks \
  -H "Authorization: Bearer $REMITFLEX_API_KEY"

curl -X POST https://api.remitflex.io/v1/cngn/payouts/resolve-account \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountNumber": "0123456789", "bankCode": "058" }'

Returns 422 when the account cannot be verified or the bank is not supported. bankCode on payouts must come from GET /v1/cngn/banks.

Payout (cNGN → NGN bank)

curl -X POST https://api.remitflex.io/v1/cngn/payouts \
  -H "Authorization: Bearer $REMITFLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": 5000,
    "accountNumber": "0123456789",
    "bankCode": "058",
    "ticker": "CNGN"
  }'

customerId is required. amount is in Naira. Minimum payout is ₦151. List: GET /v1/cngn/payouts?customerId=...

Status, email, and webhooks

Money events are stored locally. On create/update RemitFlex:

Emails the linked customer (and org owner when applicable)
Emits merchant webhooks: cngn.deposit.*, cngn.payin.*, cngn.convert.*, cngn.withdrawal.*, cngn.payout.*

Customer enablement emits cngn.customer.enabled / cngn.customer.failed when BVN KYC finishes. Open payins / converts / payouts / withdrawals also refresh on read (GET /v1/cngn/payins/{payinId}, /converts/{convertId}, /payouts/{payoutId}, /withdrawals/{withdrawalId}, /deposits/{depositId}) and via background sync. All of the above appear in Transactions (cngn_deposit, cngn_payin, cngn_convert, cngn_withdrawal, cngn_payout).

Balances vs transactions

Need	Use
Live wallet balances	`GET /v1/cngn/customers/{customerId}/wallets` (or dashboard Refresh) — returns the primary Base Smart Wallet with live CNGN/USDC/USDT balances
Money history (source of truth)	`GET /v1/transactions?customerId=` and the cNGN list endpoints below with optional `?customerId=`

All cNGN money lists accept optional customerId — RemitFlex is customer-first; filter when reconciling a single counterparty:

GET /v1/cngn/payins?customerId=
GET /v1/cngn/deposits?customerId=
GET /v1/cngn/converts?customerId=
GET /v1/cngn/withdrawals?customerId=
GET /v1/cngn/payouts?customerId=

Get started

Concepts

Collect

Convert & FX

Local money

Customers & ledger

Integration

cNGN

Enable cNGN

Permanent vs temporary virtual accounts

Temporary payin (NGN → Smart Wallet)

Convert (cNGN ↔ USDC/USDT)

Withdrawal

Banks & account resolution

Payout (cNGN → NGN bank)

Status, email, and webhooks

Balances vs transactions

​Enable cNGN

​Permanent vs temporary virtual accounts

​Temporary payin (NGN → Smart Wallet)

​Convert (cNGN ↔ USDC/USDT)

​Withdrawal

​Banks & account resolution

​Payout (cNGN → NGN bank)

​Status, email, and webhooks

​Balances vs transactions

Enable cNGN

Permanent vs temporary virtual accounts

Temporary payin (NGN → Smart Wallet)

Convert (cNGN ↔ USDC/USDT)

Withdrawal

Banks & account resolution

Payout (cNGN → NGN bank)

Status, email, and webhooks

Balances vs transactions