Skip to content

BitForex Transfer API

Jump to bottom
githubdev2020 edited this page Dec 3, 2020 · 12 revisions

Preparation

1.Get access_token through Authorized Login 2.Request a company account from BitForex 3.Protocol includes: Payment steps and payment to users by the third party website

Payment Steps Guide（From BitForex users to Third Party Websites）

BitForex OAuth2.0 Payment Protocol allows users to transfer their BitForex asset to the third party websites after the login and the payment is authorized：

1.BitForex users sent a bitforex2pp request to the third party website，the third party project gets the transfer payment sign by making a call to the bitforex API through access_token.
2.Add client_id through sign parameter，redirect to BitForex users payment confirmation page.
3.User agree to the payment，BitForex redirect users to the third party payment page and sent the payment signal to the third party.
  • Protocol Guide:

notice

please using https://www.bitforex.com for pc，using https://m.bitforex.com for mobile,In the following docking process.

STEP 1, get payment transfer sign through access_token

[POST]https://www.bitforex.com/platform/transfer/verCode request BitForex users agreement confirmation

Parameter Guide（json Requestbody）

Params

access_token: access_token after the authorized login

Requestbody

{
    "amount":2,//transfer amount
    "clientID":"test-client", //clientID
    "coinCode":"btc",  //coin name
    "clientTransferId":"3" //third party payment id（unique）
}
Response Parameter（json）
{
    "data": {
             "code":"X7CeMq4FE8oI4LprsEYd701OOMT1IWEajWAAYTK1N0k="// Pay sign
             "deadline":1584964357385
            },
    "code": "200",
    "message": "success"
}

Example

curl -X POST \
  'https://www.bitforex.com/platform/transfer/verCode?access_token=b52fe597-7131-4652-b6c2-5a0205e60bbb' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{"amount":2,"clientID":"test-client","coinCode":"btc","clientTransferId":"3"}'

STEP 2，users confirms the payment transfer

After getting the sign from the STEP 1，the third party page redirect user to BitForex payment confirmation page，link：https://www.bitforex.com/plaweb/transfer_confirm，must include 4 parameters below:

1.sign ：from STEP 1

2.client_id： client_id from the third party

3.redirect_uri：response page

4.platform：Support pc and h5(use https://m.bitforex.com in the case), the default value is pc

Redirect to BitForex page：
https://www.bitforex.com/plaweb/transfer_confirm?sign=xxxxx&client_id=xxxxx&redirect_uri=xxxxxx

STEP 3，user confirmation

After BitForex user agree or reject to the payment，BitForex redirect users to a response page up to the third party decision. (STEP 2 parameter)

STEP 4，Sent an asynchronous notification to the third party for the payment result

Third party website/project transfer asset to BitForex account

The third party project/website can transfer certain amount of assets to particular users through this API, API name:

/appapi/transfer/app2bitforex

Parameter Guide

HTTP Headers

1. time: request Timestamp
2.  sign: sign，sign format：Base64(HMAC_SHA_256（key:client_secret, value: clientID+time+RequestBody))

Requestbody

  {
      "amount":2,//transfer amount
      "clientID":"test-client", //clientID
      "coinCode":"btc",  //coin name
      "clientTransferId":"3",//third party payment id（from STEP 1）
      "userId" : "1234"//user id
  }
Response Parameter（json）
  {
                    "data": {
                            "type":"app2bitforex", //transfer type（app2bitforex/bitforex2app）
                            "amount":2,//transfer amount
                            "clientID":"test-client", //clientID
                            "coinCode":"btc",  //coin name
  "clientTransferId":"3", //third party payment id（from STEP 1）
                            "bitforexTransferId": "2313512412" // unique id for this request from bitforex
                            "result":"1", //1 success，0 fail
                            "failureMsg": "btc not enough", //fail reason
                            "userId" : "1234" //user userId
                        },
                    "code": "200",
                    "message": "success"
 }

This API will return response at the same time to make sure the transfer amount is correct and send an asynchronous notification to the third party for the payment result

Asynchronous Notification to the third party

Project and users assets changes can be notified by this API with both bitforex->app and app -> bitforex. The third party must connect the asynchronous notification API, if the third party response API returns overtime response or no response, BitForex will consider these as response failure. Then BitForex will resent notifications to assure the success rate of the notifications. Notification frequency is 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h....

  1. 1.An API is required when the third party apply to the BitForex CApp to receive notifications, Ex：https://test.app/transfer/rec
  2. The third party needs to manage its own overlapped response.
  3. Notification Protocol：：
curl -X POST \
  'https://test.app/transfer/rec' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -H 'time: 1581258844000' \
  -H 'sign: bd66f9cd-c238-e6d4-6627-3c1db1628f3d' \
  -d '{"type":"app2bitforex","amount":2,"clientID":"test-client","coinCode":"btc","clientTransferId":"3","orderId":"2313512412", "userId" : "1234"}'
Parameter Guide

Http Headers

1.time: notification sent time
2.sign：needs the third party to verify; Sign add method：Base64(HMAC_SHA_256（key:client_secret, value: clientID+time+RequestBody))

Http RequestBody

{
    "type":"app2bitforex", //transfer type（app2bitforex/bitforex2app）
    "amount":2,//transfer amount
    "clientID":"test-client", //clientID
"coinCode":"btc",  //coin name
 "clientTransferId":"3", //third party payment id（from STEP 1）
    "orderId": "2313512412" //unique id for this request from bitforex
    "result":"1", //1success，0 fail
    "failureMsg": "btc not enough", //fail reason
    "userId" : "1234" //user userId
}
Response Guide

The response must be success for BitForex to consider as succeeded payment

Clone this wiki locally