curl --request POST \
--url https://sandbox.api.afriex.com/api/v1/transaction/pool-account \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 5000,
"customerId": "6929843e2c4653277440acc0",
"countryCode": "NG",
"reference": "6929843e2c4653277440acc0",
"fileKey": "64f0c2a1e4b0a1b2c3d4e5f6/proof.pdf",
"timestamp": "2026-01-01T12:00:00.000Z"
}
'{
"data": {
"transactionId": "<string>",
"customerId": "<string>",
"sourceId": "<string>",
"destinationId": "<string>",
"sourceAmount": "<string>",
"sourceCurrency": "<string>",
"destinationAmount": "<string>",
"destinationCurrency": "<string>",
"type": "DEPOSIT",
"channel": "BANK_ACCOUNT",
"status": "PENDING",
"merchantReference": "<string>",
"rate": "<string>",
"fee": "<string>",
"meta": {
"narration": "<string>",
"otpRequired": true,
"failureReason": {
"code": "AFX_VELOCITY_LIMIT_EXCEEDED",
"message": "<string>",
"retryable": true
}
},
"createdAt": "<string>",
"updatedAt": "<string>"
}
}Submit Pool-Account Payment Proof
Submits proof of a deposit made to the business pool account. The request creates a business deposit transaction in IN_REVIEW status; an operator confirms the bank inflow before the funds are credited. The response returns that transaction. Duplicate submissions of the same business, customer, amount, reference, timestamp and sender details within the configured idempotency window are rejected. The timestamp cannot be in the future. Your business must have a webhook URL set, otherwise the request is rejected with a 400.
curl --request POST \
--url https://sandbox.api.afriex.com/api/v1/transaction/pool-account \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": 5000,
"customerId": "6929843e2c4653277440acc0",
"countryCode": "NG",
"reference": "6929843e2c4653277440acc0",
"fileKey": "64f0c2a1e4b0a1b2c3d4e5f6/proof.pdf",
"timestamp": "2026-01-01T12:00:00.000Z"
}
'{
"data": {
"transactionId": "<string>",
"customerId": "<string>",
"sourceId": "<string>",
"destinationId": "<string>",
"sourceAmount": "<string>",
"sourceCurrency": "<string>",
"destinationAmount": "<string>",
"destinationCurrency": "<string>",
"type": "DEPOSIT",
"channel": "BANK_ACCOUNT",
"status": "PENDING",
"merchantReference": "<string>",
"rate": "<string>",
"fee": "<string>",
"meta": {
"narration": "<string>",
"otpRequired": true,
"failureReason": {
"code": "AFX_VELOCITY_LIMIT_EXCEEDED",
"message": "<string>",
"retryable": true
}
},
"createdAt": "<string>",
"updatedAt": "<string>"
}
}Flow
Upload the proof
type: "transaction" and PUT the proof file (bank receipt, screenshot, etc.) to the returned presigned URL.type matters. A URL requested with type: "user" uploads to a different bucket; passing that key here is rejected as not found.Submit the proof
amount, the countryCode of the pool account, the pool-account reference (see below), the S3 fileKey returned in step 1, and the payment timestamp. Optionally attach senderDetails (name, account number, bank, country) to help reconciliation.Wait for confirmation
IN_REVIEW. Subscribe to Transaction Events to be notified when the operator confirms and the status transitions.Choosing the reference
- Credit an end customer: pass the customer’s
reference(the shortened value returned on customer reads; falls back to the customer id when none is assigned).customerIdmust match that customer. - Credit the business itself: pass the business’s own pool-account reference from Get Pool Account. Routing does not use
customerIdin this case.
Idempotency
Duplicate submissions with the same business,customerId, amount, reference, timestamp, and senderDetails within the configured window are rejected with 409 DUPLICATE_REQUEST. Include a distinct timestamp per real payment.Authorizations
Static business API key issued from the dashboard. A business can provision multiple API keys, each scoped to a configurable set of permissions (e.g. read transactions, create deposits, etc). Permissions are chosen per key at creation time in the dashboard and may be revoked by deleting the key. Manage your keys and their permissions under Developer → API keys in the dashboard.
A request whose key does not carry the permission the target
endpoint requires is rejected with 401 Unauthorized, the same
response an unrecognised, malformed, revoked or disabled key
returns. The API does not distinguish the two cases on the wire.
See the Permissions reference for the permission each endpoint requires.
Headers
Signature of the request payload, used for request authentication where payload signing is enabled for your business.
API version in ISO 8601 format. The only supported version is 2026-05-18, which is also the default when the header is omitted. Any other value is rejected with a 400 Bad Request.
Body
The deposit amount in the major currency unit.
The Afriex customer ID the deposit should be credited to. Applies when reference is a customer reference, in which case it must match that customer. When reference is the business's own pool-account reference the deposit is credited to the business and this field is not used for routing.
ISO 3166-1 alpha-2 country code of the pool account.
The pool-account reference returned by GET /api/v1/payment-method/pool-account. Used to reconcile the deposit.
The S3 object key of the uploaded proof-of-payment file. Obtain this from POST /api/v1/media/url with type: transaction first; a URL requested without that type uploads to a different bucket and the key will be rejected as not found.
ISO 8601 timestamp of when the payment was sent. It cannot be in the future (a few minutes of clock difference is tolerated). Used for idempotency together with the other request fields.
Show child attributes
Show child attributes
Response
Proof submitted successfully.
Show child attributes
Show child attributes