Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Accept Payment

Initiate IVB fiat or crypto collections with eligible currencies, customer approval and supported payment methods.

Collection requests require an explicit fiat currency grant for the business, in both TEST and LIVE. GET /api/v1/business-currencies/{businessId} returns the eligible currencies. A globally supported currency or an enabled payment method alone does not grant collection access. New requests and merchant quotes in an unenabled currency return HTTP 400 with errorCode: "COLLECTION_CURRENCY_NOT_ENABLED"; already admitted payments can still complete.

Use this endpoint to generate a payment request: a record your customer pays against. Ivorypay supports two payment channels:

  • CRYPTO: customer sends cryptocurrency to a blockchain address

  • FIAT: customer pays by bank transfer, bank authorization, 1Voucher, or mobile money, depending on the currency and method

Base path: /v1/transactions Authentication: API Key (Authorization: <secret-key>)


Endpoints

Method
Path
Auth
Description

POST

/v1/transactions

API Key

Create a payment collection request

GET

/v1/transactions/:reference/status

Secret API Key

Read the saved payment status for your business and key environment

GET

/v1/transactions/:reference/verify

Public

Verify payment status by reference


POST /v1/transactions

Creates a new incoming payment request. The response provides the payment instructions or retained result for the selected channel and method: a crypto address, bank account, bank authorization link, mobile-money approval flow, or direct voucher result.

Request

Headers

Authorization: <your-secret-api-key>
Content-Type: application/json

Body Parameters

Field
Type
Required
Description

amount

number

Yes

Amount in baseFiat when type: FIAT, or in crypto token units when type: CRYPTO. Must be >= 0; configured minimums also apply.

email

string

Yes

Customer's email address. Used for notifications.

firstName

string

No

Customer's first name.

lastName

string

No

Customer's last name.

type

string

Yes

CRYPTO or FIAT: sets the amount units. In API mode it also selects the collection channel. See CHECKOUT mode for hosted payment choices.

mode

string

Yes

Integration mode: API for programmatic integrations, CHECKOUT to use the Ivorypay hosted checkout page.

baseFiat

string

Yes

Fiat currency for pricing and conversion. It is the amount currency only when type: FIAT. See supported currencies.

crypto

string

Yes

Crypto token associated with the payment. See supported tokens.

chain

string

CRYPTO (API mode only)

Required when type is CRYPTO and mode is API. Not required in CHECKOUT mode. See chains.

phoneNumber

string

Conditional

Required for mobile money and 1Voucher; required when the Capitec Pay selection is CELLPHONE (the default). Capitec Pay uses the bank-linked number; 1Voucher uses the customer's mobile number for change vouchers and refunds. ZAR formats: 0821234567 or +27821234567. Optional for EFT.

verifiedIdNumber

string

No

Optional, Capitec Pay only: the payer's previously verified 13-digit South African national ID. Supplied from your backend using the secret key. Requires explicit capitecIdentifierType: "IDNUMBER"; do not combine with capitecIdNumber or an account selection. It is not a TIN. See Verified-ID flow.

capitecIdentifierType

string

Conditional

Capitec Pay payment proxy: CELLPHONE, IDNUMBER or ACCOUNTNUMBER. Required with an ID/account field. Omitted preserves legacy phone selection.

capitecIdNumber

string

IDNUMBER only

Customer-entered 13-digit South African national ID. Does not assert verification. Send instead of verifiedIdNumber; not a TIN.

capitecAccountNumber

string

ACCOUNTNUMBER only

Customer's 10-digit Capitec consumer account. Preserve leading zeroes by sending a string. Not a national ID or TIN.

paymentBrand

string

ZAR direct API

CAPITECPAY, EFT or 1FORYOU (1Voucher). Only send with type: FIAT, mode: API, and baseFiat: ZAR. Omit for hosted checkout.

voucherPin

string

1Voucher only

Customer's 16-digit PIN, request-only. Never retain or log it. See 1Voucher payments.

authorizationMode

string

No

ZAR bank API payments only: DIRECT returns EFT/Capitec Pay provider instructions; HOSTED is the default. Requires paymentBrand. Omit for 1Voucher.

paymentBank

string

No

Omit for Capitec Pay, EFT and 1Voucher. For EFT, the customer chooses their bank during authorization.

