Create a Transaction

Request Parameters

Parameter	Description	Data Type	Requirement	Field Length
requestDate	The date and time at which the transaction was created. Format as `YYYY-MM-DD HH:mm:ss`	String	Mandatory	19
amount	Amount payable to the beneficiary with precision of up to 6 decimal places. The number of decimals that can be paid out is country and currency specific. If the quote API was used, the Geoswift system would have rounded off the payout amount according to the round-off rules applicable to each country and currency.	String	Mandatory	10,6
currency	Payout currency in 3-letter ISO-4217 format.	String	Mandatory	3
type	The type of the transaction based on the sender and beneficiary. Values: `p2p`, `p2b`, `b2p`, `b2b` - `p2p`: Person to Person - `p2b`: Person to Business - `b2p`: Business to Person - `b2b`: Business to Business	String	Mandatory	11
descriptionText	Free format text description of the transaction provided by the client. Geoswift will pass this description to payout partners via API for use in statements or communication to beneficiaries.	String	Optional	1–256
requestingOrganisationTransactionReference	A unique transaction reference generated by the sending partner. Geoswift identifies a unique transaction from the send partner based on this reference. ⚠️ Critical: Resending with a different reference will be treated as a new transaction → risk of duplicate payout & fund loss.	String	Mandatory	4–50
provider	Mobile wallet provider code. - Mandatory for PSP wallets - Optional for MNO wallets - Must match the value sent in validation request; otherwise, transaction will be rejected.	Numeric	Optional	5–12

debitParty

Parameter	Description	Data Type	Requirement	Field Length
key: `msisdn`	Sender Mobile Number with country code. e.g. `+254123456789`	String	Mandatory	6 / 10–18
value	—	String	Mandatory	—
key: `organisationid`	Full name of the send partner entity	String	Optional	14 / 4–60
value	—	String	Optional	—
key: `bankaccountno`	Sender bank account or IBAN number or masked card number (PAN)	String	Optional	13 / 5–50
value	—	String	Optional	—
key: `pan`	Beneficiary card number (PAN), encrypted with RSA/ECB/OAEPWithSHA-256AndMGF1Padding. Geoswift provides public key. Mandatory for CARD payouts.	String	Optional	3–5 / 512–1024
value	—	String	Optional	—

creditParty

Parameter	Description	Data Type	Requirement	Field Length
key: `msisdn`	Beneficiary Mobile Number with country code. e.g. `+254123456789` Mandatory for WALLET payouts.	String	Conditional	6 / 10–18
value	—	String	Conditional	—
key: `bankaccountno`	Beneficiary bank account or IBAN number as required in destination country. Mandatory for BANK_AC payouts.	String	Conditional	13 / 5–50
value	—	String	Conditional	—
key: `accounttype`	Beneficiary bank account type: `Checking` or `Savings`. Default for p2p: `Savings`. Mandatory in certain countries.	String	Conditional	11 / 0–20
value	—	String	Conditional	—
key: `sortcode`	IFSC (India) or Swift BIC (others). Mandatory for BANK_AC payouts.	String	Conditional	8 / 4–25
value	—	String	Conditional	—
key: `organisationid`	Full name of the beneficiary bank. Mandatory for BANK_AC payouts.	String	Conditional	14 / 4–60
value	—	String	Conditional	—
key: `banksubcode`	Branch-specific code (e.g., routing number in Bangladesh). Mandatory for BANK_AC payouts.	String	Conditional	1–11 / 1–10
value	—	String	Conditional	—
key: `pan`	Encrypted beneficiary PAN (same encryption as above). Mandatory for CARD payouts.	String	Conditional	3–5 / 512–1024
value	—	String	Conditional	—

senderKyc

Parameter	Description	Data Type	Requirement	Field Length
nationality	Sender's nationality in ISO Alpha-2 format (e.g. `US`)	String	Mandatory	2
dateOfBirth	Sender's date of birth in `YYYY-MM-DD` format	String	Mandatory	10
countryOfBirth	Sender's country of birth in ISO Alpha-2 format	String	Optional	10
gender	Sender's gender: `M`, `F`, or `U`	String	Optional	1
primaryContactCountryCode	Primary contact country code	String	Optional	2
primaryContactNo	Primary contact number	String	Optional	10–15
primaryContactNoType	Contact number type (e.g. Personal/Office)	String	Optional	4–50

senderKyc:idDocument

Parameter	Description	Data Type	Requirement	Field Length
idType	ID document type (e.g. `nationalidcard`, `passport`)	String	Mandatory	1–20
idNumber	ID document number	String	Mandatory	1–30
issueDate	Issue date in `YYYY-MM-DD`	String	Conditional	10
expiryDate	Expiry date in `YYYY-MM-DD`	String	Mandatory	10
issuerCountry	Issuing country in ISO Alpha-2	String	Conditional	2

