Beneficiary Lifecycle

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

Step 3: Get Dynamic Forms (Optional)

Some corridors require additional sender information when creating a beneficiary. Check for any dynamic fields group 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

Response: If validation is supported and successful, the response will contain the 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

Note: Do not call “Add Bank Details” for Cash Pickup beneficiaries.

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

Example Validation Request:

{
    "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"}
]

Getting Started

Transaction Core

API Endpoints

Bank Transfer Flow

Step 1: List Supported Banks

List Banks

Step 2: Get Required Fields

Required Bank Fields

Step 3: Get Dynamic Forms (Optional)

Dynamic Fields

Step 4: Validate Bank Account

Validate Bank Account

Step 5: Create Beneficiary

Create Beneficiary

Step 6: Add Bank Details

Add Bank Details

Cash Pickup Flow

Step 1: Validate Phone (Optional)

Validate Mobile Number

Step 2: Create Beneficiary

Create Beneficiary

Mobile Money Flow

Step 1: List Mobile Operators

List Mobile Operators

Step 2: Validate Mobile Number

Validate Mobile Number

Step 3: Create Beneficiary

Create Beneficiary

Step 4: Create Transaction

Getting Started

Transaction Core

API Endpoints

Documentation Index

​Bank Transfer Flow

​Step 1: List Supported Banks

List Banks

​Step 2: Get Required Fields

Required Bank Fields

​Step 3: Get Dynamic Forms (Optional)

Dynamic Fields

​Step 4: Validate Bank Account

Validate Bank Account

​Step 5: Create Beneficiary

Create Beneficiary

​Step 6: Add Bank Details

Add Bank Details

​Cash Pickup Flow

​Step 1: Validate Phone (Optional)

Validate Mobile Number

​Step 2: Create Beneficiary

Create Beneficiary

​Mobile Money Flow

​Step 1: List Mobile Operators

List Mobile Operators

​Step 2: Validate Mobile Number

Validate Mobile Number

​Step 3: Create Beneficiary

Create Beneficiary

​Step 4: Create Transaction

Bank Transfer Flow

Step 1: List Supported Banks

Step 2: Get Required Fields

Step 3: Get Dynamic Forms (Optional)

Step 4: Validate Bank Account

Step 5: Create Beneficiary

Step 6: Add Bank Details

Cash Pickup Flow

Step 1: Validate Phone (Optional)

Step 2: Create Beneficiary

Mobile Money Flow

Step 1: List Mobile Operators

Step 2: Validate Mobile Number

Step 3: Create Beneficiary

Step 4: Create Transaction