Binance Pay

Binance Pay is a simple, borderless, and secure way for users to send and receive cryptocurrencies from their mobile devices. Merchants on Shutterscore can collect payments from their crypto users via email, phone number, Binance ID (UID), or Pay ID.

To collect payments using Binance Pay, the following steps are advised,

Enroll as a Binance Pay sub-merchant
Retrieve rate - Optional
Initiate deposit
Redirect users
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.

🚧
Testing Binance Pay
Unfortunately, Binance Pay is only available in live mode. You can only test it with real funds in live mode.

1. Enroll as a Binance Pay sub-merchant

To have Binance Pay enabled for your merchant account, you need to complete the Binance Pay sub merchant enrolment. This enrolment is required for Binance Pay to capture your business details and allow your Business name and logo to be shown to your users.

To complete the enrolment, do the following.

Log into your Shutterscore merchant account (Click here to login now)
Visit, fill and submit the sub-merchant enrolment form found here, making sure to provide your business name, logo, website and transaction success/failure urls.

You will receive an enrolment success notification if your registration was successful.

2. Retrieve rate - Optional

When performing a cross collection or cross deposit (That is, receiving one currency for a deposit made in another currency), a rate is required.

You may sell a product priced in NGN but have a customer that has and wants to pay in BTC. Cross collect allows your customer to pay in BTC while you receive NGN into your Shutterscore Balance. Essentially, you are collecting NGN from a customer that paid with BTC.

Rate is needed to determine how of one currency can be exchanged for another and in the previous example, how much BTC your customer had to send for you to receive the cost of your goods in NGN.

Get Rate

Before a deposit 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).

📘
Deposit From and To
In a cross deposit, the to-currency or the destination currency is the currency you want to receive, same thing with the to-amount. While the from currency or source currency is the currency your customer has and wants to pay in.

In the sample request given below, the user wants to pay with USDT, while the merchant wants to receive GHS.

