Withdrawal to Nigerian Bank

To make a withdrawal to a Nigerian bank account, the following steps are advised,

Use List banks API to get valid bank codes
Retrieve rate - Optional
Verify the destination bank account - Optional
Ask Shutterscore to handle Disbursement
Receive confirmation via webhook when the payout is completed
Query the transaction to get the status of the transaction - Optional

Let's look at each step in detail.

1. Find bank codes from List of Banks

For a successful payout, you need to input the destination bank code of the transaction in the bank field. This means you need to get details of the direct bank for that beneficiary (eg., Access Bank, or Wema Bank).

In this example, you'll find the different bank types that support transfers in Nigerian naira.

Request Banks List

Request for a list of all available banks with bank codes for transfers in Nigeria

{{baseurl}}/v1/merchant/public/misc/banks?country=NG

{
    "status": true,
    "statusCode": 200,
    "message": "Bank list retrieved",
    "data": [
        {
        "name": " Bank name", // e.g Access Bank Nigeria
        "slug": " Bank slug", // e.g access
        "code": " Bank code", // e.g 044
        "country": "NG"       // e.g NG
        },
    ]
}

2. Retrieve rate - Optional

When performing a cross withdrawal (That is, making a withdrawal to one currency from another currency e.g Using a USDT balance to withdraw to an NGN bank account), a rate ] is required.

Get Rate

Before a withdrawal amount (to_amount) is provided, there may be need to show the rate of conversion to the user or help the user calculate in real time, what they may receive from the cross withdrawal. The get rate endpoint can be used to determine the value of the destination currency (to_currency) compared to the source currency (from_currency)

{{baseurl}}/v1/merchant/public/markets/rates?to_currency=NGN&from_currency=USDT

{
    "status": true,
    "statusCode": 200,
    "message": "rates setting successfully retrieved",
    "data": {
        "fiat": "NGN",
        "asset": "USDT",
        "to_currency": "NGN",
        "from_currency": "USDT",
        "fee": 1,
        "fee_type": "PERCENTAGE",
        "refresh_in": 20,
        "rate": 730.55,
        "market": "SELL"
    }
}

Create Rate

Once the amount to be withdrawn (to_amount) is known, the create rate endpoint can be used to determine how much (from_amount) of the source currency (from_currency) will be required.

{{baseurl}}/v1/merchant/public/rates/create

{
    "from_currency": "USDT",
    "to_currency": "NGN",
    "from_amount": 5000,
    "transaction_type": "withdrawal"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Rate successfully created",
    "data": {
        "from_currency": "USDT",
        "to_currency": "NGN",
        "from_amount": 5000,
        "to_amount": 3605050,
        "reference": "569f0de6-2d28-4abf-8210-c6531385d4e5",
        "expires_at": "2022-10-03T06:53:42.158Z",
        "fee": 36050.5,
        "fee_type": "FLAT",
        "transaction_type": "WITHDRAWAL",
        "created_at": "2022-10-03T06:52:12.197Z",
        "updated_at": "2022-10-03T06:52:12.197Z",
        "fiat": "NGN",
        "asset": "USDT",
        "refresh_in": 90,
        "used": false
    }
}

Request Body

The following parameters are to be provided to the create rate API

Field	Data Type	Description
from_currency	String - Currency Code. See Supported Currencies	Required - Source currency or currency who's balance you have and you want to exchange for the other
to_currency	String - Currency Code. See Supported Currencies	Required - Destination currency or currency you want to receive (or payout in the case of a withdrawal)
from_amount	Number	Required when to_amount is not provided - Amount of the source currency to want to exchange
to_amount	Number	Required when from_amount is not provided - Amount of the destination currency you'd like to receive
transaction_type	String - withdrawal	Required - the type of transaction that the rate will be used for

You can read more about the rate API from here

3. Verify bank account number - Optional

Use the bank resolution API to verify the destination bank account number before you request the payout. See the verification request and response below.

Bank Account Resolve request