senderKyc:postalAddress

Parameter	Description	Data Type	Requirement	Field Length
addressLine1	First line of address	String	Mandatory	1–256
addressLine2	Second line of address	String	Optional	4–20
addressLine3	Third line of address	String	Optional	4–20
city	City/town	String	Mandatory	2–20
stateProvince	State (ISO Alpha-2 for US/CA→GT)	String	Conditional	2–20
postalCode	Postal/ZIP code	String	Conditional	6–8
country	Address country in ISO Alpha-2	String	Mandatory	2
cityOfBirth	Sender's city of birth	String	Optional	1–56

senderKyc:subjectName

Parameter	Description	Data Type	Requirement	Field Length
title	Title of the sender	String	Optional	0–6
firstName	First name	String	Mandatory	1–50
middleName	Middle name	String	Optional	0–20
lastName	Last name	String	Mandatory	1–50
fullName	Full name	String	Mandatory	1–128

recipientKyc

Parameter	Description	Data Type	Requirement	Field Length
nationality	Beneficiary's nationality (ISO Alpha-2)	String	Conditional	2
dateOfBirth	Beneficiary's DOB (`YYYY-MM-DD`)	String	Conditional	10
emailAddress	Email for notifications	String	Optional	0–60
countryOfBirth	Beneficiary's country of birth	String	Optional	2

recipientKyc:idDocument

Parameter	Description	Data Type	Requirement	Field Length
idType	ID type (country-specific)	String	Conditional	1–20
idNumber	ID number	String	Conditional	1–30
issueDate	Issue date (`YYYY-MM-DD`)	String	Optional	10
expiryDate	Expiry date (`YYYY-MM-DD`)	String	Conditional	10
issuerCountry	Issuing country (ISO Alpha-2)	String	Optional	2

recipientKyc:postalAddress

Parameter	Description	Data Type	Requirement	Field Length
addressLine1	First line of address	String	Conditional	1–256
addressLine2	Second line	String	Optional	4–20
addressLine3	Third line	String	Optional	4–20
city	City/town	String	Conditional	4–20
stateProvince	State (ISO Alpha-2 for US/CA)	String	Optional	2–20
postalCode	Postal code	String	Conditional	6–8
country	Address country (ISO Alpha-2)	String	Conditional	2
cityOfBirth	Beneficiary's city of birth	String	Optional	1–56

recipientKyc:subjectName

Parameter	Description	Data Type	Requirement	Field Length
firstName	First name	String	Mandatory	1–50
lastName	Last name	String	Mandatory	1–50
fullName	Full name	String	Mandatory	1–120
regionalBeneficiaryName	Regional name (e.g. Katakana for Japan)	String	Conditional	1–50

internationalTransferInformation

Parameter	Description	Data Type	Requirement	Field Length
quoteId	Quote reference from Create Quotation API	String	Mandatory	16–20
receivingCountry	Payout country code (ISO Alpha-2, e.g. `NG`)	String	Mandatory	2
remittancePurpose	Reason for transfer (see allowed values)	String	Mandatory	4–30
sourceOfFunds	Source of funds (see allowed values)	String	Mandatory	4–17
relationshipSender	Relationship between sender and beneficiary	String	Mandatory	3–11

Response Parameters (Success / Acknowledged)

Parameter	Description	Data Type
requestDate	Transaction timestamp as sent in request	String
amount	Payout amount as sent	String
currency	Payout currency as sent	String
type	Transaction type as sent	String
requestingOrganisationTransactionReference	Partner’s transaction reference	String
transactionStatus	Current status of the transaction	String
transactionReference	Unique Geoswift transaction ID	String

debitParty

Parameter	Description	Data Type
key: `msisdn`	—	String
value	Sender mobile number as sent	String

creditParty

Parameter	Description	Data Type
key: `msisdn`	—	String
value	Beneficiary mobile number as sent	String
key: `bankaccountno`	—	String
value	Beneficiary bank account as sent	String

Response Parameters (Error)

Parameter	Description	Data Type
serverCorrelationId	Partner’s transaction reference (`requestingOrganisationTransactionReference`)	String
clientCorrelationId	Geoswift-generated transaction reference	String
errorCategory	Error category (e.g. `VALIDATION_ERROR`)	String
errorCode	Specific error code	String
errorDescription	Human-readable error description	String
errorDateTime	UTC timestamp when error occurred	String

Modified at 2026-03-12 10:41:51