Swaps

A swap is basically a conversion from one currency (from_currency) to another (to_currency).

Swapping between currencies on Shutterscore is very easy and quite seamless. They are 3 steps involved in performing currency swaps via API. Let's look at all of them closely.

How to execute swaps using Shutterscore API

The following steps need to be taken in order to perform a currency swap via the Shutterscore API:

1. Fund merchant account

To make withdrawals, you must have funds in your merchant account. You can fund your account by making deposits into your account or by requesting a manual top-up.

Note : To test transactions, you can fund your sandbox account. For more information, please see the test section

2. Retrieve rate

When performing a swap (That is, converting one currency to another currency e.g Converting USDT to withdraw to NGN ), 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": "swap"
}

{
    "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",
        "settlement_time": "30",
        "fee": 36050.5,
        "fee_type": "FLAT",
        "transaction_type": "SWAP",
        "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 - swap	Required - the type of transaction that the rate will be used for
deposit_method	String	Optional. Only required when transaction type is deposit and the deposit requires a deposit method. It is the deposit method of the deposit transaction e.g binance-pay
withdrawal_method	String	Optional. Only required when transaction type is withdrawal and the withdrawal requires a withdrawal method. It is the withdrawal method of the withdrawal transaction e.g mobile-money-payout

You can read more about the rate API from here

4. Request Swap

To initiate a currency swap, you need to send a request to the swap API with a reference to the rate that you've already created and which is within its expiry time (that is, rate has not expired). The request and response are given below.

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

{
    "reference": "9a7047cc-0223-435a-818d-7673c2aa5656"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Swap completed successfully",
    "data": {
        "from_amount": 6.88885521,
        "to_amount": 5695.65726564,
        "amount": 5695.65726564,
        "amount_charged": 5695.65726564,
        "amount_settled": 5638.70069298,
        "currency": "NGN",
        "from_currency": "USDT",
        "to_currency": "NGN",
        "from": "SELF",
        "to": "SELF",
        "type": "SWAP",
        "purpose": "SWAP",
        "trx_rate": 826.793,
        "reference": "swp70hixgodfomrm1kpye3zp",
        "channel": "API",
        "settled_at": null,
        "settlement_time": 5,
        "settlement_date": "2022-10-21T05:56:07.467Z",
        "narration": "swap by Chris Steve on Prime Switch Limited merchant account",
        "beneficiary": "merchant",
        "fee_bearer": "merchant",
        "fee": 56.95657266,
        "destination": "main_balance",
        "status": "pending",
        "from_merchant": "Prime Switch Limited",
        "to_merchant": "Prime Switch Limited",
        "merchant_reference": null,
        "extra_data": null,
        "reject_reason": null,
        "provider_fee": null,
        "provider_amount": null,
        "trace_id": null,
        "payment_slug": null,
        "payment_proof": null,
        "created_at": "2022-10-21T05:51:07.483Z",
        "updated_at": "2022-10-21T05:51:07.483Z"
    }
}

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

Field	Data Type	Description
reference	String	The reference to a created rate (a rate reference)

5. Receive and validate notification

You can set your application to receive transaction status updates via webhooks if provided, and email, when the swap is completed. Please read the webhooks page for details on securing and validating the webhook notification on your end, as well as the webhook structure and body.