mobileMoneyNetwork

string

No

Wave only: WAVE_CIV (Côte d'Ivoire, +225 number) or WAVE_SEN (Senegal, +221 number). Use it to charge a Wave wallet that is on another carrier's number (for example an Orange number). XOF collections in API mode only. When omitted, the network is detected from phoneNumber as before. See Collecting from a Wave wallet.

reference

string

Yes

A unique UUID you save for duplicate detection and reconciliation.

redirect_url

string

Required for bank DIRECT

Customer return URL for checkout or bank authorization. For direct ZAR bank payments it must be HTTPS without embedded credentials. Not required for 1Voucher. Returning to this URL is not proof of payment.

metadata

string

No

Any JSON string stored on the transaction. Returned as-is in webhooks.

collectionQuote

string

No

Optional five-minute approval token from the merchant conversion endpoint. For FIAT API collections only. See collection totals and approval. Existing requests do not require it.

splitGroupId

string

No

UUID of an active split group owned by this business in the current environment. Its allocation currency must match the payment.

chain is not required for FIAT payments or when mode is CHECKOUT.


CRYPTO Payment

The customer sends cryptocurrency directly to a blockchain address.

Request

Response

What to do with the response:

  • Display collectionDetails.address as the wallet address your customer sends funds to

  • Display amountInCrypto as the exact amount they must send (fee already included)

  • platformFeeInCrypto is Ivorypay's fee included in amountInCrypto

  • Payment window expires at the returned expiresAt; use the returned validityPeriod for a countdown timer

  • Store reference for order reconciliation and webhook matching

CRYPTO Payment Mismatches and Refunds

For crypto collections, the customer should send the exact amountInCrypto in the selected currency/token to the returned wallet address.

Scenario
Outcome

Underpayment

The transaction fails and the received funds are refunded to the customer.

Overpayment

The transaction succeeds and the excess amount is refunded to the customer.

Token mismatch

The transaction fails and the received funds are refunded to the customer.


FIAT Payment

Ivorypay assigns payment instructions for the selected method. Settlement follows the accepted collection terms. With payout wallets disabled, proceeds settle in the configured crypto token. With payout wallets enabled, future fiat collections retain their original fiat currency for manual funding unless a saved active rule explicitly selects a stablecoin. Funding a payout wallet in the same fiat currency needs no FX. The collection status/detail and webhook field settlementCredit identifies the actual wallet credit separately from its crypto valuation. Existing accepted collections keep their original terms.

Request

Response

What to do with the response:

  • Display collectionDetails.bankName, collectionDetails.accountNumber, and collectionDetails.accountName to your customer

  • Display amountInFiat as the exact amount they must transfer (match this to the kobo/cent)

  • The payment window is validityPeriod seconds (600 = 10 minutes): display a countdown timer

  • Store reference for reconciliation; listen to webhooks for settlement confirmation

The customer must transfer exactly amountInFiat in fiatCurrency. Sending a different amount may cause a mismatch.


ZAR 1Voucher payments

Use type: "FIAT", mode: "API", baseFiat: "ZAR" and paymentBrand: "1FORYOU" with the customer's South African mobile number and request-only 16-digit voucherPin. Keep the required crypto valuation field and your UUID reference. Omit authorizationMode: "DIRECT", which is bank-only. No checkout page or redirect is required.

See 1Voucher payments for the complete request and response examples, phone formats, fee review, safe PIN handling and same-reference recovery after a timeout or HTTP 503. Confirm the retained Business payment status and normal webhooks before fulfilment.

ZAR bank payments: Capitec Pay and EFT

Choose the experience you want to provide:

Experience
Request
Customer action

Your own checkout

type: FIAT, mode: API, baseFiat: ZAR, authorizationMode: DIRECT, and paymentBrand: CAPITECPAY or EFT

Follow collectionDetails.nextAction directly to bank/provider authorization

Ivorypay hosted checkout

type: FIAT, mode: CHECKOUT, baseFiat: ZAR; omit paymentBrand and paymentBank

Open collectionDetails.checkoutUrl; Ivorypay handles method selection and payment instructions

API initiation happens on your server. With authorizationMode: "DIRECT", the customer does not visit an Ivorypay page. Both Capitec Pay and EFT still require customer bank authorization. Capitec currently returns a provider approval page that must be opened while the customer approves in their banking app; this is not a push-only flow that stays on your checkout. PayShap is not currently available.

Direct API request: Capitec Pay

For EFT, use paymentBrand: "EFT". The phone number is optional; omit paymentBank and let the customer select their bank during authorization. For the Capitec Pay phone flow, supply the customer's South African bank-linked phone number in local (0821234567) or international (+27821234567) format. They do not enter it again on an Ivorypay form. Keep your API key on your server.

Capitec Pay identifier selection

The ID and account selectors are part of this API/checkout update. Confirm rollout in your environment with Ivorypay before using them. Provider capability alone does not establish that an Ivorypay deployment is enabled; existing phone-only requests remain supported.

Choose exactly one Capitec Pay payment identifier. capitecIdentifierType selects it explicitly; the value is never inferred from its length. Existing requests containing only phoneNumber may omit the selector and keep the phone flow.

Selection
Required value
Meaning

CELLPHONE

phoneNumber

Customer's South African bank-linked phone number.

IDNUMBER

capitecIdNumber or merchant-only verifiedIdNumber

Exactly 13 digits: South African national ID, not a bank account, passport or TIN. capitecIdNumber is customer-entered and does not assert verification.

ACCOUNTNUMBER

capitecAccountNumber

Exactly 10 digits for this Capitec consumer-account flow. This is separate from the national ID.

The ID/account checkout form asks only for the selected identifier. Do not send both ID fields or combine an ID field with an account field. A verified ID is not an extra KYC field sent alongside a different phone/account proxy.

Capitec still requires the customer to approve payment in its app. The identifier locates the customer; it does not itself debit the account or prove payment.

Capitec Pay verified-ID flow

verifiedIdNumber is optional for current integrations and only asserts prior merchant verification. To use it, explicitly select IDNUMBER and omit capitecIdNumber. Verify the customer's identity first using a mechanism accepted by Capitec; checking 13 digits does not verify identity. Keep the verified ID and secret key on your backend. The customer cannot edit the accepted verified identity. No TIN is requested by this flow.

Replace the ID placeholder with the payer's actual verified 13-digit value. Passport numbers are not supported. Do not send private identifiers in URL parameters or logs. Public checkout accepts only a customer-entered capitecIdNumber; it cannot supply the merchant-only verifiedIdNumber assertion. The public-key SDK endpoint POST /api/v1/transactions/client/initiate also rejects verifiedIdNumber before admission; use the secret-key POST /api/v1/transactions endpoint for that assertion. The SDK can still select phone, customer-entered ID or account number for the ordinary flow. The accepted ID is saved privately and remains unchanged during recovery; it is not returned in status, receipts or webhooks. After an uncertain response, recover the original reference instead of substituting another ID or submitting again.

Risk is assigned by Capitec to the processing account, not inferred from transaction size. This feature does not classify existing merchants as high risk. If your processing account is subject to a verified-ID requirement, the ID becomes mandatory for Capitec Pay and phone/account and customer-entered, unverified ID requests are rejected. Otherwise, it remains your choice. Bank authorization and the existing status/webhook completion checks still apply to all three identifier types.

If you use approved collection quotes, request an ID-based quote with the POST body described there. Do not put the ID into the GET quote URL. Submit the same ID with the returned collectionQuote and original reference; changing the selector, verification provenance or identifier invalidates that quote.

Capitec Pay account-number example

Replace the placeholder with the customer's actual 10-digit Capitec consumer account. For the normal customer-entered ID option, use the same request with capitecIdentifierType: "IDNUMBER" and capitecIdNumber: "<13_DIGIT_SA_ID>", omitting capitecAccountNumber and verifiedIdNumber.

In the Ivorypay checkout, customers can choose phone, ID or account before admission under the normal flow. That self-entered ID is never represented as merchant verification. For a merchant-verified locked hosted payment, initiate through this secret-key API with authorizationMode: "HOSTED" (or omit it) and verifiedIdNumber; the returned retained bank action does not offer an editable identifier. Recovery reuses the saved action and private terms.

Response excerpt: direct API

The URL and parameters above are placeholders. Use the actual response, including amountInFiat and fee fields.

  1. Show the payable amount in your checkout.

  2. For nextAction.method: "GET", navigate the customer's browser to nextAction.url. For "POST", submit a browser form to that URL with the returned parameters as hidden fields using application/x-www-form-urlencoded. Preserve every name/value and use DOM APIs or HTML escaping. A POST action cannot be replaced by opening its URL.

  3. Open the action in the customer's browser, not your backend. Keep URLs and parameters out of logs and analytics and respect expiresAt. No action is returned after expiry or completion; an absent action does not mean payment succeeded.

  4. Use the signed fiatCollection.success / fiatCollection.failed webhooks, or poll GET /api/v1/transactions/:reference/status with your secret key. Match the successful reference and amounts before fulfilment. Initiation, browser return and bank approval alone are not payment confirmation.

The status endpoint reads saved state without initiating or resubmitting a payment. Its data.status is scoped to your business and the API key's TEST/LIVE environment. A reference outside that scope returns 404; a public key is rejected.

If initiation times out, keep the original reference and call POST /api/v1/transactions/:reference/fiat-allocation/recover with the same secret key and an empty JSON body. Recovery retains the payment's original authorization mode and return URL. status: "allocation_confirmed" confirms instructions, not payment success; read paymentStatus. Rejected recovery can return errorCode, paymentStatus: "FAILED" and retrySafe: false. Read the status endpoint before deciding what to show. Do not create another reference merely to recover a lost response.

With a TEST key, direct payments return nextAction.type: "TEST_SIMULATION" instead of a provider URL. Use Simulate Fiat Payments to test success, failure and expiry. Merchant TEST mode does not contact the provider sandbox.

ZAR does not return a virtual account. Existing API integrations that omit authorizationMode retain the Ivorypay BANK_AUTHORIZATION handoff, including its complete URL fragment. Requests without paymentBrand retain the checkout-link flow. Use mode: "CHECKOUT" for general hosted checkout.


Mobile Money Payment

For mobile money currencies such as XOF, approval depends on the network:

  • Wave (Senegal and Côte d'Ivoire): the response includes collectionDetails.checkoutUrl; open it for customer approval.

  • Other mobile money networks (MTN, Airtel, M-Pesa, Orange, Moov, etc.): the customer approves on their phone. Display collectionDetails.paymentInstructions.steps when present; Orange and MTN Côte d’Ivoire require manual USSD approval. There is no redirect when checkoutUrl is absent.

The request looks the same as any other FIAT payment, with phoneNumber required for mobile money:

Request

Response: Wave in Senegal / Côte d'Ivoire

For mobile money networks other than Wave the response has the same top-level fields, but collectionDetails contains no checkoutUrl.

What to do with the response:

  • checkoutUrl present (Wave): redirect the customer to collectionDetails.checkoutUrl: there is no accountNumber or bankName to display. Confirm payment with the webhook or verification endpoint before fulfilling the order.

  • No checkoutUrl (other mobile money networks): do not redirect. Show any collectionDetails.paymentInstructions and wait for confirmation. Do not assume every network sends an automatic PIN prompt. See mobile money approval.

  • See Mobile Money Payments for the full list of supported countries and networks, and the payout flow. Refunds are not available for mobile money collections.


CHECKOUT Mode

Use mode: CHECKOUT to redirect your customer to the Ivorypay hosted checkout page instead of building your own payment UI. Ivorypay handles the payment flow: your customer selects the payment type, completes the payment, and is redirected back to your site.

  • With type: FIAT, the amount is in baseFiat; the checkout can offer bank payment and crypto when those methods are enabled for your business.

  • With type: CRYPTO, the amount is in token units and the checkout offers crypto payment.

  • Selecting Bank transfer reveals EFT and Capitec Pay for ZAR. These are payment choices within the bank-transfer flow.

  • chain is not required: for crypto payment, the customer selects a network on the checkout page

  • For ZAR, omit paymentBrand and paymentBank; method selection happens in checkout

  • redirect_url is optional: if provided, the customer is redirected there after a successful payment with the reference appended as a query parameter

Request

Response

Redirect your customer to collectionDetails.checkoutUrl exactly as returned, including any query parameters. After a successful payment, they will be sent to:

On your server, call the authenticated transaction verification endpoint with your secret key. Match SUCCESS, reference and amounts to your saved order before fulfilling it.


CRYPTO vs FIAT: Response Comparison

Field
CRYPTO
FIAT

channel

"CRYPTO"

"FIAT"

collectionDetails.address

Blockchain wallet address to send funds to

Not applicable

collectionDetails.network

Blockchain network (e.g. BSC_MAINNET)

Not applicable

collectionDetails.accountName

Not applicable

Beneficiary account name

collectionDetails.accountNumber

Not applicable

Beneficiary account number

collectionDetails.bankName

Not applicable

Beneficiary bank name

collectionDetails.checkoutUrl

Not applicable

Ivorypay checkout link in hosted mode, legacy ZAR API requests without paymentBrand, and Wave. Direct ZAR bank payments use nextAction; 1Voucher needs neither field

collectionDetails.nextAction

Not applicable

Direct ZAR bank authorization: { type: "BANK_AUTHORIZATION", url, expiresAt }

amountInCrypto

Exact crypto amount to send (fee included)

Not applicable

platformFeeInCrypto

Ivorypay's fee included in amountInCrypto

Not applicable

amountInFiat

Fiat equivalent of the crypto amount

Exact payable amount for the selected method

fiatCurrency

Fiat currency of amountInFiat

Payment currency (NGN, ZAR, etc.)

platformFeeInFiat

Not applicable

Ivorypay's fee; collectionFeeBearer determines whether the customer pays it or the merchant absorbs it

validityPeriod

Returned seconds until the payment window closes

Returned seconds until the payment window closes

expiresAt

ISO timestamp when the payment window closes

Payment window expiry where returned; expiry does not prove non-payment


Error Responses

Status
Message
Cause

400

amount must not be less than 0

Negative amount

400

email must be an email

Invalid email format

400

type must be one of FIAT, CRYPTO

Invalid type value

400

network chain must be one of ...

Invalid or missing chain for CRYPTO

401

Unauthorized

Missing or invalid API key


GET /v1/transactions/:reference/verify

Verifies the current payment status of a transaction by reference. This endpoint is public: no API key required. Use it to display a limited payment receipt. For order fulfilment, use the authenticated transaction verification endpoint on your server and reconcile against your saved order.

Request

Path Parameters

Parameter
Type
Description

reference

string

Transaction reference string

Example

Response

This public receipt omits customer details and full settlement data. Use the authenticated transaction verification on your server to match the order and confirm fulfilment. A successful HTTP request is not itself a successful payment.


Supported Values

The following are examples. Use Supported tokens and networks and the routes enabled for your business; this list is not an availability guarantee.

baseFiat

Value
Currency

NGN

Nigerian Naira

ZAR

South African Rand (see Capitec Pay and EFT)

XOF

West African CFA Franc (Wave, and other mobile money: see Mobile Money Payment)

USD

US Dollar

crypto (token)

Value
Name

USDT

Tether USD

USDC

USD Coin

chain (network)

Required for CRYPTO payments only.

Value
Network Name
Standard

BSC_MAINNET

Binance Smart Chain (BNB Chain)

BEP-20

POLYGON

Polygon (Matic Network)

ERC-20


Transaction Lifecycle

Status
Description

PENDING

Transaction created, waiting for the customer to pay

PROCESSING

Payment detected, being processed

CONFIRMING

Awaiting sufficient confirmations

SUCCESS

Payment confirmed, funds credited to your wallet

MISMATCH

Customer sent less than expected or sent the wrong token

EXPIRED

Payment window closed with no payment received

FAILED

Transaction failed

Use the returned expiry/validity period for the payment window. After expiry, reconcile the original reference before initiating another payment. For CRYPTO payments, underpayments and token mismatches can trigger a failed payment and a separate refund process; overpayments can trigger a refund of the excess. A payment status does not prove refund completion. Track the refund outcome before promising that funds have been returned.


Integration Flow

CRYPTO

FIAT: virtual account

For ZAR, follow the bank authorization flow. This example is for a currency that returns a virtual account:


Code Examples

Node.js: FIAT

Node.js: CRYPTO

cURL: FIAT

cURL: CRYPTO

Last updated