Create and track deposits, withdrawals, and swaps.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/afriex-transactions-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Afriex Business Transactions API
version: 1.0.13
description: 'Welcome to the Afriex Business API. This API allows you to manage customers, process payments, handle payouts, and receive real-time notifications via webhooks.
For detailed guidance on authentication, pagination, error handling, and webhooks, please refer to the dedicated guides in the top bar. The guide provides a step-by-step instructions to help you integrate seamlessly.'
termsOfService: https://www.afriex.com/terms-and-condition
contact:
name: Afriex API Support
email: support@afriex.com
url: https://docs.afriex.com
license:
name: Proprietary
url: https://www.afriex.com/terms-and-condition
servers:
- url: https://sandbox.api.afriex.com
description: Staging Base URL
- url: https://api.afriex.com
description: Production Base URL
security:
- ApiKey: []
tags:
- name: Transactions
description: Create and track deposits, withdrawals, and swaps.
paths:
/api/v1/transaction:
parameters:
- $ref: '#/components/parameters/x-api-version'
post:
operationId: createTransaction
summary: Create a new transaction
description: 'Create a new transaction to process a payment for a customer. Use `type: WITHDRAW` to send funds to a destination payment method (requires `destinationId`), `type: DEPOSIT` to pull funds from a source payment method (requires `sourceId`), or `type: SWAP` to convert funds between currencies within the Afriex wallet (requires `sourceCurrency`, `destinationCurrency`, `meta`, and exactly one of `sourceAmount` or `destinationAmount`).'
tags:
- Transactions
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
description: The unique identifier of the customer. Required for DEPOSIT and WITHDRAW transactions. Not required for SWAP, if omitted, the transaction runs against the business wallet.
examples:
- 69528240ba52c13b669fb239
type:
type: string
description: The type of transaction. DEPOSIT pulls funds from the customer's source payment method (requires sourceId). WITHDRAW sends funds to the customer's destination payment method (requires destinationId). SWAP converts funds between currencies within the Afriex wallet (requires sourceCurrency, destinationCurrency, meta, and exactly one of sourceAmount or destinationAmount; the API computes the other side at the live exchange rate, and sending both is rejected). If omitted, defaults to WITHDRAW.
enum:
- DEPOSIT
- WITHDRAW
- SWAP
sourceAmount:
description: 'The transaction amount in the source currency. For WITHDRAW, provide exactly one of sourceAmount or destinationAmount: sending sourceAmount alone lets the API compute destinationAmount at the live forward rate (useful when you know only how much you want to send, e.g. a SWIFT payout of a fixed source balance). For DEPOSIT the required amount is destinationAmount, so sourceAmount is optional. For SWAP, provide exactly one of sourceAmount or destinationAmount: setting sourceAmount makes the API compute destinationAmount at the live exchange rate.'
$ref: '#/components/schemas/amount'
destinationAmount:
description: 'The transaction amount in the destination currency. Required for DEPOSIT. For WITHDRAW, provide exactly one of sourceAmount or destinationAmount: setting destinationAmount fixes the payout amount, while omitting it and sending sourceAmount lets the API compute destinationAmount at the live forward rate. For SWAP, provide exactly one of sourceAmount or destinationAmount: setting destinationAmount instead makes the API compute sourceAmount at the inverse rate. Sending both amounts on a SWAP is rejected.'
$ref: '#/components/schemas/amount'
destinationCurrency:
type: string
description: The 3-letter ISO 4217 currency code of the destination currency (e.g., USD, NGN).
examples:
- USD
sourceCurrency:
type: string
description: The 3-letter ISO 4217 currency code of the source currency (e.g., USD, NGN).
examples:
- NGN
destinationId:
type: string
description: 'Required for WITHDRAW transactions. The id of the destination payment method that money will be sent to.
'
examples:
- 690df3281c11eea59108fcaf
sourceId:
type: string
description: 'Required for DEPOSIT transactions. The id of the source payment method that money will be pulled from.
'
examples:
- 690df3281c11eea59108fcaf
meta:
description: Transaction metadata. idempotencyKey and reference are required.
$ref: '#/components/schemas/TransactionMeta'
shouldPreferSourceAmount:
type: boolean
description: Opt in to deriving destinationAmount from sourceAmount even when both amounts are sent. Defaults to false, which keeps destination-wins semantics so a caller that echoes both amounts still gets the destinationAmount they asked for. Set true to have sourceAmount drive the payout via the forward rate.
correspondentBankName:
type: string
description: The correspondent (intermediary) bank name for USD payouts (WITHDRAW with destinationCurrency USD and meta.settlement 'request'). Only used as a fallback when the destination payment method lacks it — the payment method's value takes precedence. Must be provided together with correspondentBankAccountNumber.
correspondentBankAccountNumber:
type: string
description: The correspondent (intermediary) bank account number for USD payouts (WITHDRAW with destinationCurrency USD and meta.settlement 'request'). Only used as a fallback when the destination payment method lacks it — the payment method's value takes precedence. Must be provided together with correspondentBankName.
oneOf:
- title: Withdraw
description: Send funds to a customer's destination payment method. This is the default when type is omitted. Provide exactly one of sourceAmount or destinationAmount; sending sourceAmount alone lets the API compute the destination side at the live forward rate.
required:
- customerId
- sourceCurrency
- destinationCurrency
- destinationId
- meta
properties:
type:
enum:
- WITHDRAW
- title: Deposit
description: Pull funds from a customer's source payment method.
required:
- type
- customerId
- destinationAmount
- sourceCurrency
- destinationCurrency
- sourceId
- meta
properties:
type:
enum:
- DEPOSIT
- title: Swap
description: Convert funds between currencies within the Afriex wallet. Provide exactly one of sourceAmount or destinationAmount; sending both is rejected.
required:
- type
- sourceCurrency
- destinationCurrency
- meta
properties:
type:
enum:
- SWAP
examples:
Withdraw:
summary: 'Withdraw (destination amount): fix the payout amount the customer receives'
value:
customerId: 69528240ba52c13b669fb239
type: WITHDRAW
destinationAmount: 5000
sourceCurrency: USD
destinationCurrency: NGN
destinationId: 690df3281c11eea59108fcaf
meta:
reference: ref-withdraw-001
idempotencyKey: idem-withdraw-001
WithdrawSourceAmount:
summary: 'Withdraw (source amount, SWIFT MZN→USD): send the full source balance and let the API compute the payout at the live forward rate'
value:
customerId: 69528240ba52c13b669fb239
type: WITHDRAW
sourceAmount: 10000
sourceCurrency: MZN
destinationCurrency: USD
destinationId: 690df3281c11eea59108fcaf
meta:
reference: ref-withdraw-002
idempotencyKey: idem-withdraw-002
Deposit:
summary: Deposit, pull funds from a customer's source payment method
value:
customerId: 69528240ba52c13b669fb239
type: DEPOSIT
sourceAmount: '10'
destinationAmount: 5000
sourceCurrency: USD
destinationCurrency: NGN
sourceId: 690df3281c11eea59108fcaf
meta:
reference: ref-deposit-001
idempotencyKey: idem-deposit-001
Swap:
summary: 'Swap (source-only): convert funds between currencies within the Afriex wallet'
value:
type: SWAP
sourceAmount: 10
sourceCurrency: USD
destinationCurrency: NGN
meta:
reference: ref-swap-001
idempotencyKey: idem-swap-001
SwapDestination:
summary: 'Swap (destination-only): the API computes the source amount at the inverse rate'
value:
type: SWAP
destinationAmount: 16500
sourceCurrency: USD
destinationCurrency: NGN
meta:
reference: ref-swap-002
idempotencyKey: idem-swap-002
responses:
'201':
description: Transaction created successfully.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Transaction'
examples:
withdraw:
summary: WITHDRAW transaction created (pending)
value:
data:
status: PENDING
type: WITHDRAW
channel: BANK_ACCOUNT
sourceAmount: '3.28847'
sourceCurrency: USD
destinationAmount: '5000'
destinationCurrency: NGN
destinationId: 690df3281c11eea59108fcaf
customerId: 69528240ba52c13b669fb239
transactionId: 69d60071ab82306f11b03393
meta:
reference: ref-withdraw-001
idempotencyKey: idem-withdraw-001
createdAt: '2026-04-08T07:14:57.444Z'
updatedAt: '2026-04-08T07:14:57.444Z'
swap:
summary: SWAP transaction created (success)
value:
data:
status: SUCCESS
type: SWAP
channel: WALLET
sourceAmount: '10'
sourceCurrency: USD
destinationAmount: '14101.041'
destinationCurrency: NGN
destinationId: ''
customerId: ''
transactionId: 69d60072ab82306f11b033b9
meta:
reference: ref-swap-001
idempotencyKey: idem-swap-001
createdAt: '2026-04-08T07:14:58.237Z'
updatedAt: '2026-04-08T07:14:58.237Z'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
swapBothAmounts:
summary: SWAP with both amounts provided
value:
code: INVALID_BUSINESS_TRANSACTION_REQUEST
error: Invalid business transaction request
details:
errorMessage: Invalid business transaction request
friendlyMessage: Only one of source amount or destination amount can be provided
missingDestinationAmount:
summary: Missing destination amount
value:
code: INVALID_BUSINESS_TRANSACTION_REQUEST
error: Invalid business transaction request
details:
errorMessage: Invalid business transaction request
friendlyMessage: Invalid destination amount
invalidCurrency:
summary: Invalid currency code
value:
code: INVALID_BUSINESS_TRANSACTION_REQUEST
error: Invalid business transaction request
details:
errorMessage: Invalid business transaction request
friendlyMessage: Invalid source currency
missingIdempotencyKey:
summary: Missing idempotency key
value:
code: INVALID_BUSINESS_TRANSACTION_REQUEST
error: Invalid business transaction request
details:
errorMessage: Invalid business transaction request
friendlyMessage: No idempotency key provided
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
code: AUTHENTICATION_ERROR
error: Authorization header is missing
details: {}
invalidApiKey:
summary: Invalid API key
value:
code: AUTHENTICATION_ERROR
error: Invalid authorization header
details: {}
'404':
description: Not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
customerNotFound:
summary: Customer not found
value:
code: USER_NOT_FOUND
error: User not found
details:
errorMessage: User not found
friendlyMessage: ''
'500':
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serverError:
summary: Unexpected server error
value:
code: INTERNAL_SERVER_ERROR
error: It's not you, it's us, please reach out to support
details: {}
'503':
description: 'Temporarily unavailable: an upstream payment processor failed or timed out, or the API is restarting. Retry with backoff and honour the Retry-After header when present. The API never returns 502 or 504; if you receive one of those, it was generated by Cloudflare and its body does not follow this schema.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serviceUnavailable:
summary: Upstream processor unavailable
value:
code: EXTERNAL_REQUEST_ERROR
error: External request error
details: {}
x-codeSamples:
- lang: TypeScript
label: Afriex SDK
source: "const transaction = await afriex.transactions.create({\n customerId: \"customer-id\",\n sourceAmount: \"10\",\n destinationAmount: \"5000\",\n sourceCurrency: \"USD\",\n destinationCurrency: \"NGN\",\n destinationId: \"payment-method-id\",\n meta: {\n idempotencyKey: \"unique-key-123\",\n reference: \"order-456\",\n narration: \"Payment for services\",\n },\n});\n"
get:
operationId: listTransactions
summary: Get transaction list
description: Retrieves a paginated list of transactions.
tags:
- Transactions
parameters:
- name: page
in: query
description: Zero-based page number for pagination.
required: false
schema:
type: integer
minimum: 0
default: 0
- name: limit
in: query
description: Number of items per page (max 100).
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 10
- name: transactionId
in: query
description: Filter by the Afriex transaction ID (`transactionId`) returned when the transaction was created.
required: false
schema:
type: string
- name: reference
in: query
description: Filter by the merchant-supplied reference set in `meta.reference` at transaction creation.
required: false
schema:
type: string
- name: status
in: query
description: Filter by one or more transaction statuses. Use a comma-separated list for multiple values (e.g. `?status=PENDING,PROCESSING`).
required: false
schema:
type: array
items:
type: string
enum:
- PENDING
- PROCESSING
- SUCCESS
- FAILED
- CANCELLED
- REFUNDED
- RETRY
- UNKNOWN
- SCHEDULED
- CUSTOMER_ACTION_REQUIRED
- REJECTED
- IN_REVIEW
- CHECKER_APPROVAL_REQUIRED
- ENGINEERING_REVIEW_REQUIRED
- RFI_REQUESTED
- DISPUTED
- DISPUTE_RESOLVED
- DISPUTE_WON
- DISPUTE_LOST
- DISPUTE_EVIDENCE_SUBMITTED
style: form
explode: false
- name: type
in: query
description: Filter by one or more transaction types. Use a comma-separated list for multiple values (e.g. `?type=DEPOSIT,WITHDRAW`).
required: false
schema:
type: array
items:
type: string
enum:
- DEPOSIT
- WITHDRAW
- SWAP
style: form
explode: false
- name: channel
in: query
description: Filter by one or more payment channels (source or destination). Use a comma-separated list for multiple values (e.g. `?channel=BANK_ACCOUNT,MOBILE_MONEY`).
required: false
schema:
type: array
items:
type: string
enum:
- BANK_ACCOUNT
- MOBILE_MONEY
- CARD
- CRYPTO
- VIRTUAL_BANK_ACCOUNT
- ACH_BANK_ACCOUNT
- INTERAC
- PAYBILL_TILL
- RFP
- UPI
- VIRTUAL_CARD
- SWIFT
- WE_CHAT
- ALIPAY
- WALLET
style: form
explode: false
- name: currency
in: query
description: Filter by one or more 3-letter ISO 4217 currency codes (source or destination). Use a comma-separated list for multiple values (e.g. `?currency=USD,NGN`).
required: false
schema:
type: array
items:
type: string
examples:
- USD
style: form
explode: false
- name: fromDate
in: query
description: Return only transactions created on or after this ISO 8601 date-time (e.g. `2025-01-01T00:00:00.000Z`).
required: false
schema:
type: string
format: date-time
- name: toDate
in: query
description: Return only transactions created on or before this ISO 8601 date-time. Must be equal to or later than `fromDate`.
required: false
schema:
type: string
format: date-time
responses:
'200':
description: List of transactions retrieved successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
page:
type: integer
description: Current page number
total:
type: integer
description: Total number of transactions matching the query
examples:
success:
summary: Transaction list retrieved
value:
data:
- status: SUCCESS
type: SWAP
channel: WALLET
sourceAmount: '10'
sourceCurrency: USD
destinationAmount: '14101.041'
destinationCurrency: NGN
destinationId: ''
customerId: 68e6717848e1f632e9686460
transactionId: 69d3c79531c0234586ad5ee0
meta:
reference: ref-swap-minimal-002
idempotencyKey: idem-swap-minimal-002
createdAt: '2026-04-06T14:47:49.166Z'
updatedAt: '2026-04-06T14:47:49.166Z'
- status: PENDING
type: WITHDRAW
channel: BANK_ACCOUNT
sourceAmount: '3.28847'
sourceCurrency: USD
destinationAmount: '5000'
destinationCurrency: NGN
destinationId: 690df3281c11eea59108fcaf
customerId: 69528240ba52c13b669fb239
transactionId: 69d60071ab82306f11b03393
meta:
reference: ref-withdraw-001
idempotencyKey: idem-withdraw-001
createdAt: '2026-04-08T07:14:57.444Z'
updatedAt: '2026-04-08T07:14:57.444Z'
total: 285
page: 0
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
code: AUTHENTICATION_ERROR
error: Authorization header is missing
details: {}
invalidApiKey:
summary: Invalid API key
value:
code: AUTHENTICATION_ERROR
error: Invalid authorization header
details: {}
'422':
description: Request failed schema validation. `details.friendlyMessage` carries the specific field error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
validationError:
summary: Validation error
value:
code: VALIDATION_ERROR
error: Validation error
details:
errorMessage: Validation error
friendlyMessage: '''page'' must be a number'
'500':
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serverError:
summary: Unexpected server error
value:
code: INTERNAL_SERVER_ERROR
error: It's not you, it's us, please reach out to support
details: {}
'503':
description: 'Temporarily unavailable: an upstream payment processor failed or timed out, or the API is restarting. Retry with backoff and honour the Retry-After header when present. The API never returns 502 or 504; if you receive one of those, it was generated by Cloudflare and its body does not follow this schema.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serviceUnavailable:
summary: Upstream processor unavailable
value:
code: EXTERNAL_REQUEST_ERROR
error: External request error
details: {}
x-codeSamples:
- lang: TypeScript
label: Afriex SDK
source: "const response = await afriex.transactions.list({\n page: 0,\n limit: 20,\n status: [\"PENDING\", \"PROCESSING\"],\n currency: [\"USD\", \"NGN\"],\n fromDate: \"2026-01-01T00:00:00.000Z\",\n toDate: \"2026-01-31T23:59:59.999Z\",\n});\n\nconsole.log(response.data); // Transaction[]\n"
/api/v1/transaction/{transactionId}:
parameters:
- $ref: '#/components/parameters/x-api-signature'
- $ref: '#/components/parameters/x-api-version'
get:
operationId: getTransaction
summary: Get transaction by ID
description: Retrieves a specific transaction by its unique identifier.
tags:
- Transactions
parameters:
- name: transactionId
in: path
description: The unique identifier of the transaction
required: true
schema:
type: string
responses:
'200':
description: Transaction retrieved successfully.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Transaction'
examples:
success:
summary: Transaction retrieved
value:
data:
status: SUCCESS
type: SWAP
channel: WALLET
sourceAmount: '10'
sourceCurrency: USD
destinationAmount: '14101.041'
destinationCurrency: NGN
destinationId: ''
customerId: 68e6717848e1f632e9686460
transactionId: 69d3c79531c0234586ad5ee0
meta:
reference: ref-swap-minimal-002
idempotencyKey: idem-swap-minimal-002
createdAt: '2026-04-06T14:47:49.166Z'
updatedAt: '2026-04-06T14:47:49.166Z'
'400':
description: Invalid transaction ID format.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
validationError:
summary: Validation error
value:
code: VALIDATION_ERROR
error: 'Failed to parse request. Issues: ''transactionId'' must be a string'
details: {}
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
code: AUTHENTICATION_ERROR
error: Authorization header is missing
details: {}
invalidApiKey:
summary: Invalid API key
value:
code: AUTHENTICATION_ERROR
error: Invalid authorization header
details: {}
'404':
description: Transaction not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
notFound:
summary: Transaction not found
value:
code: BUSINESS_TRANSACTION_NOT_FOUND
error: Business transaction not found
details:
errorMessage: Business transaction not found
friendlyMessage: ''
'500':
description: Server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serverError:
summary: Unexpected server error
value:
code: INTERNAL_SERVER_ERROR
error: It's not you, it's us, please reach out to support
details: {}
'503':
description: 'Temporarily unavailable: an upstream payment processor failed or timed out, or the API is restarting. Retry with backoff and honour the Retry-After header when present. The API never returns 502 or 504; if you receive one of those, it was generated by Cloudflare and its body does not follow this schema.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
serviceUnavailable:
summary: Upstream processor unavailable
value:
code: EXTERNAL_REQUEST_ERROR
error: External request error
details: {}
x-codeSamples:
- lang: TypeScript
label: Afriex SDK
source: 'const transaction = await afriex.transactions.get("transaction-id");
'
/api/v1/transaction/{transactionId}/authorize:
parameters:
- $ref: '#/components/parameters/x-api-version'
post:
operationId: authorizeTransaction
summary: Authorize a pending transaction
description: Completes a transaction that was created in a `CUSTOMER_ACTION_REQUIRED` state and needs an extra authorization step (for example, a one-time password on a mobile-money deposit). The body is discriminated by `type`; today the only supported variant is `OTP`.
tags:
- Transactions
parameters:
- name: transactionId
in: path
description: The unique identifier of the transaction
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
type:
type: string
description: The authorization method.
enum:
- OTP
otp:
type: string
description: The one-time password supplied by the customer.
required:
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/afriex/refs/heads/main/openapi/afriex-transactions-api-openapi.yml