@abhikumar_98/sdk v1.2.7

Purple Pay Specification

Summary

A standardised implementation for encoding payment requests as URLs and QRs EIP 67 is used as a reference.

Direct Transfer Request

Direct Transfer Request is a URL encoding scheme which can be used by a wallet to directly create and inititate a transaction

ethereum: ?value= &gas=<suggested_gas> &data= &token= &token_address=<token_address> &chain_id=<chain_id> &label= &message= &redirect=

Receiver

It is the address of the EOA that is receiving the payment. To receive an ERC20 token (USDC), token and token_address fields need to be populated.

Value

value field is the amount of token to be transferred. It must be non-negative integer. Wallet should prompt the user for amount if value is not provided.

Token

token field should contain the symbol of the token being used to transfer the payment in. It is not needed in case of native token transfer.

Token Address

token_address field should contain the address of the ERC20 token being used to transfer the payment in.

Data

date field contains bytecode for function invocation of the ERC20 contract for a non-native token.

Label (change wording)

The value must be a URL-encoded UTF-8 string that describes the source of the transfer request.

For example, this might be the name of a brand, store, application, or person making the request. The wallet should URL-decode the value and display the decoded value to the user.

Message (change wording)

he value must be a URL-encoded UTF-8 string that describes the nature of the transfer request.

For example, this might be the name of an item being purchased, an order ID, or a thank you note. The wallet should URL-decode the value and display the decoded value to the user.

Redirect (change wording)

A single redirect field is allowed as an optional query parameter. The value must be a URL-encoded absolute HTTPS or solana: URL.

The wallet must URL-decode the value. If it is a HTTPS URL then the wallet should display the decoded value to the user.

Redirect URLs should only be followed if the transaction is successful. A transaction should be considered successful if the user approves it and the broadcast transaction has a Confirmed or Finalized status. If the redirect is a HTTPS URL then the wallet should open the URL using any browser. This may be a browser included in the wallet. If it is a ethereum: URL then the wallet should treat it as a new Purple Pay request.

Transaction Request

This encodedes a URL for a payment transaction.

ethereum: The request is interactive because the parameters in the URL are used by a wallet to make an HTTP request to compose a transaction.

URL

The value must be a conditionally URL-encoded absolute HTTPS URL.

GET Request

The wallet should make an HTTP GET JSON request to the URL. The request should not identify the wallet or the user.

The wallet should make the request with an Accept-Encoding header, and should respond with a Content-Encoding header for HTTP compression.

The wallet should display the domain of the URL as the request is being made.

GET Response The wallet must handle HTTP client error, server error, and redirect responses. The application must respond with these, or with an HTTP OK JSON response with a body of

{"label":"","icon":""}

The value must be a UTF-8 string that describes the source of the transaction request. For example, this might be the name of a brand, store, application, or person making the request.

The value must be an absolute HTTP or HTTPS URL of an icon image. The file must be an SVG, PNG, or WebP image, or the wallet must reject it as malformed.

The wallet should not cache the response except as instructed by HTTP caching response headers.

The wallet should display the label and render the icon image to user.

POST Request

The wallet must make an HTTP POST JSON request to the URL with a body of

{"account":""} The value must be the base58-encoded public key of an account that may sign the transaction.

The wallet should make the request with an Accept-Encoding header, and the application should respond with a Content-Encoding header for HTTP compression.

The wallet should display the domain of the URL as the request is being made. If a GET request was made, the wallet should also display the label and render the icon image from the response.

POST Response The wallet must handle HTTP client and server errors in accordance with the error handling specification. Redirect responses must be handled appropriately. The application must respond with these, or with an HTTP OK JSON response with a body of

{"transaction":"", "redirect":""} The value must be a base64-encoded serialized transaction. The wallet must base64-decode the transaction and deserialize it.

The application may respond with a partially or fully signed transaction. The wallet must validate the transaction as untrusted.

Error Handling

If the application responds with an HTTP client or server error in response to the POST or PUT operations, the wallet must consider the entire transaction request as failed.

Client and server errors may optionally be accompanied by a JSON body containing a UTF-8 string message field describing the nature of the error:

{"message":""} The wallet must display at least the first 80 characters of the message field to the user if it is included in the response.