# BullStreet Pay Authorization

## Introduction

As for the first time of a user using **BullStreet Pay**, there is no `userKey` under the user, you will need to provide us `merchantUserId` and `merchantUsername` (Optional) when calling [Get Payment Widget](https://api.btse.co/payment/pay-api#tag/Widget-Service/operation/post-payapi-widget-url) and then we will guide the user to log into BullStreet platform for further authorization process. Once the user approves the authorization of BullStreet Pay service, we will send you userKey which is bound with the user and these 2 attributes in order that you can know the userKey belongs to which user in your system.

Moreover, if a user would like to unbind BullStreet Pay service, he or she can unauthorize it in BullStreet mobile application. At this point, we will also send you userKey with status of unbinding to inform you the situation.

Based on the flow, we need you to provide us an endpoint to receive user key inforamtion. We will call the endpoint when:
1. User authorize the service(Bind)
2. User delete the service(Unbind)

For the detail information of the endpoint we need, please refer to [API Design](#API-Design).


## API Design
### Receive User Key Information
- **HTTP Method**: POST
- **URL**: https://your.domain.com/pay-api/v1/callback/widget/register
- **Headers**:
- **Content-Type**: application/json
- **Others**: Please refer to [Signature](#Signature)
- **Request Body**:
Parameter Name|Data Type|Required?|Description|
:--|:--|:--|:--|
userKey|string|v|User key for further use (e.g. [Get Payment Widget](https://api.btse.co/payment/pay-api#tag/Widget-Service/operation/post-payapi-widget-url))
status|string|v|The status of userKey. (e.g. `PENDING`, `BOUND`, `UNBIND`)
merchantUserId|string|v|User Id you provided when calling [Get Payment Widget](https://api.btse.co/payment/pay-api#tag/Widget-Service/operation/post-payapi-widget-url) if there is no userKey
merchantUsername|string||User name you provided when calling [Get Payment Widget](https://api.btse.co/payment/pay-api#tag/Widget-Service/operation/post-payapi-widget-url) if there is no userKey

    {
        "userKey": "0ac6086b31b159414755ee57147b3e272caa3e1056eca657720927bce6004c7b",
        "statusOfKey": "PENDING",
        "merchantUserId": "123456",
        "merchantUsername": "jane987"
    }

- **Response**:
The data in response depends on you, yet you must let us know whether you accept the request with HTTP status code `200`.

## Signature
For security, it will be better if there is a mechanism to verify whether payload is changed. Please refer to our signature mechanism described as below.

### Algorithm
We use `HMAC.SHA384` algorithm to generate signatures.

### Parameters Used for Generating Signatures

Key|Data Type|Example|Description
:--|:--|:--|:--
secret key|string| xxxxxxxxx |The secret key we provide you.
url|string|/api/binding/userInfo|API URI
nonce|string|1640313017000|current unix timestamps in milliseconds
request body|JSON string| |Should be JSON string

### Content-Type: `application/json`

url: /api/binding/userInfo
nonce: 1640313017000
body: {"userKey":"0ac6086b31b159414755ee57147b3e272caa3e1056eca657720927bce6004c7b","statusOfKey": "PENDING","merchantRegisterId": "123456","merchantRegisterName": "jane987"}

sign: HMAC.SHA384(secretKey, (url+nonce+body))
= HMAC.SHA384('xxxxxxxxx', '/api/binding/userInfo1640313017000{"userKey":"0ac6086b31b159414755ee57147b3e272caa3e1056eca657720927bce6004c7b","statusOfKey": "PENDING","merchantRegisterId": "123456","merchantRegisterName": "jane987"}')
= 718aa02d17b36965c1e7e32a492bd24449c2041140456422420e6ded2f1daafbcca20048e4027c523cf8ee77cc1ab959

### Put them in Header
- request-api: `api key paired with the secret key used in calculation`
- request-nonce: `1640313017000`
- request-sign: `718aa02d17b36965c1e7e32a492bd24449c2041140456422420e6ded2f1daafbcca20048e4027c523cf8ee77cc1ab959`

## Changelog
#### 2023.06.12
- Change attribute name in request body
- merchantRegisterId → merchantUserId
- merchantRegisterName → merchantUsername
- Adjust content based on final decision, removing binding process from registration but combining it with payment flow.

#### 2023.05.11
- Generate the 1st version of API doc for proceeding binding process during registration