This resolves the bank account:

{{baseurl}}/v1/merchant/public/misc/banks/resolve

{
   "bank": "033",
   "account": "2158634852"
}

{
  "status": true,
  "statusCode": 200,
  "message": "Bank details resolve successfully",
  "data": {
    "bank_name": "United Bank for Africa",
    "bank_code": "033",
    "account_number": "2158634852",
    "account_name": "EBUKA CIROMA OLADEMJI"
  }
}

Request body

The bank account resolution API accepts the following parameters.

Field	Data Type	Description
bank	String	Required - bank code of account number
account	String	Required - account number to be resolved

4. Ask Shutterscore to process withdrawal

To initiate a withdrawal to a Nigerian bank account, you need to send a request to the withdrawal API with the required parameters. The request data will depend on the type of withdrawal.

Direct Withdrawal

{{baseurl}}/v1/merchant/public/transactions/withdraw

{
    "beneficiary": {
        "email": "[email protected]",
        "phone": null,
        "bank": "058",
        "account_name": "James Okon",
        "account_number": "0116533244"
    },
    "amount": 2600,
    "currency": "NGN",
    "narration": "Pay to my account",
    "reference": "MERCHANT-REFERENCE",
    "fee_bearer": "merchant"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Withdrawal completed successfully",
    "data": {
        "from_amount": 1600,
        "amount": 1600,
        "amount_charged": 1605,
        "amount_settled": 1600,
        "currency": "NGN",
        "from_currency": "NGN",
        "from": "SELF",
        "to": "OTHER",
        "type": "WITHDRAWAL",
        "purpose": "WITHDRAWAL",
        "reference": "WTH-478d3867-88ff-4bf8-a007-1d358b9bae11",
        "merchant_reference": "MERCHANT-REFERENCE",
        "channel": "API",
        "settled_at": "2022-10-03T12:04:05.000Z",
        "narration": "Pay to my account",
        "beneficiary": "{\"email\":\"[email protected]\",\"phone\":null,\"bank\":\"058\",\"account_name\":\"James Okon\",\"account_number\":\"0116533244\"}",
        "fee_bearer": "merchant",
        "fee": 5,
        "destination": "main_balance",
        "payment_slug": "instant-bank-payout",
        "status": "pending",
        "from_merchant": "Prime Switch Limited",
        "to_amount": null,
        "to_currency": null,
        "trx_rate": null,
        "rateId": null,
        "settlement_time": null,
        "settlement_date": null,
        "reject_reason": null,
        "trace_id": null,
        "payment_proof": null,
        "created_at": "2022-10-03T12:04:05.009Z",
        "updated_at": "2022-10-03T12:04:05.009Z",
        "to_merchant": null
    }
}

Cross Withdrawal

{{baseurl}}/v1/merchant/public/transactions/withdraw

{
    "beneficiary": {
        "email": "[email protected]",
        "phone": null,
        "bank": "058",
        "account_name": "James Okon",
        "account_number": "0116533244"
    },
    "narration": "Pay to my account",
    "reference": "MERCHANT-REFERENCE",
    "fee_bearer": "merchant",
    "rate_reference": "17c2922a-3a06-4464-abd9-041619bdf553"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Withdrawal completed successfully",
    "data": {
        "from_amount": 4999.86190385,
        "amount": 4999.86190385,
        "amount_charged": 5004.86190385,
        "amount_settled": 4999.86190385,
        "currency": "NGN",
        "from_currency": "NGN",
        "from": "SELF",
        "to": "OTHER",
        "type": "WITHDRAWAL",
        "purpose": "WITHDRAWAL",
        "trx_rate": 724.11,
        "reference": "WTH-876c4209-5c84-4fc5-a8d8-7b56080a690b",
        "channel": "API",
        "settled_at": "2022-10-06T10:20:38.425Z",
        "narration": "Pay to my account",
        "beneficiary": "{\"email\":\"[email protected]\",\"phone\":\"08065432435\",\"bank\":\"058\",\"account_name\":\"James Okon\",\"account_number\":\"0116533244\"}",
        "fee_bearer": "merchant",
        "fee": 5,
        "destination": "main_balance",
        "payment_slug": "instant-bank-payout",
        "status": "pending",
        "from_merchant": "Prime Switch Limited",
        "to_amount": null,
        "to_currency": null,
        "rateId": null,
        "merchant_reference": "MERCHANT-REFERENCE",
        "settlement_time": null,
        "settlement_date": null,
        "reject_reason": null,
        "trace_id": null,
        "payment_proof": null,
        "created_at": "2022-10-06T10:20:38.435Z",
        "updated_at": "2022-10-06T10:20:38.435Z",
        "to_merchant": null
    }
}

