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
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/jsonBody Parameters
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.
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.
chainis not required for FIAT payments or whenmodeisCHECKOUT.
CRYPTO Payment
The customer sends cryptocurrency directly to a blockchain address.
Request
Response
What to do with the response:
Display
collectionDetails.addressas the wallet address your customer sends funds toDisplay
amountInCryptoas the exact amount they must send (fee already included)platformFeeInCryptois Ivorypay's fee included inamountInCryptoPayment window expires at the returned
expiresAt; use the returnedvalidityPeriodfor a countdown timerStore
referencefor 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.
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, andcollectionDetails.accountNameto your customerDisplay
amountInFiatas the exact amount they must transfer (match this to the kobo/cent)The payment window is
validityPeriodseconds (600 = 10 minutes): display a countdown timerStore
referencefor reconciliation; listen to webhooks for settlement confirmation
The customer must transfer exactly
amountInFiatinfiatCurrency. 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:
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.
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.
Show the payable amount in your checkout.
For
nextAction.method: "GET", navigate the customer's browser tonextAction.url. For"POST", submit a browser form to that URL with the returnedparametersas hidden fields usingapplication/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.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.Use the signed
fiatCollection.success/fiatCollection.failedwebhooks, or pollGET /api/v1/transactions/:reference/statuswith 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.stepswhen present; Orange and MTN Côte d’Ivoire require manual USSD approval. There is no redirect whencheckoutUrlis 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:
checkoutUrlpresent (Wave): redirect the customer tocollectionDetails.checkoutUrl: there is noaccountNumberorbankNameto display. Confirm payment with the webhook or verification endpoint before fulfilling the order.No
checkoutUrl(other mobile money networks): do not redirect. Show anycollectionDetails.paymentInstructionsand 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 inbaseFiat; 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.
chainis not required: for crypto payment, the customer selects a network on the checkout pageFor ZAR, omit
paymentBrandandpaymentBank; method selection happens in checkoutredirect_urlis optional: if provided, the customer is redirected there after a successful payment with thereferenceappended 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
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
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
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
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)
USDT
Tether USD
USDC
USD Coin
chain (network)
Required for CRYPTO payments only.
BSC_MAINNET
Binance Smart Chain (BNB Chain)
BEP-20
POLYGON
Polygon (Matic Network)
ERC-20
Transaction Lifecycle
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