Withdrawal to Ghanaian Bank

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

Use List banks API to get valid bank and branch codes
Retrieve rate - 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 and branch codes from list of banks

For a successful payout, you need to input the destination bank code of the transaction in the bank field and bank branch code in the branch field. This means you need to get details of the direct bank for that beneficiary (e.g, Access Bank, Amalgamated Bank, e.t.c).

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

Request Banks List

Request for a list of all available banks with bank codes for transfers in Ghana, as well as their branches

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

{
    "status": true,
    "statusCode": 200,
    "message": "Bank list retrieved",
    "data": [
        {
            "id": 174,
            "code": "GH280100", //Bank Code
            "name": "ACCESS BANK GH LTD", //Bank Name
            "branches": [ //Bank Branches
                {
                    "id": 1233,
                    "branch_code": "GH280101", //Bank Branch Code
                    "branch_name": "Access Bank Main Branch", //Bank Branch Name
                    "swift_code": "ABNGGHAC",
                    "bic": "ABNGGHACXXX",
                    "bank_id": 174
                }
            ]
         }
    ]
}

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 a GHS 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=GHS&from_currency=USDT

{
    "status": true,
    "statusCode": 200,
    "message": "rates setting successfully retrieved",
    "data": {
        "fiat": "GHS",
        "asset": "USDT",
        "to_currency": "GHS",
        "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": "GHS",
    "from_amount": 5000,
    "transaction_type": "withdrawal"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Rate successfully created",
    "data": {
        "from_currency": "USDT",
        "to_currency": "GHS",
        "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": "GHS",
        "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 (GHS in this case)
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. Ask Shutterscore to process withdrawal

To initiate a withdrawal to a Ghanaian 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,
        "country": "GH",
        "bank": "GH080100",
        "branch": "ADNTGHAC",
        "account_name": "James Okon",
        "account_number": "123456789",
        "account_type": "individual"
    },
    "amount": 2600,
    "currency": "GHS",
    "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": "GHS",
        "from_currency": "GHS",
        "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,\"country\":\"GH\",\"bank\":\"GH080100\",\"branch\":\"ADNTGHAC\",\"account_name\":\"James Okon\",\"account_number\":\"123456789\",\"account_type\":\"individual\"}",
        "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,
        "country": "GH",
        "bank": "GH080100",
        "branch": "ADNTGHAC",
        "account_name": "James Okon",
        "account_number": "123456789",
        "account_type": "individual"
    },
    "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": "GHS",
        "from_currency": "GHS",
        "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\":null,\"country\":\"GH\",\"bank\":\"GH080100\",\"branch\":\"ADNTGHAC\",\"account_name\":\"James Okon\",\"account_number\":\"123456789\",\"account_type\":\"individual\"}",
        "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 Ghanaian 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 - Ghanaian bank code
beneficiary.branch	String	Required - Ghanaian bank branch code
beneficiary.account_name	String	Required - Name of the beneficiary account
beneficiary.account_number	String	Required - Beneficiary account number
beneficiary.account_type	String	Required - Beneficiary type (can be either individual for individuals or corporate for companies and organisations)
beneficiary.country	String	Optional - Country of beneficiary - GH
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 - GHS	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.

4 - 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

5 - 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,
    }
}