Request Body
The parameters below are used with the withdrawal API to request a withdrawal to a Nigeria bank account

Field	Data Type	Description
beneficiary	Object	Required
beneficiary.email	String	Required - Email address of the beneficiary
beneficiary.phone	String	Optional - Phone number of the beneficiary
beneficiary.bank	String	Required - Nigerian bank code
beneficiary.account_name	String	Required - Name of the beneficiary account
beneficiary.account_number	String	Required - Beneficiary account number
amount	Number	Required for direct withdrawal - the amount to be withdrawn (paid to the beneficiary). For cross withdrawal, the to_amount on the rate is used
currency	String - NGN	Required for direct withdrawal. For cross withdrawal, the to_currency on the rate is used
narration	String	Optional - description of the transaction
reference	String	Optional - Merchant's reference of the transaction.
rate_reference	String	Required for cross withdrawal - Rate reference. Provides a reference to the rate that will be used for the cross withdrawal.
fee_bearer	String - merchant or beneficiary	Optional - Fee Bearer. When not provided, the value used is merchant.

5 - Receive confirmation via webhook

You can set your application to receive a confirmation via webhooks if provided, and email, when the payout is completed. Ensure that you verify that the webhook confirmation notification is from us. Kindly read more about webhooks on Shutterscore here

6 - Get single transaction status - Optional

Periodically or after receiving a webhook notification from Shutterscore, you can request for the transaction details, including its status. You can retrieve a single transaction using it's reference or merchant reference as shown below.

{{baseurl}}/v1/merchant/public/transactions/:reference or :merchant_reference

{
    "status": true,
    "statusCode": 200,
    "message": "Transaction successfully retreived",
    "data": {
        "from_amount": 4999.86190385,
        "to_amount": null,
        "amount": 4999.86190385,
        "amount_charged": 5004.86190385,
        "amount_settled": 4999.86190385,
        "currency": "NGN",
        "from_currency": "NGN",
        "to_currency": null,
        "from": "SELF",
        "to": "OTHER",
        "type": "WITHDRAWAL",
        "purpose": "WITHDRAWAL",
        "trx_rate": 724.11,
        "reference": "WTH-876c4209-5c84-4fc5-a8d8-7b56080a690b",
        "merchant_reference": "MERCHANT-REFERENCE",
        "channel": "API",
        "settled_at": "2022-10-06T10:20:38.000Z",
        "settlement_time": null,
        "settlement_date": "2022-10-06T10:51:20.000Z",
        "narration": "Pay to my account",
        "beneficiary": "{\"email\":\"[email protected]\",\"phone\":\"08065432435\",\"bank\":\"058\",\"account_name\":\"James Okon\",\"account_number\":\"0116533244\"}",
        "reject_reason": null,
        "fee_bearer": "merchant",
        "fee": 5,
        "trace_id": null,
        "destination": "main_balance",
        "payment_slug": "instant-bank-payout",
        "payment_proof": null,
        "status": "success",
        "created_at": "2022-10-06T10:20:38.435Z",
        "updated_at": "2022-10-06T10:51:19.000Z",
        "from_merchant": "Prime Switch Limited",
        "to_merchant": null,
    }
}