💻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 - <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: <base_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:

         **http** Authorization: Bearer <your-jwt-token>

      3. Replace <your-jwt-token> 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: <base_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: <base_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: <base_url>/payments/payment_verify/<payment_id>

      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