Creating a beneficiary involves a multi-step process to ensure data accuracy and compliance. The flow varies depending on the payout method (Bank Transfer, Cash Pickup, or Mobile Money) but the core process is the same.
Payment Type Configuration: The available payout methods and their specific configuration are managed at the admin level by the principal firm. This is out of scope for the client integration but determines which options are available for your customers.
Bank Transfer
Cash Pickup
Mobile Money
Bank Transfer Flow
For Bank Transfers, the process involves validating the bank account details before creating the beneficiary profile and linking the account.Step 1: List Supported Banks
First, retrieve the list of supported banks for the destination country.List Banks
View list of supported beneficiary banks
Step 2: Get Required Fields
Different countries and banks require different fields (e.g., IBAN vs. Account Number + Sort Code). Fetch the dynamic requirements for the selected country.Required Bank Fields
View required bank fields
REGISTERED_CUSTOMER_CREATE_BENE.Dynamic Fields
View dynamic fields
Step 4: Validate Bank Account
Before creation, validate the bank account details. This ensures the account exists and matches the beneficiary name (where supported).Validate Bank Account
View validate bank account endpoint
accountName which should be used to pre-fill the beneficiary name.Step 5: Create Beneficiary
Create the beneficiary profile using the validated details.Create Beneficiary
Create beneficiary endpoint
Step 6: Add Bank Details
Finally, link the validated bank account to the newly created beneficiary. This can be done immediately after creation or at a later time.Add Bank Details
Add bank details endpoint
Cash Pickup Flow
For Cash Pickup, no bank account is required. The beneficiary is identified by their name and phone number only.Step 1: Validate Phone (Optional)
If supported for the corridor and the payout partner, validate the phone number using the validation endpoint (similar to bank account validation but for phone).Validate Mobile Number
View validate mobile number endpoint
Step 2: Create Beneficiary
Create the beneficiary profile. Ensure the phone field is populated as it is compulsory for Cash Pickup.Create Beneficiary
Create beneficiary endpoint
Mobile Money Flow
Mobile Money transfers require validating the mobile number with the specific operator(if supported/activated) before creation.Step 1: List Mobile Operators
Retrieve the list of supported mobile money operators for the destination country.List Mobile Operators
View supported mobile operators
Step 2: Validate Mobile Number
Validate the mobile number and operator code. This checks if the number is active and registered.Validate Mobile Number
Use transactionType: MOBILE_MONEY and mobileOperatorCode
{
"mobileOperatorCode": "ORANGE",
"transactionType": "MOBILE_MONEY",
"topUpMobileNumber": "090382738",
"accountNumberCountry": "GIN",
"expectedCurrencyCode": "GNF"
}
Step 3: Create Beneficiary
If validation is successful (or if validation is not supported but the format is correct), create the beneficiary profile.Create Beneficiary
Create beneficiary endpoint
Step 4: Create Transaction
When creating the transaction, include the mobile money details in the creditParty array."creditParty": [
{"key": "mobilemoneynumber", "value": "0903827384"},
{"key": "mobileoperatorcode", "value": "ORANGE"}
]
