Remittance Tutorial

In this example we’ll go through all of the steps and give examples on what you’ll need to do to implement a call to pay out funds to customers. Once you’ve read through this guide you’ll know everything that is required by us for you to use our payout system.

Let’s assume you operate in the US, and would like to use our site to send funds to Nigerian bank accounts.

You have a user registered and KYC’d on your site called John Doe. He is a recurring user on your site, and his user ID in your system is Sender:US:123456. He creates a transaction on your site asking you to send 100 USD to his partner in Nigeria Sheila Doe. He is going to fund the transaction in USD. Let’s assume the transaction created in your system has an ID of Transaction:NGN:123456.

Once you have the details collected on your end, you can then initiate the transaction in our system. This example will guide you through the details you need to set and what calls you need to make.

Authentication

All API calls on APEX are authenticated. API requests made without authorization will fail with the status code 401: Unauthorized.

• Log in to your APEX dashboard
• Navigate to Settings
• Select API keys from API & Webhook section to view and copy your keys

Country Restriction

if your account in APEX is created under US, you have to look up currencies under US. Every currency listed under a country have different restrictions such as local swap, international remittance currenies, delivery methods, delivery windows, account types, banks, mobile money networks and cash pickup. learn more click here

• Local swap - If this is available on a currency, it means you can swap it to other currencies under the listed country. For example if USD, CAD, EUR and GBP is listed under united states, & USD has local swap enabled, you can swap it to other currencies.
• International remittance - This is the list of recipient countries that you can send funds. For example multiple countries can be listed under USD as recipient countries tied to a particular currency, Nigeria - NGN can be a recipient currency under USD, meaning John can send USD to Sheila and she will receive it in NGN. You have to take note of international_remittance_id as this allows the system to understand what action you want to take.
• Delivery method - This includes bank, mobile_money and cash_pickup. Every delivery method have different payout fees, not all delivery methods are available for a currency. Account types are required when adding a recipient that has bank as a delivery method, it can be found under banks as a delivery_method.
• Delivery window - This is the speed of payout to recipient, each have different payout fees.
• Fee Structure - Its important to know how we calculate fees, it includes delivery window fees, payout method fee and swap fee if from and recipient currency ain't thesame. fee type ranges from no_fee, fiat, percent, fiat_percent.

Sender Details

Next step is setting up the sender details. Generally you’ll need to send us the following information for every sender and we will return a sender id:

• name
• email
• phone
• address information
• kyc data

{
    "first_name": "John",
    "middle_name": "Son",
    "last_name": "Doe",
    "email": "doe@remote.com",
    "phone": "+1234567789899",
    "phone_iso2": "US",
    "country": "US",
    "state": "DE",
    "city": "City",
    "address": "Address",
    "postal_code": "90000",
    "entity": "individual",
    "ip_address": "98.97.79.160",
    "id_type": "SSN",
    "id_number": "1234567890",
    "id_url": "https://google.com",
    "birth_date":"29-06-1999",
    "external_id": "0c355ea1-b6f3-4ad2-bae8-05bb0b494b0c"
}

Creating Recipient

Once you have the sender let’s set up the recipient as well. In this example we’re going to do an NGN::Bank payout, which requires:

• name
• email
• phone
• address information
• bank details
• transfer purpose
• currency of recipient, ensure you look up recipient country to get the currency_id.

{
    "currency_id" : "d374d1fa-6a88-47b7-a5cc-94acb76610fc",
    "transfer_purpose_id" : "0b051b28-dfde-4460-971c-2ad8084b04d6",
    "first_name": "Sheila",
    "middle_name": "Angel",
    "last_name": "Doe",
    "email": "sheila@remote.com",
    "phone": "09012345678",
    "phone_iso2": "NG",
    "delivery_method": "bank",
    "bank_id": "a76ee6f3-5164-40c8-8f3d-322817cc6def",
    "acct_no": "12413523562366",
    "acct_name": "John Derick",
    "acct_type_id": "505b513a-b5e5-4d5b-aa43-ae8dcda30191",
}

Tying it all together

Finally we need to tie the sender and recipient together into a transaction.

{
    "wallet_id" : "3b035348-c753-4f19-8aee-eb9d826e2941",
    "sender_id" : "120988ea-b91b-4543-9bc0-d851e17db04b",
    "recipient_id" : "faded4da-f559-4191-9527-f7843c4038cf",
    "international_remittance_id" : "876e83d7-736c-4ed0-8e27-d541d143a141",
    "delivery_window_id" : "0c355ea1-b6f3-4ad2-bae8-05bb0b494b0c",
    "external_id" : "0e0c895e-51a0-4449-a491-a2ab1aa5ed36",
    "amount" : "9100"
}

Waiting for the transaction to finish

Once the transaction is created and funded it goes into our processing queue. During this processing we will constantly try to pay out the funds. Dependent on the payment corridor and the recipient this can take anything from couple of minutes to a couple of days. In order to let you know when the transaction has finished paying out we will send out a notification to your registered webhook address, to let you know that the transaction has finished processing.