{{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 received by the merchant (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": "deposit",
    "deposit_method": "binance-pay"
}

{
    "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": "DEPOSIT",
        "deposit_method": "binance-pay",
        "withdrawal_method": null,
        "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 with which your customer wants to pay
to_currency	String - Currency Code. See Supported Currencies	Required - Destination currency or currency you want to receive(GHS in this case)
from_amount	Number	Required when to_amount is not provided - Amount of the source currency your customer is supposed to pay
to_amount	Number	Required when from_amount is not provided - Amount of the destination currency you'd like to receive
transaction_type	String - deposit	Required - the type of transaction that the rate will be used for
deposit_method	String - binance-pay	Required - the deposit method that is being used

You can read more about the rate API from here

3. Initiate deposit

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

Direct Deposit

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

{
  	"amount: 10,
  	"currency": "USDT",
    "deposit_method": "binance-pay",
    "requirement": {
        "product_name": "Product Name",
        "product_description": "Product Service",
        "failure_url": "",
        "success_url": ""
    },
    "reference": "AZ-Nwanne-master-12",
    "fee_bearer": "beneficiary"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Payment links generated successfully",
    "data": {
        "prepayId": "190801160074133504",
        "terminalType": "OTHERS",
        "expireTime": 1666685599000,
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20221025/c8855709-5302-49a0-9a23-213eec68f77a.jpg",
        "qrContent": "https://app.binance.com/qr/dplk14b3f81f440245e99d8c50de79ac5eec",
        "checkoutUrl": "https://pay.binance.com/en/checkout/55e4e8e6333046c785b12693e244f340",
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=jHhODx6xqOni5QHE77PhRIkyNy0YFhcJ&returnLink=https://merchant.staging.shutterscore.io/balances?currency=USDT&amount=1.32187707&reference=dpt7my3fj44eqpkhcehcf54u&status=success&nonce=b3fa379746343cf9b4fb41daa78e2ce9&cancelLink=https://merchant.staging.shutterscore.io/balances?currency=USDT&amount=1.32187707&reference=dpt7my3fj44eqpkhcehcf54u&status=error&nonce=b3fa379746343cf9b4fb41daa78e2ce9",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=55e4e8e6333046c785b12693e244f340&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj1qSGhPRHg2eHFPbmk1UUhFNzdQaFJJa3lOeTBZRmhjSiZyZXR1cm5MaW5rPWh0dHBzOi8vbWVyY2hhbnQuc3RhZ2luZy5zaHV0dGVyc2NvcmUuaW8vYmFsYW5jZXM_Y3VycmVuY3k9VVNEVCZhbW91bnQ9MS4zMjE4NzcwNyZyZWZlcmVuY2U9ZHB0N215M2ZqNDRlcXBraGNlaGNmNTR1JnN0YXR1cz1zdWNjZXNzJm5vbmNlPWIzZmEzNzk3NDYzNDNjZjliNGZiNDFkYWE3OGUyY2U5JmNhbmNlbExpbms9aHR0cHM6Ly9tZXJjaGFudC5zdGFnaW5nLnNodXR0ZXJzY29yZS5pby9iYWxhbmNlcz9jdXJyZW5jeT1VU0RUJmFtb3VudD0xLjMyMTg3NzA3JnJlZmVyZW5jZT1kcHQ3bXkzZmo0NGVxcGtoY2VoY2Y1NHUmc3RhdHVzPWVycm9yJm5vbmNlPWIzZmEzNzk3NDYzNDNjZjliNGZiNDFkYWE3OGUyY2U5",
        "product_name": "Product Name",
        "product_description": "Product Service",
        "failure_url": "",
        "success_url": "",
        "merchant_reference": "AZ-Nwanne-master-12",
        "from_merchant": null,
        "to_merchant": null
    }
}

Cross Collect/Deposit

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

{
    "deposit_method": "binance-pay",
    "requirement": {
        "product_name": "Product Name",
        "product_description": "Product Service",
        "failure_url": "",
        "success_url": ""
    },
    "reference": "AZ-Nwanne-master-12",
    "rate_reference": "31917500-a3aa-419a-83db-8226efb3fd52",
    "fee_bearer": "beneficiary"
}

{
    "status": true,
    "statusCode": 200,
    "message": "Deposit completed successfully",
    "data": {
        "prepayId": "190801160074133504",
        "terminalType": "OTHERS",
        "expireTime": 1666685599000,
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20221025/c8855709-5302-49a0-9a23-213eec68f77a.jpg",
        "qrContent": "https://app.binance.com/qr/dplk14b3f81f440245e99d8c50de79ac5eec",
        "checkoutUrl": "https://pay.binance.com/en/checkout/55e4e8e6333046c785b12693e244f340",
        "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=jHhODx6xqOni5QHE77PhRIkyNy0YFhcJ&returnLink=https://merchant.staging.shutterscore.io/balances?currency=USDT&amount=1.32187707&reference=dpt7my3fj44eqpkhcehcf54u&status=success&nonce=b3fa379746343cf9b4fb41daa78e2ce9&cancelLink=https://merchant.staging.shutterscore.io/balances?currency=USDT&amount=1.32187707&reference=dpt7my3fj44eqpkhcehcf54u&status=error&nonce=b3fa379746343cf9b4fb41daa78e2ce9",
        "universalUrl": "https://app.binance.com/payment/secpay?linkToken=55e4e8e6333046c785b12693e244f340&_dp=Ym5jOi8vYXBwLmJpbmFuY2UuY29tL3BheW1lbnQvc2VjcGF5P3RlbXBUb2tlbj1qSGhPRHg2eHFPbmk1UUhFNzdQaFJJa3lOeTBZRmhjSiZyZXR1cm5MaW5rPWh0dHBzOi8vbWVyY2hhbnQuc3RhZ2luZy5zaHV0dGVyc2NvcmUuaW8vYmFsYW5jZXM_Y3VycmVuY3k9VVNEVCZhbW91bnQ9MS4zMjE4NzcwNyZyZWZlcmVuY2U9ZHB0N215M2ZqNDRlcXBraGNlaGNmNTR1JnN0YXR1cz1zdWNjZXNzJm5vbmNlPWIzZmEzNzk3NDYzNDNjZjliNGZiNDFkYWE3OGUyY2U5JmNhbmNlbExpbms9aHR0cHM6Ly9tZXJjaGFudC5zdGFnaW5nLnNodXR0ZXJzY29yZS5pby9iYWxhbmNlcz9jdXJyZW5jeT1VU0RUJmFtb3VudD0xLjMyMTg3NzA3JnJlZmVyZW5jZT1kcHQ3bXkzZmo0NGVxcGtoY2VoY2Y1NHUmc3RhdHVzPWVycm9yJm5vbmNlPWIzZmEzNzk3NDYzNDNjZjliNGZiNDFkYWE3OGUyY2U5",
        "product_name": "Product Name",
        "product_description": "Product Service",
        "failure_url": "",
        "success_url": "",
        "merchant_reference": "AZ-Nwanne-master-12",
        "from_merchant": null,
        "to_merchant": null
    }
}

Request Body
The parameters below are used with the deposit API to initiate a Binance Pay deposit.

Field	Data Type	Description
requirement	Object	Required
requirement.product_name	String	Required - Email address of the beneficiary
requirement.product_description	String	Optional - Phone number of the beneficiary
requirement.failure_url	String	Optional - URL to redirect to on payment failure
requirement.success_url	String	Optional - URL to redirect to on payment success
deposit_method	String - binance-pay	Required - the deposit method used
amount	Number	Required for direct deposit - the amount to be deposited (paid to the merchant). For cross deposit, the to_amount on the rate is used
currency	String - GHS	Required for direct deposit. For cross deposit, the to_currency on the rate is used
reference	String	Optional - Merchant's reference of the transaction.
rate_reference	String	Required for cross deposit - Rate reference provides a reference to the rate that will be used for the cross deposit.
fee_bearer	String - merchant or beneficiary	Optional - Fee Bearer. When not provided, the value used is merchant.

4 - Redirect users

If the initiate deposit request is successful, you'll receive a response that contains Binance Pay links.
You'll need to redirect your user to the url in the universalUrl property in the response so that the user can complete the payment. The image below shows the Binance payment page that is loaded from the url.

5 - Receive confirmation via webhook

You can set your application to receive a confirmation via webhooks if provided, and email, when the deposit is completed.

For direct deposit, the event your application should listen for is the deposit.success event, while for cross deposit/collect, your app should listen for a swap.success event.

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

Binance Pay

🚧
Testing Binance Pay

1. Enroll as a Binance Pay sub-merchant

2. Retrieve rate - Optional

Get Rate

📘
Deposit From and To

Create Rate

3. Initiate deposit

Direct Deposit

Cross Collect/Deposit

4 - Redirect users

5 - Receive confirmation via webhook

6 - Get single transaction status - Optional

🚧Testing Binance Pay

1. Enroll as a Binance Pay sub-merchant

2. Retrieve rate - Optional

Get Rate

📘Deposit From and To

Create Rate

3. Initiate deposit

Direct Deposit

Cross Collect/Deposit

4 - Redirect users

5 - Receive confirmation via webhook

6 - Get single transaction status - Optional

🚧
Testing Binance Pay

📘
Deposit From and To