# API Documentation
## API Specification Common Standards
### Protocol Standards and Methods
| Action | Standard | Description |
| --------------------- | ----------------------- | ---------------------------------------------------------------- |
| Transfer | HTTPS enabled endpoints | Secure interactions (Payments, Customer) |
| Data Exchange (CRUD) | POST/GET/PUT/DELETE | Varies as per API |
| Data Format | application/json | All data exchanges (requests and responses made in this format) |
| Char Encoding | UTF-8 | |
| Signature Algorithm | HMAC-SHA512 | |
| Signature Requirement | WIP | Signature-checking is required for requesting and receiving data |
| Logic Judgment | | Determine protocol field, service field and transaction status. |
### Request Header
| Attributes | Type | Required | Limitation | Description |
| ------------ | ------ | -------- | ---------------- | ------------ |
| content-type | string | Y | application/json | content type |
| | | | | |
### Signature
#### Build the content
```
String payload = timestamp + "\n" + nonce + "\n" + body + "\n";
```
#### Sign the content
```
String signature = hex(hmac("sha512", payload, secretKey)).toUpperCase()
```
***
**NOTE**
* ‘\n’ is LF, ASCII value is '0x0A'
* Parameter names are case-sensitive;
* When checking returned data or a push notification signature, the transferred sign parameter is excluded in this signature as it is compared with the created signature.
* When post the Json body, carefully check the quote, **'** is not same as **"**
***
## Merchant APIs
**Base URL** - ` : api-azsit.purplepay.app`
### **Authentication**
1. Register as a merchant on PurplePay Dashboard with email and password
2. Purple Pay authentication API uses Bearer authorization. It should be included in the header
3. Generating JWT Token
1. End Point:
1. Method: POST
2. URL: `/auth/token`
2. Request Parameters:
| Attributes (1st level) | Type | Required | Description |
| ---------------------- | ------ | -------- | ---------------------------------------------------- |
| username | string | Y | email id as the username for signing up |
| password | string | Y | Strong alphanumeric password with special characters |
3. Response:
| Attributes | Type | Required | Description |
| -------------- | ------------ | -------- | ------------------------------------------------------------ |
| access\_token | string/token | Y | JWT token which is to be used to authenticate every request |
| refresh\_token | string/token | Y | Refresh token to get the new access\_token before it expires |
4. Using the JWT Token
1. Once you have generated a JWT access token, you can use it to authenticate your requests.
2. The token should be included in the `Authorization` header with the `Bearer` keyword, like so:
```python
**http** Authorization: Bearer
```
3. Replace `` with your actual JWT token.
4. Remember, all API requests must be made over HTTPS. Non-secure requests will fail.
***
### **Payments Config API**
1. It returns details of supported chains and their details.
2. It also returns data to support and enrich classification around the different attributes of payments such as payment type (merchant, ecommerce, P2P etc).
3. Endpoint:
1. Method: GET
2. URL: `/payments/chain_config`
***
### **Create Checkout API**
1. Payments API is used to create orders and generate counterfactual payment addresses to receive payments on different chains
2. Endpoint:
1. Method: POST
2. URL: `/payments/burner_address`
3. Request Parameters:
| Attributes (1st level) | Type | Required | Description |
| -------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| api\_key | UUID | Y | api\_key generated after signing up as a merchant |
| payment\_type | enum | string | |
| \[merchant pos, merchant one time, merchant ecommerce, p2p one time] | N | payment\_type is one of the values received from the config api. It serves to differentiate the category of source generating the payment. | |
| order\_amount | float | Y | value of the order |
| currency | enum | string | |
| \[usd] | N | currently, the defualt is in US Dollar. Support for generating orders in other currency is WIP and will be launched soon. | |
| description | string upto 500 characters | | |
| chain\_id | enum | int | |
| testnet: \[80001, 81] | | | |
| mainnet: \[592, ] | Y | It is one of the chain ids received from chain\_config. This chain id is used to create the counterfactual address on the relevant chain. | |
| user\_order\_id | string | | merchant generated order id |
4. Response:
| Attributes (1st level) | Attributes (2nd level) | Attributes (3rd level) | Type | Required | Description |
| ---------------------------------------------- | ---------------------- | ----------------------------------------- | ------ | -------- | -------------------------------- |
| data | | | | | |
| | tokens | | | | |
| | | burner\_address | | | |
| | | order\_amount | | | |
| | | conversion\_rate\_in\_usd | | | |
| | | is\_used\_for\_payment | | | |
| | | transfer\_to\_merchant\_transaction\_hash | | | |
| | | burner\_contract\_deploy\_status | | | |
| | | burner\_contract\_deploy\_failure\_reason | | | |
| | | symbol | | | |
| | | token\_address | | | |
| | | chain\_id | | | |
| | | chain\_name | | | |
| | | decimals | | | |
| | | image\_url | | | |
| | id | | | | Payment Id created in Purple Pay |
| | payment\_status | | string | enum | |
| \[In Progress, Completed, Partially Completed] | | | | | |
| | description | | string | | |
| message | | | string | | |
| error | | | | | |
***
### **Payment Status API**
1. The payment status and verification API tracks and updates the status of payments for the given Purple Pay order id.
2. Endpoint
1. Method: GET
2. URL: `/payments/payment_verify/`
1. This payment id can be purple pay payment\_id or merchant user\_order\_id.
3. Request Parameters
1. payment\_id in url path as mentioned above
4. Response:
| Attributes (1st level) | Attributes (2nd level) | Attributes (3rd level) | Type | Required | Description |
| --------------------------------------------------------------- | ---------------------- | ----------------------------------------- | ---------------- | -------- | ----------- |
| data | | | | | |
| | id | | | | |
| | payment\_details | | | | |
| | tokens | | array of objects | | |
| | | burner\_address | | | |
| | | order\_amount | | | |
| | | is\_used\_for\_payment | | | |
| | | symbol | | | |
| | | token\_address | | | |
| | | chain\_id | | | |
| | | chain\_name | | | |
| | | decimals | | | |
| | | image\_url | | | |
| | | conversion\_rate | | | |
| | | transfer\_to\_merchant\_transaction\_hash | | | |
| | | burner\_contract\_deploy\_status | enum | string | |
| \[initiated deploy, not deploy, failure deploy, success deploy] | | | | | |
| | | burner\_contract\_deploy\_failure\_reason | | | |
| message | | | | | |
| error | | | | | |
| payment\_status | | | | | |