Skip to main content
POST
Create Transaction
Initiates a new transaction where the sender and recipient have already been onboarded. Both must have active customer profiles.

Request Headers

string
required
JWT Access Token of the authenticated user.
string
required
A unique key for this transaction submission. If the same key is sent twice, the second request returns the result of the first rather than creating a duplicate transaction. Use a UUID or a unique reference from your system.
string
required
IP address of the device initiating the transaction.
string
default:"fincode"
required
Platform identifier. Use fincode.
string
default:"200"
required
Unique request identifier.
string
Optional. The password is not checked on create-transaction, so this header can be left out.

Request Body

number
required
The amount the recipient will receive, in the receiving currency.
number
required
The amount the sender pays, in the sending currency.
boolean
required
Whether fees are included in sendAmount. Set to true if the sender pays a fixed amount inclusive of all fees; false if fees are added on top.
string
required
ISO 4217 currency code the sender is paying in (e.g. GBP).
string
required
ISO 4217 currency code the recipient will receive (e.g. NGN).
string
required
Transaction / delivery method. Common values:
string
required
Aggregation mode for the transaction. Accepted values: NONE_AGGREGATION and AGGREGATION. Use NONE_AGGREGATION for a standard transaction.
string
Accepted but not currently used. Whatever value is sent, cashier bookings are recorded as CASHIER_PAY_FROM_CUSTOMER_E_WALLET, and every booking starts as PENDING_PAYMENT. To pay for a booking from a wallet, call Make Payment from Wallet. A value that is not a valid payment method is rejected.
string
Customer code of an existing sender (returned from find-customer-by-name-or-phone-no or register-customer). Required unless you send newSenderKyc to create a new sender in the same request. Send exactly one of the two. See Agent Integration for the new sender option.
string
Customer code of an existing recipient/beneficiary (returned from new-beneficiary). Required unless you send newRecipientKyc to create a new recipient in the same request. Send exactly one of the two.
array
required
Key-value pairs for the recipient’s bank/account details. See the Add Bank Details key reference for the full list of valid keys. All keys must be lowercase.
object
required
Regulatory and routing information for the transfer.
string
Security question for cash pickup transactions. Required when type is CASHPICKUP.
string
Answer to the security question. Required when type is CASHPICKUP.
string
Your own reference for this transaction. Optional — the platform generates one if not provided.
object
Additional dynamic fields specific to your configuration. Pass an empty object {} if not applicable.
array
List of documents attached to this transaction (for transactions requiring document verification). Pass an empty array [] if none.

Code Example

cURL

Response

The response is returned as a plain object (not wrapped in data). On success, these fields carry values:
string
The payment reference number (PCN). Use it for payment and status calls such as checktransactionstatus/{pcn}.
string
The transaction ID.
string
The transaction ID, for use as payAbleId in payment calls.
string
SUCCESS when the transaction was created.
string
The transaction status, normally PENDING_PAYMENT for a new booking.
string
The sender’s customer code. Store it and reuse it for later bookings with the same sender.
string
The recipient’s customer code. Store it and reuse it for later bookings with the same recipient.
string
The sender’s user ID.
number
The amount the recipient will receive.
string
ISO 3166-1 alpha-3 code of the sending country.
string
ISO 3166-1 alpha-3 code of the receiving country.
string
TRANSACTION.
boolean
Whether the transaction has passed its compliance checks.
string
Compliance check result: PASS, WARNING, AWAITING_CUSTOMER_ACTION or FAIL.
array
Compliance requirements linked to this transaction.
string
Transaction created successfully.
Other fields in the response are not populated on success and come back empty (null, 0 or false). There are no fields named pcn or customerCode; the PCN is in objectReference.

When compliance documents are required

If the booking cannot go ahead until the customer provides documents, no PCN is returned. The response carries status FAILED, transactionStatus FAILED, errorCode -1, errorCodeType KYC_DOCUMENT_REQUIRED_502, a message explaining the requirement, and customerComplianceCheckList listing what is needed. Collect the listed documents, then submit the booking again.

Headers

platform
string
default:fincode
required
uuid
string
default:200
required
X-Auth-Token
string
required
password
string

Optional. Not checked on create-transaction.

ipAddress
string
required
X-Idempotency-Key
string
required

Body

application/json
amount
string
required
sendAmount
string
required
inclussive
boolean
required
receivingCurrency
string
default:NGN
required
sendCurrency
string
default:GBP
required
type
string
default:ACCOUNTPAYMENT
required
preExistingSenderCustomerCode
string
required
preExistingRecipientCustomerCode
string
required
creditParty
object[]
required
internationalTransferInformation
object
required
transactionProcessingMode
string
default:NONE_AGGREGATION
descriptionText
string
transactionModule
string
default:REMITTANCE

Response

200 - application/json

Transaction created. On success these fields carry values; other fields come back empty (null, 0 or false). If compliance documents are required, status is FAILED, errorCodeType is KYC_DOCUMENT_REQUIRED_502 and no PCN is returned.

objectReference
string

Payment reference number (PCN)

serverCorrelationId
string

Transaction ID

payAbleId
string

Transaction ID, for use as payAbleId in payment calls

status
string

SUCCESS when created, FAILED when compliance documents are required

transactionStatus
string

Transaction status, normally PENDING_PAYMENT for a new booking

preExistingSenderCustomerCode
string

Sender's customer code

preExistingRecipientCustomerCode
string

Recipient's customer code

userId
string

Sender's user ID

receivingAmount
number

Amount the recipient will receive

iso3CountryFrom
string

ISO 3166-1 alpha-3 code of the sending country

iso3CountryTo
string

ISO 3166-1 alpha-3 code of the receiving country

payableType
string

TRANSACTION

compliant
boolean

Whether the transaction has passed its compliance checks

complienceCheck
enum<string>
Available options:
PASS,
WARNING,
AWAITING_CUSTOMER_ACTION,
FAIL
customerComplianceCheckList
object[]

Compliance requirements linked to this transaction

message
string
errorCode
string

-1 when compliance documents are required

errorCodeType
string

KYC_DOCUMENT_REQUIRED_502 when compliance documents are required