[title] Initialize [path] Untitled/ The Unity SDK needs to be initialised with configuration information associated with the mobile application, firebase realtime database and Pay3 environment settings. **Initialization Parameters** 1. **pay3HostName**: Pay3 will be opened in a new window using this hostname prefix. The host name is environment dependent. 2. **pay3ClientId**: A unique client id is created for each client application. The client id is environment dependent. 3. **appNotify\* Configs**: These are config parameters for firebase realtime database. This is used to publish realtime events to the app. 4. **appDeepLink**: This string in the form of `scheme://resource` can be passed during initalization. This will be used by Pay3 as referrer / redirect intent. The string needs to be whitelisted in Pay3 backend for proper working of the Pay3 services. Following are the **sample code** **snippets** for your reference. The entire package with complete example will be provided during onboarding. Game can use **Pay3SDKConfig.cs** which extends *ScriptableObject.* This accepts all settings required for Pay3 SDK. Game can create an asset using this. The asset needs to be passed to *Pay3Helper.cs* instance. :::CodeblockTabs Pay3SDKConfig.cs ```cpp using UnityEngine; [CreateAssetMenu(fileName = "Pay3SDKConfig", menuName = "ScriptableObjects/Pay3SDKConfig", order = 1)] public class Pay3SDKConfig : ScriptableObject { public string androidPackageId; public string appNotifyApiKey; public string appNotifyAppId; public string appNotifyProjectId; public string appNotifyDatabaseUrl; public string appNotifyStorageBucket; public string appDeepLink; public string pay3ClientId; public string pay3HostName; } ``` ::: Game can instantiate **Pay3Helper.cs** that extends *MonoBehaviour*. This loads configuration from Pay3SDKConfig during the Start. :::CodeblockTabs Pay3Helper.cs ```cpp namespace Pay3.SDK.Helper { // Import essential packages using Firebase.Auth; using Firebase.Database; using Firebase; using UnityEngine; public class Pay3Helper : MonoBehaviour { // Attach the Pay3SDKConfig to this Behaviour public Pay3SDKConfig sdkConfig; // When the app starts, check to make sure that we have // the required dependencies to use Firebase, and if not, // add them if possible. public virtual void Start() { InitializeFirebaseAuth(); } // Handle initialization of the necessary firebase modules: private void InitializeFirebaseAuth() { authOptions = new Firebase.AppOptions { // Use Configuration from Pay3SDK Config }; fbApp = Firebase.FirebaseApp.Create(authOptions, "Pay3"); auth = Firebase.Auth.FirebaseAuth.GetAuth(fbApp); SignInAnonymously(); } // Request anonymous sign-in and wait until asynchronous call completes. private void SignInAnonymously() { auth.SignInAnonymouslyAsync().ContinueWith((authTask) => { if (authTask.IsCompleted) { Firebase.Auth.FirebaseUser user = authTask.Result.User; StartTransactionListener(user.UserId); } }); } } } ``` ::: *** [title] Pay3 Javascript SDK [path] / Pay3 Javascript SDK provides a two-way communication with Pay3 webapp: This can be integrated to the application using one of the following methods: 1. NPM module [@pay3/sdk ](https://www.npmjs.com/package/@pay3/sdk) 2. OR Script tag of the application's html file `https://pay3.money/pay3-sdk-pay/index.global.X.Y.Z.js` Pay3 webapp is a highly customisable. Following picture show high-level communication between the integrating App and Pay3. ## Checkout Integration Checkout flow can be utilised by the applications to get users buy and pay using their preferred local currencies. ### Integration Design ![](https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/K2UKgFwHExp_rm9hHwWTW_pay3-sdk-checkout-integration.png) ## Payout Integration Payout flow can be utilised by the application to allow users to withdraw funds from the application into their preferred payment instrument. ### Integration Design ![](https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/FeH9VAxNNzQLR7fKH65VD_pay3-sdk-payout-integration.png) ## Crypto Payin Integration Users can pay via Crypto for the product and services provided by the application. ![Crypto Payin Integration Overview](https://archbee-image-uploads.s3.amazonaws.com/5goxYzXl7cEfaX56A_Ptv-gu7bbgpgWdSpilAsugHS5-20240828-072348.png "Crypto Payin Integration Overview") Above diagram shows the integration overview for Crypto payin. *** [title] Get Fiat Order Details [path] Pay3 API Documentation/ API that returns clients orders matching the *requestId*. This api requires access token that can be generated using [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA) API. The response is a list of Orders which matches the given criteria. 1. `orderStatus` : For list of possible status please refer : [Fiat Order Status](docId:-_ZgIyFgAsxS2Uqr272QA) 2. `userAddress` : User's email address 3. `updatedTs` : Last Order updated timestamp in epoch milliseconds 4. `partner` : Downstream partner ID 5. `orderType` : Type of Order. Can be CHECKOUT/PAYOUT 6. `requestId` : Unique ID passed during Order creation 7. `clientId` : Client ID 8. `exchangeCurId` : Name of the currency supported 9. `exchangeAmount` : Currency Amount 10. `paymentMethod` : Payment Method specified for Order 11. `errorReason` : Contains `errorCode` and `errorDesc`. Will be received only in case if status is FAILED. List of possible [Error Codes](docId\:upvtC67WkwGNCSCjVAQ0v) :::ApiMethodV2 ```json { "name": "Get Order Details", "method": "GET", "url": "https://your-hostname.pay3.app/v1/client/orders?requestId=your-request-id&clientId=your-client-id", "description": "Get order details by client's request-id", "tab": "examples", "examples": { "languages": [ { "id": "3LjxGJCqZzKeICMDOi23s", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/client/orders?requestId=your-request-id&clientId=your-client-id' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--header 'access-token: ACCESS-TOKEN-IN-JWT'", "customLabel": "" } ], "selectedLanguageId": "3LjxGJCqZzKeICMDOi23s" }, "results": { "languages": [ { "id": "GC_lbEEV7Jo_hgFNI1cHK", "language": "200", "customLabel": "", "code": "{\n \"data\": [\n {\n \"orderId\": \"4073be54-5903-47c8-820f-17aa12964ba8\",\n \"orderStatus\": \"FAILED\",\n \"userAddress\": \"user@email.com\",\n \"updatedTs\": 1706610264546,\n \"partner\": \"xyz\",\n \"orderType\": \"CHECKOUT\",\n \"requestId\": \"900531\",\n \"clientId\": \"YOUR-CLIENT-ID\",\n \"exchangeCurId\": \"brl_bz\",\n \"exchangeAmount\": \"2.00\",\n \"paymentMethod\": \"pix\",\n \"errorReason\": {\n \"errorCode\": \"9004\",\n \"errorDesc\": \"Error occurred while the payment was processed by the payment partner\"\n }\n }\n ]\n}" }, { "id": "Ybev9LI4TwGz-n2zW-919", "language": "401", "customLabel": "", "code": "{\"error\":\"Client verification failed\"}" } ], "selectedLanguageId": "GC_lbEEV7Jo_hgFNI1cHK" }, "request": { "pathParameters": [], "queryParameters": [ { "name": "requestId", "kind": "required", "type": "string", "description": "Request Id is the unique id that was passed by your application while creating the order.", "children": [] }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client Id", "children": [] } ], "headerParameters": [ { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired.", "children": [] } ], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Header Parameter", "value": "headerParameters" }, "hasTryItOut": false, "autoGeneratedAnchorSlug": "get-order-details", "legacyHash": "-iBJgsqJ9XnskOxFc1df4" } ``` ::: *** [title] Agentic AI Payments [path] / [title] Invoicing and Billing Agent [path] / [title] Onboarding [path] Overview/ Our onboarding process is designed to ensure a smooth and productive integration of our services into your operations. It involves understanding your business, establishing pricing agreements, and facilitating technical integration. This process is tailored to ensure both regulatory compliance and seamless technical integration, setting the stage for a successful partnership. ## Phase 1: Know Your Business (KYB) Onboarding ### Step 1: Business Screening In the initial step, we will collect and verify essential business information to ensure regulatory compliance and better understand your organisation. This process involves gathering and validating key details about your business. ### Step 2: Pricing Agreements Following the KYB screening, we will proceed to discuss and confirm the pricing agreements. We will also engage in a dialogue to agree on any other relevant fees related to the integration process. This step ensures that we establish a transparent pricing structure tailored to your specific requirements. ## Phase 2: Technical Onboarding: ### Step 1: Domain Whitelisting After the KYB onboarding, the technical phase begins with domain whitelisting. You will provide domain information for system access, and we will proceed to whitelist the specified domains, granting authorised access to our platform. This step is essential for secure and authorized interaction with our services. ### Step 2: Enabling country currency for the application. This step involves integrating the appropriate country currency and mapping to best payment partner services for the client. into the system for in-game purchasing or other purposes. Pay3 routing engine requires onboarding of client to list of supported country currency. These registered currency names are used during transaction. For example `usd_us`, `gbp_gb`, `brl_bz` ### Step 3: API and SDK Key Sharing In this step, we will share API hostnames, client IDs and SDK keys. These keys are required for accessing and utilizing our system's capabilities. We will also provide comprehensive instructions on how to effectively use these keys for system integration, ensuring a seamless technical onboarding process. This step is fundamental for the successful integration of our services into your operations. The rest of the document describes the functionality of our system in detail. [title] Overview [path] / Pay3 provides the transactional infrastructure that powers a wide range of businesses e-commerce, travel, gaming, and digital services, helping them seamlessly onboard users and accept payments globally. We enable enterprises to accept **fiat payments, digital currencies, cryptocurrencies, and stablecoins** across mobile, web, and POS, ensuring smooth operations across all channels. Our platform supports a variety of use cases, including **card and bank-based fiat payments, online checkout solutions, digital goods, remittances, on/off-ramps, and in-game purchases**. Pay3’s solutions enable companies to launch and scale rapidly, offering a secure, cost-efficient, and reliable alternative to building and maintaining in-house payment infrastructure across both **fiat and digital asset rails**. [title] Getting Started [path] / Pay3-Checkout allows you to set up widely used popular payment methods with just one integration, providing a smooth checkout process for your in-game purchases. Few lines of code is all needed to complete the integration, giving your users an excellent experience. Following documentation will help you get up to speed with Pay3 SDK integration. [title] Initialize using script tag [path] Pay3 Javascript SDK/ ## Include script dependency When using script dependency you can include the javascript's url with in the head section of the application. X.Y.Z is the version of the javascript file, for instance: `https://pay3.money/pay3-sdk-pay/index.global.1.2.3.js` :::CodeblockTabs index.js ```html ``` ::: This script creates a singleton instance of the Pay3 class and exports an object `window.pay3Pay` ## init() Init saves the parameters which will be used during future function calls. It also registers a listener to listen for messages from Pay3. Pay3 team shares `hostname` and `clientId` during onboarding. **Parameters** 1. **hostname**: Pay3 will be opened in a new window using this hostname prefix. The host name is environment dependent. 2. **clientId**: A unique client ID is created by the Pay3 team to identify the client application. The client ID is environment dependent. 3. **lang **(optional, default value 'en'): This parameter specifies the language preference for the Pay3 SDK. The strings used follow two letter language code as in ISO 639-1. Example **pt** for Portuguese, **en** for English. :::CodeblockTabs index.js ```javascript window.pay3Pay.init(hostname, clientId); ``` ::: *** [title] Transactions [path] Untitled/ ### TriggerOpenCheckout The application can use `TriggerOpenCheckout` to receive payments from the users. Here the Pay3 modal will guide user through fiat payment services and deposit the payment to the app's Fiat account. **checkoutPayload : JSON string with following parameters** 1. **requestId **(Type string): App needs to generate a unique identifier for every checkout call. This ID will be provided in the events and Webhooks callbacks. This ID can be used by the App to identify and update state in App's backend. 2. **user **(Type Object): User details can be passed to Pay3 in this object. 1. **email** (Type string): Provide valid email address of user. This data will be passed to paymen partner during the Fiat checkout flow. Payment Partner might send mails to user updating them status of their transaction. 3. **payment** (Type Object): This section provides is the amount payable by the user of your platform. It could be cost price of your digital asset user wishes to checkout. 1. **amount** (Type string): String representing currency amount in two decimal precision. The amount is provided separately for each supported currency. 2. **name** (Type string): Name of the currency supported in the purchase flow. The name will be provided by Pay3 during Onboarding. 4. **userMessage** (Type string): Short meaningful name of the asset user is about to purchase :::CodeblockTabs Pay3Helper.cs ```cpp public class Pay3Helper : MonoBehaviour { // Pseudocode to trigger checkout using Fiat public void TriggerOpenCheckout() { string checkoutPayload = "{}"; // Create a checkout payload byte[] plainTextBytes = Encoding.UTF8.GetBytes(checkoutPayload); string requestParam = Convert.ToBase64String(plainTextBytes); string reqUrl = "https://"+hostName+"/web-sdk/"+ clientId +"?referrer="+deepLink+"&action=checkout&data=" + requestParam; Application.OpenURL(reqUrl); } } ``` ::: *** [title] Pay3 Unity Integration [path] / Pay3 provides support for application developed using Unity. The SDK provides two-way communication with Pay3 webapp. Pay3 webapp is a versatile application that can handle various payment methods for your users. Pay3 publishes realtime events to native applications like Unity games using Firebase Realtime database. ## Frontend Integration ![Pay3 SDK integration](https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/G0ZydWW8QkCnTjR0T7VSq_nn-4.png "Native SDK Integration") ## Backend Integration ![Backend Integration](https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/H3nD_gi9YI5CIbwWJK_yF_screenshot-2024-02-08-at-42354-pm.png "Backend Integration") *** [title] Event Listeners [path] Pay3 React Native SDK/ ### Introduction After completing transactions in Pay3 SDK UI, the Pay3 SDK publishes events to App. ### pay3-sdk-transaction-status This event is fired by Pay3 SDK on completion of checkout transaction triggered by checkout webview `pay3.geCheckoutWebView()` **Payload** 1. `data` (Type Object): Following keys are present in this object 1. `status` (Type string): The status can have values `SUCCESS` or `ERROR`. 2. `message` (Type string): User-friendly message returned after completion of the transaction. 3. `orderId` (Type string): Pay3 Order ID. 4. `requestId` (Type string): Unique id passed by App. 2. `error` (Type Object, Optional): Following keys will be present if there is an error. Please refer to [SDK Errors](docId\:upvtC67WkwGNCSCjVAQ0v) for reference. 1. `code` (Type number): Error code. 2. `message` (Type string): Error message. :::CodeblockTabs index.js ```javascript pay3.on('pay3-sdk-transaction-status', (payload: any) => { // Add your custom logic to handle the transaction status setPay3CheckoutVisibleState(false); // Can be used to hide the Checkout WebView }, ); ``` ::: ### Sample Event ```javascript { "data": { "message": "Transaction completed successfully", "orderId": "7a38ee7f-d5a9-45c8-af6b-e75d4190722a", "receipt": "txnReceipt", "requestId": "252425", "status": "SUCCESS" }, "ts": 1706087047736 } ``` *** [title] Transactions [path] Pay3 React Native SDK/ ### pay3.getCheckoutWebView(checkoutObj) The application can use `getCheckoutWebView`, which returns a `WebView` component from `react-native-webview`npm package. Here the Pay3 modal will guide user through fiat payment services and deposit the payment to the app's Fiat account. **Parameters** 1. **requestId **(Type string): App needs to generate a unique identifier for every checkout call. This id will be provided in the Javascript events and Webhooks callbacks. This id can be used by the App to identify and update state in App's backend. 2. **user **: User details can be passed to Pay3 in this object. 1. **email** (Type string): Provide valid email address of user. This data will be passed to partner service during the Fiat checkout flow. Payment partner may send mails to user updating them status of their transaction. 3. **payment** : This section provides is the amount payable by the user of your platform. It could be cost price of your digital asset user wishes to checkout. 1. **amount** (Type string): String representing currency amount in two decimal precision. The amount is provided separately for each supported currency. 2. **name** (Type string): Name of the currency supported in the purchase flow. The name will be provided by Pay3 during Onboarding. 4. **userMessage** (Type string): Short meaningful name of the asset user is about to purchase. ```javascript const checkoutObj = { "requestId": requestId, "user": { "email": "user@email.address" }, "payment": [ { "amount": "20.25", "name": "brl_bz" }, { "amount": "5.05", "name": "usd_usa" }, { "amount": "4.00", "name": "gbp_gb" } ], "userMessage": "Sample Message" }; // Opens Pay3 Buy modal return ( <> {pay3checkoutVisibleState? pay3.getCheckoutWebView(checkoutObj) : null} ); ``` *** [title] Pay3 React Native SDK [path] / Pay3 React Native SDK is a node module [@pay3/sdk-react-native ](https://www.npmjs.com/package/@pay3/sdk-react-native) that can be included within the mobile application. The sdk provides two-way communication with Pay3 webapp . Pay3 webapp is a versatile application that can handle various payment methods for your users. Pay3 publishes realtime events to mobile applications using Firebase Realtime database. ![Pay3 Checkout Flow](https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/KQN6tQg52nv8-Qm1P_gK__fiat-checkout-flow.png "Pay3 Checkout Flow") *** [title] End User Flow - Crypto Checkout [path] Untitled/ This feature allows you to accept payments in cryptocurrencies and stablecoins across popular chains such as Ethereum, Tron, Solana, Polygon, and Bitcoin. User can do the payment using two methods: 1\. Connect user's wallet like Metamask, Coinbase, Walletconnect etc and pay through the connected wallet. 2\. Users can pay by using the QR code. For reference, we will go over the flow of USDT Checkout on Polygon using QR code method. 1. User finishes the complete payment - When the user initiates the payment, the user is presented with the screen which will comprise the amount, network and QR code and the fees. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/di5ypDwXXaMld9nB-Pon4_screenshot-2024-05-09-at-548-1.png" size="50" width="1680" height="2690" position="center" darkWidth="1680" darkHeight="2690" showCaption="false"} - Once the user scans the QR code and the payment is done, the user indicates that the transfer is completed by using the 'I have completed this payment' button - Upon confirmation, the transaction is processed and relevant status of the transaction is presented to the user along with the reference ID of the transaction. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/5goxYzXl7cEfaX56A_Ptv-NrnErMLIQCF5aMRsMCXdw-20250829-052019.png" size="50" width="840" height="854" position="center" darkWidth="840" darkHeight="854" showCaption="false"} 2\. User makes partial payment - When the user initiates the payment, the user is presented with the screen which will comprise the amount, network and QR code and the fees. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/F8lLoWompq0Mk1JwZDpvU_screenshot-2024-05-09-at-548-1.png" size="50" width="1680" height="2690" position="center" darkWidth="1680" darkHeight="2690" showCaption="false"} - Incase the user now makes the partial payment and indicates that the transfer is completed by using the 'I have completed this payment' button, we will indicate to the user that they have only completed a partial payment. They will be given an option to finish the transaction by re-generating the QR code. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/q-egACaO3JG4QuYmkAzK4_underpaid-transaction-6.png" size="50" width="1694" height="2234" position="center" darkWidth="1694" darkHeight="2234" showCaption="false"} - The user is shown the re-generated QR code with the updated amount which needs to be paid by the user. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/1aKyF46WACQqRxo6Thb0H_group-1000008647.png" size="50" width="840" height="1345" position="center" darkWidth="840" darkHeight="1345" showCaption="false"} - Upon confirmation, the transaction is processed and relevant status of the transaction is presented to the user along with the reference ID of the transaction. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/5goxYzXl7cEfaX56A_Ptv-NrnErMLIQCF5aMRsMCXdw-20250829-052019.png" size="50" width="840" height="854" position="center" darkWidth="840" darkHeight="854" showCaption="false"} **Note: BTC transactions involve longer confirmation times **compared to other crypto payments. Because of Bitcoin’s inherent blockchain characteristics, users should expect delays before the payment is fully confirmed by the network. This longer processing time is normal and simply reflects the required number of blockchain confirmations. Hence, we take the user through a slightly different flow where a ‘Payment Initiated’ screen is shown, and the merchant is updated regarding the order status through a Webhook after we receive confirmation from the Bitcoin Network. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/5goxYzXl7cEfaX56A_Ptv-I7Uqc2lNMCT1X0PjCIyEC-20250828-085628.png" size="50" width="1260" height="1281" position="center" darkWidth="1260" darkHeight="1281" showCaption="false"} *** [title] End User Flows [path] / This section explains the key steps a user follows, from starting a transaction to completing the purchase. The flow highlights how tokens are credited or debited to the user’s account. Sample UI screenshots are included to help visually understand each step of the user experience. *** [title] End User Flow - Fiat Payout [path] Untitled/ You can request payouts of Game rewards and other in-game assets using popular Fiat payment methods. For reference, we will go over the flow of Fiat Payout with the Bank Transfer method in Brazil: 1. When the payout flow starts, the user is presented with the screen which will comprise the First Name, Last Name, Fiat Amount, Document Type and Document ID ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/JAyK0kMr8UsM2IFZQidLD_group-1686554534.png" size="50" width="1688" height="2822" position="center" showCaption="false"} 2\. After user verifies the above details, the Full Name and Bank Account details are fetched from the last payin transaction and displayed to the user for his reference. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/5IoWUKF5rC5NPuj-2Nv1w_group-1686554525.png" size="50" width="1686" height="2826" position="center" showCaption="false"} 3\. After reviewing the details, the user is required to submit the transaction and the payout is initiated. Note: Based on the partner and payment method, processing of payouts can take up to 90 seconds for instant payouts. For non-instant payouts, it will be processed during business banking hours. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/9JcgbaqQe2mz216pCFoHU/NCKNzdVmHXpG63ES9OF8-_group-1000008683.png" size="50" width="1688" height="1754" position="center" showCaption="false"} *** [title] End User Flow - Crypto Payouts [path] Untitled/ This feature allows you to pay out your users in cryptocurrencies and stablecoins across popular chains such as Ethereum, Tron, Solana, Polygon, and Bitcoin. Users can receive payouts by going through the following steps: 1. All the required details for the payout such as Wallet Address, Token, Amount, and Chain are provided to us and displayed to the user. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/5goxYzXl7cEfaX56A_Ptv-P5FLEkvXAMtyVspJdRu0J-20250829-051527.png" size="50" width="848" height="1500" position="center" darkWidth="848" darkHeight="1500" showCaption="false"} 2\. The user verifies all the information on the screen and submits the payout request. Upon confirmation, the transaction is processed, and the relevant status is displayed to the user along with the transaction reference ID. ::Image[]{src="https://archbee-image-uploads.s3.amazonaws.com/5goxYzXl7cEfaX56A_Ptv-NrnErMLIQCF5aMRsMCXdw-20250829-052019.png" size="50" width="840" height="854" position="center" darkWidth="840" darkHeight="854" showCaption="false"} *** [title] Update Your Webhook [path] Pay3 API Documentation/ This API changes the current configured webhook for your payment notifications at Pay3's end. :::ApiMethodV2 ```json { "name": "Update Your Webhook", "method": "POST", "url": "https://your-hostname.pay3.app/v1/client/webhook-url", "description": "Get balance for a Client ID", "tab": "examples", "examples": { "languages": [ { "id": "R_kjEOVWrgdjXK9y79KWL", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/client/fiat/webhook-url' \\\n--header 'access-token: ACCESS-TOKEN-IN-JWT' \\\n--header 'client-id: YOUR-CLIENT-ID' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"webhookUrl\": \"your-webhook-endpoint\"\n}'", "customLabel": "" } ], "selectedLanguageId": "R_kjEOVWrgdjXK9y79KWL" }, "results": { "languages": [ { "id": "-WPelU7C1GJ3RYSstvFCO", "language": "200", "customLabel": "", "code": "{\n \"message\": \"Webhook endpoint updated successfully.\"\n}" }, { "id": "nV086WqVdYra6yxpqPFIt", "language": "400", "customLabel": "", "code": "{\n \"error\": {\n \"code\": \"400\",\n \"message\": \"Could not verify the client\"\n }\n}" } ], "selectedLanguageId": "nV086WqVdYra6yxpqPFIt" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired.", "children": [] }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client id. Application's Identifier", "": "Client id. Application's Identifier" } ], "bodyDataParameters": [ { "name": "webhookUrl", "kind": "optional", "type": "string", "description": "Client's webhook URL endpoint to be configured", "": "Client's webhook URL endpoint to be configured" } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "autoGeneratedAnchorSlug": "update-your-webhook", "legacyHash": "doQI9gILV4-iR9zqY-57O" } ``` ::: *** [title] Access Token [path] Pay3 API Documentation/ # Get Access Token This api returns access token that can be used in some of our API endpoints here. **Important**: **Only call this API from server side** where the api-secret is well protected. :::ApiMethodV2 ```json { "name": "Get Access Token", "method": "GET", "url": "https://your-hostname.pay3.app/v1/auth/access-token", "description": "Get access token using api secret and client id", "tab": "examples", "examples": { "languages": [ { "id": "AZqOTJjcGUy11gU45LLMe", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/auth/access-token' \\\n--header 'api-secret: YOUR-API-SECRET' \\\n--header 'client-id: YOUR-CLIENT-ID'\n ", "customLabel": "" } ], "selectedLanguageId": "AZqOTJjcGUy11gU45LLMe" }, "results": { "languages": [ { "id": "kCj1U3BaA8qdjse8CmUlZ", "language": "200", "customLabel": "", "code": "{\n \"accessToken\": \"ACCESS-TOKEN-IN-JWT\"\n}" }, { "id": "MI7qeU6S41sbo6vz9368z", "language": "401", "customLabel": "", "code": "Unauthorized access" } ], "selectedLanguageId": "kCj1U3BaA8qdjse8CmUlZ" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "api-secret", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired.", "children": [] }, { "name": "client-id", "kind": "required", "type": "string", "description": "Client Id", "children": [] } ], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Header Parameter", "value": "headerParameters" }, "hasTryItOut": true, "autoGeneratedAnchorSlug": "get-access-token-1", "legacyHash": "aVw21md4V3_tmSG0I0usw" } ``` ::: *** [title] Create Crypto Payout Order [path] Pay3 API Documentation/ This API creates a payout order to enable users to withdraw funds. It accepts `address`, `currency` ,`clientId` and `amount`. This api requires access token that can be generated using [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA) API. :::ApiMethodV2 ```json { "name": "Create Crypto Payout Order", "method": "POST", "url": "https://your-hostname.pay3.app/v1/client/crypto-payout/create-order", "description": "Create an order with payout details from application's backend", "tab": "examples", "examples": { "languages": [ { "id": "nyfSHp7J-NrsuqTH3FW7t", "language": "curl", "code": "curl --location 'https://api.dev.pay3.app/v1/client/crypto-payout/create-order' \\\n--header 'signature: {{signature}}' \\\n--header 'access-token: {dynamic-access-toke}' \\\n--header 'Content-Type: application/json' \\\n--data '{\n \"clientId\": \"....\",\n \"requestId\": \"a1d4a50e-5577-4581-a980-98b03bc76260\",\n \"amount\": \"0.0001\",\n \"currency\": \"btc_bitcointestnet\",\n \"address\": \"0x5Fc0D01A67E756a15B8eb56937Fcb382637E8D2\",\n \"mode\":\"returnUrl\"\n }", "customLabel": "" } ], "selectedLanguageId": "nyfSHp7J-NrsuqTH3FW7t" }, "results": { "languages": [ { "id": "VQyRchSR38UbBEhATUpjh", "language": "200", "code": "mode=returnUrl\n{\n \"token\": \"b5ed337a-e299-4f2b-aa76-50c68097d9c1\",\n \"requestId\": \"a1d4a50e-5577-4581-a980-98b03bc76260\",\n \"url\": \"https://host.pay3.app/pay3-sdk-ui-path\"\n}\n\nmode=createEstimate\n{\n \"token\": \"a003d60c-d0ae-40e5-a7cb-2634ab607253\",\n \"requestId\": \"a1d4a50e-5577-4581-a980-98b03bc76260\",\n \"currency\": \"btc_bitcointestnet\",\n \"address\": \"tb1q7sqtxktz3jle8evmfnnhv45s0maudwdtknmdqu\",\n \"warning\": \"The btc_bitcointestnet balance (0.0031) is below the configured threshold (100.0000).\",\n \"estimatedFees\": \"0.000066\",\n \"estimatedNetAmount\": \"0.000034\"\n}", "customLabel": "" }, { "id": "tIvoQbUSKGnrqallvNDVQ", "language": "401", "code": "{\n error: {\n code: '7001',\n message: 'Order already exists for given requestId'\n }\n}", "customLabel": "" } ], "selectedLanguageId": "VQyRchSR38UbBEhATUpjh" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "signature", "kind": "required", "type": "string", "description": "Signature generated with sha256 followed by base64 encoding. Check below section for more details", "children": [] }, { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired", "children": [] } ], "bodyDataParameters": [ { "name": "requestId", "kind": "required", "type": "string", "description": "Identifier that is created by client application's backend. This will be passed in relevant events and webhooks from Pay3 to Application", "children": [] }, { "name": "address", "kind": "required", "type": "string", "description": "The address is the destination wallet address where the crypto token currency will be deposited after the payout is processed. (User's wallet address should be passed in this)", "": "The address is the destination wallet address where the crypto token currency will be deposited after the payout is processed. (User's wallet address should be passed in this)" }, { "name": "currency", "kind": "required", "type": "string", "description": "The currency is Pay3's unique string ID denoting the token that needs to be purchased. Example value are btc_bitcoin, usdt_polygon, uni_eth. " }, { "name": "amount", "kind": "required", "type": "string", "description": "The amount in ethereum / btc user needs to pay. ", "": "The amount in ethereum / btc user needs to pay. " }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client id. Application's identifier", "children": [] }, { "name": "mode", "kind": "optional", "type": "string", "description": "The supported values for mode are returnUrl, createEstimate, and default.\n\nreturnUrl: API response includes an additional field token, requestId and url.\nThis URL provides a direct checkout page link where users can complete their crypto payment through a hosted frontend flow.\n\ncreateEstimate: API returns a token and requestId.\nThese values must be passed to the Execute Crypto Payout Order API to complete the payout. This flow is fully backend-driven and does not involve any frontend or UI.", "": "The supported values for mode are returnUrl, createEstimate, and default.\n\nreturnUrl: API response includes an additional field token, requestId and url.\nThis URL provides a direct checkout page link where users can complete their crypto payment through a hosted frontend flow.\n\ncreateEstimate: API returns a token and requestId.\nThese values must be passed to the Execute Crypto Payout Order API to complete the payout. This flow is fully backend-driven and does not involve any frontend or UI." }, { "name": "callbackUrl", "kind": "optional", "type": "string", "description": "Application can provide a url in this parameter. After completion of the transaction, user will be redirected to this url. An additional parameter data query parameter will be added to the url. ", "": "callbackUrl" }, { "name": "sponsorFee", "kind": "optional", "type": "boolean", "description": "When sponsorFee is set to true, the exact amount is sent to the destination address (user's address) without deducting fees.", "": "When sponsorFee is set to true, the exact amount is sent to the destination address (user's address) without deducting fees." }, { "name": "userId", "kind": "optional", "type": "string", "description": "Pass any string for the user (uniqueId) to identify and map the orders against the user. This can be same value which you are using in your application to uniquely identify the users.", "": "Pass any string for the user (uniqueId) to identify and map the orders against the user. This can be same value which you are using in your application to uniquely identify the users." } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "response": [ { "name": "token", "kind": "optional", "type": "string", "description": "Returned as part of the payout order creation. This value authorizes and links the execution request to the original payout order. \n\nFor mode = createEstimate\nThis token must be passed to the Execute Crypto Payout Order API to finalize and trigger the payout. " }, { "name": "requestId", "kind": "optional", "type": "string", "description": "This is the same value of requestId passed while calling this API", "children": [] }, { "name": "url", "kind": "optional", "type": "string", "description": "(Returned only when mode = returnUrl)\nA direct checkout page link where users can complete their crypto payment through a hosted frontend page.", "children": [] }, { "name": "currency", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe currency string representing the token selected for payout. Example values include btc_bitcoin, usdt_polygon etc. Same as passed in the request.", "children": [] }, { "name": "address", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe destination wallet address where the payout is intended to be processed. Same as passed in the request.", "children": [] }, { "name": "warning", "kind": "optional", "type": "string", "description": "May provide additional information or caution related to the payout session, eg. Payout wallet balance is lesser than threshold. \n", "children": [] }, { "name": "estimatedFees", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe estimated gas/network fees in \"currency\" value, required to complete the payout.", "children": [] }, { "name": "estimatedNetAmount", "kind": "optional", "type": "string", "description": "(Returned for mode = createEstimate)\nThe estimated net amount in \"currency\" value, the user will receive after deducting gas fees and any applicable charges.", "children": [] } ], "hasTryItOut": false, "autoGeneratedAnchorSlug": "create-crypto-payout-order", "legacyHash": "sqj7sRsDC04r4g-8bBx8B" } ``` ::: ## Signature Generation The request for creating payout order requires a header `signature`. This can be generated using following javascript code snippet. ```javascript const crypto = require('crypto'); // Required Parameters const secretKey="Api-Secret-Provided-By-Pay3"; const address = "destination-wallet-address"; const currency = "currency-id"; const amount = "0.02"; const requestId = "Order-Id-Generated-By-Application"; const getSignature = (secretKey, address, currency, amount, requestId) => { // Prepare the string to sign in same format. const stringToSign = 'address=' + address + '¤cy=' + currency + '&amount=' + amount + '&requestId=' + requestId; // Generating signature using SHA256 and provided secret and // base64 encode the result const mac = crypto.createHmac('sha256', secretKey); return mac.update(stringToSign).digest('base64'); } // Generate Signature const signature = getSignature(secretKey, address, currency, amount, requestId); ``` *** [title] Postman API Collection [path] Pay3 API Documentation/ The Pay3 Postman API Collection is your gateway to seamlessly test and integrate our suite of payment orchestration APIs. Explore, test, and build robust payment solutions for your business with ease. ## Getting Started ### Step 1: Access the API Collection 1. **Download the Collection:** Click here to download the [Pay3 API Collection](https://documenter.getpostman.com/view/47708127/2sBXcAH2WE) ### Step 2: Set Up Your Environment 1. **Configure Variables in Postman:** - API Secret: Add your unique API key to the environment variables. - Client ID: Add your unique Client ID key to the environment variables. - Endpoint: Set up the sandbox or production URL. ## Need Help? If you encounter any issues or have questions: - **Contact Support:** [help@pay3.money](mailto\:help@pay3.money) *** [title] Get Webhook [path] Pay3 API Documentation/ This API returns the current configured webhook for your payment notifications at Pay3's end. :::ApiMethodV2 ```json { "name": "Get Webhook", "method": "GET", "url": "https://your-hostname.pay3.app/v1/client/webhook-url", "description": "Get balance for a Client ID", "tab": "examples", "examples": { "languages": [ { "id": "R_kjEOVWrgdjXK9y79KWL", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/client/fiat/webhook-url' \\\n--header 'access-token: ACCESS-TOKEN-IN-JWT'\n--header 'client-id: YOUR-CLIENT-ID'", "customLabel": "" } ], "selectedLanguageId": "R_kjEOVWrgdjXK9y79KWL" }, "results": { "languages": [ { "id": "-WPelU7C1GJ3RYSstvFCO", "language": "200", "customLabel": "", "code": "{\n \"webhookUrl\": \"your-webhook-endpoint\"\n}" }, { "id": "nV086WqVdYra6yxpqPFIt", "language": "400", "customLabel": "", "code": "{\n \"error\": {\n \"code\": \"400\",\n \"message\": \"Could not verify the client\"\n }\n}" } ], "selectedLanguageId": "nV086WqVdYra6yxpqPFIt" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired.", "children": [] }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client id. Application's Identifier", "": "Client id. Application's Identifier" } ], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Header Parameter", "value": "headerParameters" }, "hasTryItOut": false, "autoGeneratedAnchorSlug": "get-webhook", "legacyHash": "HyIBWDa61Nu8ecXMmt_0E" } ``` ::: *** [title] Get Balance [path] Pay3 API Documentation/ This API returns balance for accounts configured for checkout and payout transactions. A list of balance objects is returned are for a given Client ID. If for a given currency, there are multiple partners configured based on payment methods, the response will contain balances for those multiple partners. :::ApiMethodV2 ```json { "name": "Get Balance", "method": "GET", "url": "https://your-hostname.pay3.app/v1/client/fiat/balance", "description": "Get balance for a Client ID", "tab": "examples", "examples": { "languages": [ { "id": "R_kjEOVWrgdjXK9y79KWL", "language": "curl", "code": "curl --location 'https://your-hostname.pay3.app/v1/client/fiat/balance?clientId=YOUR-CLIENT-ID' \\\n--header 'access-token: ACCESS-TOKEN-IN-JWT'", "customLabel": "" } ], "selectedLanguageId": "R_kjEOVWrgdjXK9y79KWL" }, "results": { "languages": [ { "id": "-WPelU7C1GJ3RYSstvFCO", "language": "200", "customLabel": "", "code": "{\n \"balances\": [\n {\n \"currencyId\": \"brl_bz\",\n \"currency\": \"BRL\",\n \"balance\": \"6348.22\",\n \"partner\": \"partnerId\"\n }\n ]\n}" }, { "id": "nV086WqVdYra6yxpqPFIt", "language": "400", "customLabel": "", "code": "{\n \"error\": {\n \"code\": \"400\",\n \"message\": \"Could not verify the client\"\n }\n}" } ], "selectedLanguageId": "-WPelU7C1GJ3RYSstvFCO" }, "request": { "pathParameters": [], "queryParameters": [ { "name": "clientId", "kind": "required", "type": "string", "description": "Client ID", "children": [] } ], "headerParameters": [ { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired.", "children": [] } ], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Query Parameter", "value": "queryParameters" }, "hasTryItOut": false, "autoGeneratedAnchorSlug": "get-balance", "legacyHash": "ScY8BfqTc_CgJdpVCQO3Y" } ``` ::: *** [title] Execute Fiat Settlement - Submit Invoice [path] Pay3 API Documentation/ This API is used to submit invoice details for a specific fiat order and subsequently trigger the settlement process. This API is required only for certain geographies or currencies where merchants must submit invoice details for each order to comply with local regulatory and compliance requirements. Whether invoice submission is required for your integration will be communicated by the Pay3 team during the integration process. This API requires access token that can be generated using [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA) API. :::ApiMethodV2 ```json { "name": "Fiat Settlement - Submit Invoice", "method": "POST", "url": "https://your-hostname.pay3.app/client/fiat-settlement/submit-invoice", "description": "Submit an Invoice for any fiat order using the same requestId which was used during the order creation.", "tab": "examples", "examples": { "languages": [ { "id": "nyfSHp7J-NrsuqTH3FW7t", "language": "curl", "code": "curl --location 'https://api.pprod.pay3.app/v1/client/fiat-settlement/submit-invoice' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--header 'access-token: eyJraWQiOiIxYmI5NjA1YzM2ZVRCWkJMOH' \\\n--data '{\n \"requestId\": \"2544743810\",\n \"clientId\": \"82e024d1-8e43-4252-88d4-f3222e4f113b\",\n \"countryOfOrigin\": \"USA\",\n \"importerName\": \"John\",\n \"importerAddress\": {\n \"address\": \"321 Elm Street, Suite 3\",\n \"country\": \"USA\",\n \"city\": \"Los Angeles, CA\",\n \"pinCode\": \"90401\"\n },\n \"billerName\": \"Pay3\",\n \"billerAddress\": {\n \"address\": \"123 Space Center Blvd\",\n \"country\": \"USA\",\n \"city\": \"Houston\",\n \"pinCode\": \"77058\"\n },\n \"invoiceDate\": \"2027-01-01\",\n \"orderSno\": \"123123\",\n \"invoiceTotal\": \"400.00\",\n \"invoiceNumber\": \"234234\",\n \"items\": [\n {\n \"itemDescription\": \"Shoes\",\n \"price\": \"250.00\",\n \"quantity\": \"1\",\n \"taxPercentage\": \"0\",\n \"taxAmount\": \"0.00\",\n \"itemTotalPrice\": \"250.00\"\n },\n {\n \"itemDescription\": \"Watch\",\n \"price\": \"150.00\",\n \"quantity\": \"1\",\n \"taxPercentage\": \"0\",\n \"taxAmount\": \"0.00\",\n \"itemTotalPrice\": \"150.00\"\n }\n ]\n}'", "customLabel": "" } ], "selectedLanguageId": "nyfSHp7J-NrsuqTH3FW7t" }, "results": { "languages": [ { "id": "VQyRchSR38UbBEhATUpjh", "language": "200", "code": "{\n \"id\": \"237690bb-f311-4a3e-9fbe-d36711ad5bfa\",\n \"status\": \"REVIEW_QUEUED\",\n \"requestMetadata\": {\n \"clientId\": \"82e024d1-8e43-4252-88d4-f3222e4f113b\",\n \"requestId\": \"2544743810\",\n \"countryOfOrigin\": \"USA\",\n \"importerName\": \"John\",\n \"importerAddress\": {\n \"address\": \"321 Elm Street, Suite 3\",\n \"city\": \"Los Angeles, CA\",\n \"country\": \"USA\",\n \"pinCode\": \"90401\"\n },\n \"billerName\": \"Pay3\",\n \"billerAddress\": {\n \"address\": \"123 Space Center Blvd\",\n \"city\": \"Houston\",\n \"country\": \"USA\",\n \"pinCode\": \"77058\"\n },\n \"invoiceDate\": \"2027-01-01\",\n \"invoiceTotal\": \"400.00\",\n \"orderSno\": \"123123\",\n \"invoiceNumber\": \"234234\",\n \"items\": [\n {\n \"itemDescription\": \"Shoes\",\n \"hsCode\": null,\n \"price\": \"250.00\",\n \"quantity\": \"1\",\n \"taxPercentage\": \"0\",\n \"taxAmount\": \"0.00\",\n \"itemTotalPrice\": \"250.00\"\n },\n {\n \"itemDescription\": \"Watch\",\n \"hsCode\": null,\n \"price\": \"150.00\",\n \"quantity\": \"1\",\n \"taxPercentage\": \"0\",\n \"taxAmount\": \"0.00\",\n \"itemTotalPrice\": \"150.00\"\n }\n ]\n },\n \"createdTs\": \"2026-07-08T10:42:51.307292+00:00\",\n \"updatedTs\": \"2026-07-08T10:42:51.307292+00:00\"\n}", "customLabel": "" }, { "id": "tIvoQbUSKGnrqallvNDVQ", "language": "401", "code": "{\n \"code\": \"7001\",\n \"error\": {\n \"code\": \"500\",\n \"message\": \"No route found for subscription\"\n }\n}\n\n{\n \"code\": \"7001\",\n \"error\": {\n \"code\": \"500\",\n \"message\": \"Invalid value for interval: DAILY1\"\n }\n}", "customLabel": "" } ], "selectedLanguageId": "VQyRchSR38UbBEhATUpjh" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired", "children": [] } ], "bodyDataParameters": [ { "name": "requestId", "kind": "required", "type": "string", "description": "Identifier that is created by Application's backend. This will be passed in relevant events and webhooks from Pay3 to Application", "": "Identifier that is created by Application's backend. This will be passed in relevant events and webhooks from Pay3 to Application" }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client id. Application's identifier", "": "required" }, { "name": "countryOfOrigin", "kind": "required", "type": "string", "description": "This parameter accepts a string for Country of origin.", "": "required" }, { "name": "importerName", "kind": "required", "type": "string", "description": "Name of the importer/end user.\n", "": "required" }, { "name": "importerAddress", "kind": "required", "type": "object", "description": "Address of the importer/end user. This object accepts following params:-\n", "": "required", "children": [ { "name": "address", "kind": "optional", "type": "string", "description": "" }, { "name": "country", "kind": "optional", "type": "string", "description": "" }, { "name": "city", "kind": "optional", "type": "string", "description": "" }, { "name": "pinCode", "kind": "optional", "type": "string", "description": "" } ], "schema": [ { "name": "address", "kind": "optional", "type": "string", "description": "" }, { "name": "country", "kind": "optional", "type": "string", "description": "" }, { "name": "city", "kind": "optional", "type": "string", "description": "" }, { "name": "pinCode", "kind": "optional", "type": "string", "description": "" } ] }, { "name": "billerName", "kind": "required", "type": "string", "description": "Name of the Merchant. Eg :- \"ABC Private Limited\"", "": "required" }, { "name": "billerAddress", "kind": "required", "type": "object", "description": "Address of the Merchant. This object accepts following params :- ", "": "required", "children": [ { "name": "address", "kind": "optional", "type": "string", "description": "" }, { "name": "country", "kind": "optional", "type": "string", "description": "" }, { "name": "city", "kind": "optional", "type": "string", "description": "" }, { "name": "pinCode", "kind": "optional", "type": "string", "description": "" } ], "schema": [ { "name": "address", "kind": "optional", "type": "string", "description": "" }, { "name": "country", "kind": "optional", "type": "string", "description": "" }, { "name": "city", "kind": "optional", "type": "string", "description": "" }, { "name": "pinCode", "kind": "optional", "type": "string", "description": "" } ] }, { "name": "invoiceDate", "kind": "required", "type": "string", "description": "Date of the invoice", "": "required" }, { "name": "invoiceTotal", "kind": "required", "type": "integer", "description": "This parameter is the sum of all the \"itemTotalPrice\" from the \"items\" object.", "": "required" }, { "name": "orderSno", "kind": "required", "type": "string", "description": "Order Serial number.", "": "required" }, { "name": "invoiceNumber", "kind": "required", "type": "string", "description": "The invoice number of the order.", "": "required" }, { "name": "items", "kind": "required", "type": "object", "description": "This parameter accepts array of objects. Using this multiple details can be submitted for different item. \nEach object inside this accepts following parameters :- \n", "": "This parameter accepts array of objects. Using this multiple details can be submitted for different item. \nEach object inside this accepts following parameters :- \n", "children": [ { "name": "itemDescription", "kind": "optional", "type": "string", "description": "Small Description of the item. Eg :- \"shoes\" , \"watch\" etc." }, { "name": "price", "kind": "optional", "type": "integer", "description": "Price of the Item." }, { "name": "quantity", "kind": "optional", "type": "integer", "description": "Quantity of the item." }, { "name": "taxPercentage", "kind": "optional", "type": "string", "description": "Tax percentage applicable on the item." }, { "name": "taxAmount", "kind": "optional", "type": "integer", "description": "Calculated tax amount as per the \"taxPercentage\"." }, { "name": "itemTotalPrice", "kind": "optional", "type": "integer", "description": "Total Price of the item inclusive of tax." } ], "schema": [ { "name": "itemDescription", "kind": "optional", "type": "string", "description": "Small Description of the item. Eg :- \"shoes\" , \"watch\" etc." }, { "name": "price", "kind": "optional", "type": "integer", "description": "Price of the Item." }, { "name": "quantity", "kind": "optional", "type": "integer", "description": "Quantity of the item." }, { "name": "taxPercentage", "kind": "optional", "type": "string", "description": "Tax percentage applicable on the item." }, { "name": "taxAmount", "kind": "optional", "type": "integer", "description": "Calculated tax amount as per the \"taxPercentage\"." }, { "name": "itemTotalPrice", "kind": "optional", "type": "integer", "description": "Total Price of the item inclusive of tax." } ] } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "hasTryItOut": false, "autoGeneratedAnchorSlug": "fiat-settlement-submit-invoice", "legacyHash": "706EUjTSNEFgKfL4kKq4S" } ``` ::: *** [title] SDK Errors [path] / 008.5Pay3 SDK provides error states that can be access from the Application. # Initialisation Errors | Code | Message | Description | | ---- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 1001 | Failed to initialize | Error connecting with services while initializing the client-side wallet. Make sure the clientId is enabled and configured. | | 1002 | Domain not whitelisted | To enable the wallet in a new domain, please contact us. | | 1003 | Not initialized | This error can happen when the application uses SDK components and features before initialization. | # Transaction Errors | Code | Message | Description | | -------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 7001 | Unable to fetch buy offer | Error fetching suitable offer while initialising the transaction. This can happen if the amount doesn't match limit checks, payment method and country not supported. | | | | | | 9002 | No route found for checkout | Currently there is no partner supporting the selected payment method. | | | | | | 9003 | Payment Cancelled | Payment cancelled during the checkout process. | | | | | | 9004 | Failure with partner | Error occurred while the payment was processed by the payment partner. | | 9004.1 | Failure with partner | User limit exceeded. | | 9004.2 | Failure with partner | Error trying to validate tax ID document. | | 9004.3 | Failure with partner | Invalid transaction ID. | | 9004.4 | Failure with partner | Transaction is invalid. | | | | | | 9005 | Payment Declined | Downstream payment partner declined the transaction. | | 9005.1 | Payment Declined | TaxID doesn’t exist. | | 9005.2 | Payment Declined | CPF query for minors blocked in compliance with the General Data Protection Law - LGPD. | | 9005.3 | Payment Declined | TaxID pending regularisation. | | 9005.4 | Payment Declined | TaxID suspended. | | 9005.5 | Payment Declined | TaxID canceled by local authority. | | 9005.6 | Payment Declined | Impeached TaxID. | | 9005.7 | Payment Declined | Transaction declined for unknown reason. | | 9005.8 | Payment Declined | Payment rejected by risk analysis. | | 9005.9 | Payment Declined | Unauthorized. Invalid security code. | | 9005.10 | Payment Declined | Unauthorized. Restricted card. | | 9005.11 | Payment Declined | Unauthorized. Card expired. | | 9005.12 | Payment Declined | Unauthorized. The card does not belong to the payment network. | | 9005.13 | Payment Declined | Unauthorized. Check the situation of the store with the issuer. | | 9005.14 | Payment Declined | There is an issue with this card. Please contact the issuer. | | 9005.15 | Payment Declined | Transaction not authorized. Please try again. | | 9005.16 | Payment Declined | Invalid/Incorrect Destination Account. | | 9005.17 | Payment Declined | Insufficient funds in Payout account. | | 9005.18 | Payment Declined | User payment declined due to source account mismatch. | | 9005.19 | Payment Declined | Missing Destination Account. | | 9005.20 | Payment Declined | No Payin prior to Payout. | | 9005.21 | Payment Declined | Payment was not completed on time. | | 9005.22 | Payment Declined | Transaction failed at processor end due to risk control.Please try using a different payment method/card. | | 9005.23 | Payment Declined | Account is invalid or not active. | | 9005.24 | Payment Declined | User information entered is invalid. | | 9005.25 | Payment Declined | System is busy, please try again later. | | 9005.26 | Payment Declined | Request timed out. | | 9005.27 | Payment Declined | Unknown error. | | 9005.28 | Payment Declined | The signature verify failed. | | 9005.29 | Payment Declined | Invalid merchant. | | 9005.30 | Payment Declined | Invalid merchant APP. | | 9005.31 | Payment Declined | Invalid parameter - input parameter field length does not meet the requirement. | | 9005.32 | Payment Declined | Amount is incorrect. | | 9005.33 | Payment Declined | Invalid country, please refer to Supported Country/Region and Currency. | | 9005.34 | Payment Declined | Invalid currency, please refer to Supported Country/Region and Currency. | | 9005.35 | Payment Declined | Invalid contract, please check contract validity. | | 9005.36 | Payment Declined | The payment method does not exist; please change to other payment methods. | | 9005.37 | Payment Declined | The payment method is temporarily unavailable; please change to another payment method. | | 9005.38 | Payment Declined | Maximum amount limit. | | 9005.39 | Payment Declined | Amount limit. | | 9005.40 | Payment Declined | Duplicate order. | | 9005.41 | Payment Declined | The merchant is not onboarded; please complete merchant onboarding | | 9005.42 | Payment Declined | Payment is being processed; please try again later. | | 9005.43 | Payment Declined | Invalid ledger participant. | | 9005.44 | Payment Declined | Order closed. | | 9005.45 | Payment Declined | Insufficient Balance. | | 9005.46 | Payment Declined | OTP verification exceeds limit. | | 9005.47 | Payment Declined | OTP verification failed. | | 9005.48 | Payment Declined | Verification times exceeded. | | 9005.49 | Payment Declined | Barcode refresh limit. | | 9005.50 | Payment Declined | Barcode refresh failed. | | 9005.51 | Payment Declined | Invalid card number. | | 9005.52 | Payment Declined | Invalid card number validity period. | | 9005.53 | Payment Declined | Invalid cardholder name. | | 9005.54 | Payment Declined | Invalid CVV. | | 9005.55 | Payment Declined | Unsupported card. | | 9005.56 | Payment Declined | Invalid phone number. | | 9005.57 | Payment Declined | Invalid UPI. | | 9005.58 | Payment Declined | Pin verification exceeds limit. | | 9005.59 | Payment Declined | Invalid PIN. | | 9005.60 | Payment Declined | Invalid bank card number. | | 9005.61 | Payment Declined | Invalid ID number. | | 9005.62 | Payment Declined | Invalid Email. | | 9005.63 | Payment Declined | Invalid document. | | 9005.64 | Payment Declined | Invalid TC Kimlik No. | | 9005.65 | Payment Declined | Invalid date format. | | 9005.66 | Payment Declined | Invalid payee name. | | 9005.67 | Payment Declined | Invalid remark. | | 9005.68 | Payment Declined | Invalid CNIC. | | 9005.69 | Payment Declined | Payment Failed. | | 9005.70 | Payment Declined | Account locked/frozen. | | 9005.71 | Payment Declined | User canceled third-party payment. | | 9005.72 | Payment Declined | Your payment was declined due to authentication failure. Please try using a different card or contact your issuer for more detail. | | 9005.73 | Payment Declined | Authorization expired. | | 9005.74 | Payment Declined | Authorization failed or does not exist. | | 9005.75 | Payment Declined | Merchant blacklist blocking. | | 9005.76 | Payment Declined | Request rejected by third party. | | 9005.77 | Payment Declined | The order does not exist. | | 9005.78 | Payment Declined | Refund failed; the payment method does not support refund. | | 9005.79 | Payment Declined | Invalid refund order number. | | 9005.80 | Payment Declined | The customer bank account has been closed. | | 9005.81 | Payment Declined | The country of the business address provided does not match the account country. | | 9005.82 | Payment Declined | Account country change requires additional steps. | | 9005.83 | Payment Declined | Some account information mismatches with one another. | | 9005.84 | Payment Declined | The bank account number provided is invalid. | | 9005.85 | Payment Declined | The specified amount is greater than the minimum amount allowed | | 9005.86 | Payment Declined | The specified amount is less than the minimum amount allowed | | 9005.87 | Payment Declined | The bank account provided cannot be used to charge. | | 9005.88 | Payment Declined | The customer account cannot be used with the payment method | | 9005.89 | Payment Declined | This card has been declined too many times. | | 9005.90 | Payment Declined | The customer account has insufficient funds to cover this payment. | | 9005.91 | Payment Declined | An error occurred when processing the card. | | 9005.92 | Payment Declined | Too many requests hit the API too quickly. | | 9005.93 | Payment Declined | The bank routing number provided is invalid. | | 9005.94 | Payment Declined | The shipping address information cannot be used to accurately determine tax rates. | | 9005.95 | Payment Declined | Customer's payment instrument is inactive. | | 9005.96 | Payment Declined | Customer's payment instrument was blocked by the network | | 9005.97 | Payment Declined | Request session is timed out. Kindly retry after sometime. | | 9005.98 | Payment Declined | A network infrastructure error was detected | | 9005.99 | Payment Declined | Transaction declined due to invalid issuer. | | 9005.100 | Payment Declined | Transaction failed due to host timeout. | | 9005.101 | Payment Declined | There is some temporary issue from the bank side. | | 9005.102 | Payment Declined | Transaction failed due to system error. | | 9005.103 | Payment Declined | System error was detected at payment processor end | | 9005.104 | Payment Declined | Transaction failed due to unknown error. | | 9005.105 | Payment Declined | Problem occurred while getting terminal | | 9005.106 | Payment Declined | Transaction failed due to acquirer not participating. | | 9005.107 | Payment Declined | Transaction failed due to invalid card type. | | 9005.108 | Payment Declined | The server encountered an unexpected error while processing the request. | | 9005.109 | Payment Declined | Transaction rejected at NPCI. Please contact the acquirer. | | 9005.110 | Payment Declined | There is some network issue from the bank side. | | 9005.111 | Payment Declined | Invalid card status for the provided card details. | | 9005.112 | Payment Declined | Transaction declined because service is not available. | | 9005.113 | Payment Declined | Issuer bank did not respond on time. | | 9005.114 | Payment Declined | Issuer bank or payment service provider declined the transaction. | | 9005.115 | Payment Declined | Payment service provider declined the transaction | | 9005.116 | Payment Declined | Customer has exceeded the withdrawal amount limit. | | 9005.117 | Payment Declined | Card is restricted or not valid. | | 9005.118 | Payment Declined | Transaction declined because of violation of law. | | 9005.119 | Payment Declined | Transaction is not captured. | | 9005.120 | Payment Declined | Transaction failed due to various reasons (invalid mpin, user connectivity issue). | | 9005.121 | Payment Declined | Transaction declined because of suspected fraud. | | 9005.122 | Payment Declined | User has exceeded daily limit of transferring funds. | | 9005.123 | Payment Declined | Transaction declined because of blocked account. | | 9005.124 | Payment Declined | Transaction failed as the authentication failed at bank end. | | 9005.125 | Payment Declined | The request the client made is incorrect or corrupt. | | 9005.126 | Payment Declined | Bank unable to authorize the transaction. | | 9005.127 | Payment Declined | Customer has exceeded the withdrawal count limit. | | 9005.128 | Payment Declined | Transaction declined as the session got expired for this transaction. | | 9005.129 | Payment Declined | Transaction declined due to risk. | | 9005.130 | Payment Declined | Customer account is closed. | | 9005.131 | Payment Declined | Transaction declined as the card is expired or incorrect expiry date. | | 9005.132 | Payment Declined | Transaction not permitted to cardholder. | | 9005.133 | Payment Declined | Amount exceeded the authorized merchant limit. | | 9005.134 | Payment Declined | Inactive card or card not authorized for card not present transaction. | | 9005.135 | Payment Declined | Transaction not permitted to cardholder. | | 9005.136 | Payment Declined | Customer has exceeded the withdrawal frequency limit. | | 9005.137 | Payment Declined | Transaction declined because of blocked account/card. | | 9005.138 | Payment Declined | Transaction daily limit exceeded. | | 9005.139 | Payment Declined | This transaction has been declined/canceled by the user. | | 9005.140 | Payment Declined | Transaction exceeds credit card limit. | | 9005.141 | Payment Declined | PSP/Bank server downtime. Kindly retry after sometime. | | 9005.142 | Payment Declined | User is not authorized to perform this action. Reach out to issuer bank. | | 9005.143 | Payment Declined | Transaction declined because it exceeds risk threshold. | | 9005.144 | Payment Declined | Customer entered incorrect card number details. | | 9005.145 | Payment Declined | Retry the transaction. | | 9005.146 | Payment Declined | This PSP is not allowed to initiate this payment. | | 9005.147 | Payment Declined | Transaction amount limit exceeded. | | 9005.148 | Payment Declined | Some of the details related to the transaction are missing. | | 9005.149 | Payment Declined | Transaction is not allowed by bank. | | 9005.150 | Payment Declined | PSP server downtime. Kindly retry after sometime. | | 9005.151 | Payment Declined | User's phone number is not registered to the bank. | | 9005.152 | Payment Declined | Invalid Request. | | 9005.153 | Payment Declined | Transaction cost or currency not supplied. | | 9005.154 | Payment Declined | Cart ID not set. | | 9005.155 | Payment Declined | Invalid store ID. | | 9005.156 | Payment Declined | Invalid transaction mode. | | 9005.157 | Payment Declined | Card expiry not supplied. | | 9005.158 | Payment Declined | Card start date not supplied. | | 9005.159 | Payment Declined | Card issue number not supplied. | | 9005.160 | Payment Declined | Card number not supplied. | | 9005.161 | Payment Declined | Invalid card security code (CVV). | | 9005.162 | Payment Declined | Card security code (CVV) not supplied. | | 9005.163 | Payment Declined | Name not valid/not supplied. | | 9005.164 | Payment Declined | Address not valid/not supplied. | | 9005.165 | Payment Declined | Country not valid/not supplied. | | 9005.166 | Payment Declined | IP address not valid/not supplied. | | 9005.167 | Payment Declined | Card/Currency/Class combination not supported. | | 9005.168 | Payment Declined | Invalid transaction reference. | | 9005.169 | Payment Declined | Amount differs from original. | | 9005.170 | Payment Declined | Currency differs from original. | | 9005.171 | Payment Declined | Original transaction not authorised. | | 9005.172 | Payment Declined | Original transaction already voided. | | 9005.173 | Payment Declined | Original transaction mismatch. | | 9005.174 | Payment Declined | Invalid start date. | | 9005.175 | Payment Declined | Card details differ from original. | | 9005.176 | Payment Declined | Not authorised. | | 9005.177 | Payment Declined | Original transaction cannot be voided. | | 9005.178 | Payment Declined | Cancelled. | | 9005.179 | Payment Declined | No response. | | 9005.180 | Payment Declined | Unable to refund. | | 9005.181 | Payment Declined | Previous transaction is on hold. | | 9005.182 | Payment Declined | Invalid transaction class. | | 9005.183 | Payment Declined | Invalid transaction type. | | 9005.184 | Payment Declined | Email not valid/not supplied. | | 9005.185 | Payment Declined | Phone number not valid/not supplied. | | 9005.186 | Payment Declined | Transaction mode differs from original. | | 9005.187 | Payment Declined | 3DSecure authentication not available for this card. | | 9005.188 | Payment Declined | 3DSecure authentication rejected. | | 9005.189 | Payment Declined | Description not set. | | 9005.190 | Payment Declined | Sold Out. | | 9005.191 | Payment Declined | Card is for ATM use only. | | 9005.192 | Payment Declined | Invalid transaction Method. | | 9005.193 | Payment Declined | Transaction part not specified. | | 9005.194 | Payment Declined | Unable to access transaction part. | | 9005.195 | Payment Declined | Error connecting to service provider. | | 9005.196 | Payment Declined | Request aborted. | | 9005.197 | Payment Declined | Verification failed. | | 9005.198 | Payment Declined | Refer to card issuer. | | 9005.199 | Payment Declined | Do not honor. | | 9005.200 | Payment Declined | Address verification (AVS) mismatch. | | 9005.201 | Payment Declined | Card security code (CVV) and address (AVS) mismatch. | | 9005.202 | Payment Declined | Card is not enabled for e-commerce. | | 9005.203 | Payment Declined | Card cancelled. | | 9005.204 | Payment Declined | No/invalid account. | | 9005.205 | Payment Declined | Invalid Terminal configurations. | | 9005.206 | Payment Declined | Invalid value for split parameter. | | 9005.207 | Payment Declined | Split payment not enabled for the store. | | 9005.208 | Payment Declined | Card token validation failed. | | 9005.209 | Payment Declined | STCPay order creation falied. | | 9005.210 | Payment Declined | Paypal order creation falied. | | 9005.211 | Payment Declined | Problem with Cybersource configurations. | | 9005.212 | Payment Declined | Anti-fraud pre-auth. | | 9005.213 | Payment Declined | Anti-fraud post-auth. | | 9005.214 | Payment Declined | Card limits exceeded. | | 9005.215 | Payment Declined | Terminal limits. | | 9005.216 | Payment Declined | Fraud deteted by the acquirer. | | 9005.217 | Payment Declined | Multiple email used with the same card. | | 9005.218 | Payment Declined | Internal system error. | | 9005.219 | Payment Declined | Invalid end date. | | 9005.220 | Payment Declined | Limit value should be less than or equal to 4000. | | 9005.221 | Payment Declined | The date range exceeds seven days. | | 9005.222 | Payment Declined | Invalid or less parameters in URL. | | 9005.223 | Payment Declined | From date can not be grater than to date. | | 9005.224 | Payment Declined | Transaction is already captured. | | 9005.225 | Payment Declined | Invalid path parameter. | | 9005.226 | Payment Declined | Acquirer system error. | | 9005.227 | Payment Declined | Invalid issuer. | | 9005.228 | Payment Declined | Restricted. | | 9005.229 | Payment Declined | Closed card/account. | | 9005.230 | Payment Declined | Authorisation revoked. | | 9005.231 | Payment Declined | Fraud suspected by issuer. | | 9005.232 | Payment Declined | Fraud suspected by scheme. | | 9005.233 | Payment Declined | Scheme lifecycle/policy. | | 9005.234 | Payment Declined | Unable to route. | | 9005.235 | Payment Declined | OTP Limit exceeded. | | 9005.236 | Payment Declined | Already paid. | | 9005.237 | Payment Declined | Payment expired. | | 9005.238 | Payment Declined | Coupon expired or invalid – cannot apply to subscription. | | 9005.239 | Payment Declined | Payment mandate invalid or expired – re-auth needed. | | 9005.240 | Payment Declined | Invoice locked/finalized – cannot modify. | | 9005.241 | Payment Declined | Payment requires customer authentication (3DS/SCA). | | 9005.242 | Payment Declined | Authentication required – ask user to complete 3DS or update payment method | | 9005.243 | Payment Declined | Payment declined – ask user to try another card or update default payment method | | 9005.244 | Payment Declined | Bank account blocked – ask user to add another account or payment method | | 9005.245 | Payment Declined | Payment method not available – ask user to select another method | | 9005.246 | Payment Declined | Authentication failed – ask user to retry or update payment method | | 9005.247 | Payment Declined | Payment attempt failed – ask user to retry or change method | | 9005.248 | Payment Declined | Payment expired – ask user to retry or update payment method | | 9005.249 | Payment Declined | Card expired – ask user to update card or provide a new one"). | | 9005.250 | Payment Declined | Card declined – ask user to try another card. | | 9005.251 | Payment Declined | Address mismatch – ask user to correct billing address. | | 9005.252 | Payment Declined | Invalid CVC – ask user to re-enter or use a different card. | | 9005.253 | Payment Declined | Invalid card number – ask user to correct it. | | 9005.254 | Payment Declined | Postal code mismatch – ask user to correct ZIP. | | 9005.255 | Payment Declined | Invalid CVC – ask user to correct or use another card. | | 9005.256 | Payment Declined | Invalid expiry month – ask user to update details. | | 9005.257 | Payment Declined | Invalid expiry year – ask user to update details. | | 9005.258 | Payment Declined | Invalid field format. | | 9005.259 | Payment Declined | Invalid mandatory field. | | 9005.260 | Payment Declined | Unauthorized. | | 9005.261 | Payment Declined | Feature not allowed. | | 9005.262 | Payment Declined | Invalid transaction status. | | 9005.263 | Payment Declined | Invalid routing. | | 9005.264 | Payment Declined | Bank not supported. | | 9005.265 | Payment Declined | Invalid Card/Account/Virtual Account/Customer info. | | 9005.266 | Payment Declined | Bill blocked or not found. | | 9005.267 | Payment Declined | Bill expired. | | 9005.268 | Payment Declined | Invalid Product ID. | | 9005.269 | Payment Declined | Invalid Transaction Invoice. | | 9005.270 | Payment Declined | Invalid Seller Or Acquiring Bank Code. | | 9005.271 | Payment Declined | Invalid amount. | | 9005.272 | Payment Declined | Invalid Buyer Account. | | 9005.273 | Payment Declined | Invalid Bank | | 9005.274 | Payment Declined | Invalid Seller Exchange Or Seller. | | 9005.275 | Payment Declined | Maximum Transaction Limit Exceeded. | | 9005.276 | Payment Declined | Invalid Seller for Merchant Specific Limit | | 9005.277 | Payment Declined | Transaction Not Permitted | | 9005.278
| Payment Declined | Transaction To Merchant Not Permitted | | 9005.279 | Payment Declined | Invalid Buyer Name Or Buyer ID | | 9005.280 | Payment Declined | Blocked Bank | | 9005.281 | Payment Declined | Invalid Transaction setup. | | 9005.282 | Payment Declined | Cardholder is not enrolled in 3D Secure | | 9005.283 | Payment Declined | Transaction retry limit exceeded | | 9005.284 | Payment Declined | Authentication is not currently available | | | | | | 9006.1 | Refund Failed | There was an issue with Refund transaction. | | 9006.2 | Refund Failed | Invalid Refund Amount | | 9006.3 | Refund Failed | Invalid Refund Parent Order | | 9006.4 | Refund Failed | Refund needs to be completed manually by the bank. | | 9006.5 | Refund Failed | Currently refund cannot be processed, please reach out to client experience. | | | | | | 9007 | Under Paid | Crypto amount received is less than expected order amount. | | | | | | 9008.1 | Settlement Failed | Settlement can't be processed for the given order. | | 9008.2 | Settlement Under Review | Review details are already submitted | | 9008.3 | Settlement Failed | Invalid request id | | 9008.4 | Settlement Under Review | Retry limit reached | | 9008.5 | Settlement Under Review | Processing issue | | 9008.6 | Settlement Under Review | System error | | 9008.7 | Settlement Under Review | Confirmation timeout
| *** [title] Pay3 Webhooks [path] / As an order progresses through it's lifecycle, Pay3 shares webhook events with the App's backend about the status of order and other relevant details. This page explains different status and the information related to the webhook. This page also explains how a App can consume the events towards the end of this page. ## API Signature The application needs to share an API endpoint to which Pay3 service will be sending a webhook as a POST request with a payload which contains webhook data. Below is an example curl of how Pay3 service will be calling the provided webhook endpoint with the data. The API needs to respond back with http status code **200 **on receiving the data. The server side will retry sending the data 10 times. ```curl curl --location 'https://your-host-webhookserver.com/sample-webhook-path' \ --header 'Content-Type: application/json' -X POST \ --data '{ "payload": "eyJhbGciOiJIUzM4NCJ9.eyJvcmRlclR5cGUiOiJGSUFUIiwib3JkZXJJZCI6IjdhZWQwNjRiLWNiMmQtNDJmOC05NTYwLTc3NDEzZGNjNWZjNCIsIm9yZGVyU3RhdHVzIjoiQ09NUExFVEVEIiwib2ZmZXJJZCI6IjMzMGNkNGJiLTE4YTUtNGVkZC1hMWY0LWNkMzczMzU2ZGEwOCJ9.DmIg6ontoWke1hEGVV62gDDNKlT9L3fcRQRWemnLqjf565pH28L3_Nr7_b1C2KTp" }' ``` ## Sample Payload Below is an example payload which is received in the webhook events provided by Pay3 ```javascript { "requestId": "ed821e55-7084-467c-9e3f-4279e4d39c97" "data": { "orderType": "CHECKOUT", "orderId": "9c4dd5b3-64de-4d94-b696-3e92cd6b12ba", "orderStatus": "COMPLETED" "walletAddress": "0x..." }, "type": "pay3-sdk-transaction-status" } ``` ### Payload Schema 1. `data` : Following keys are present in this object. 1. `orderType`: Indicates the type of order for which the event is sent for. If the given order contains a crypto transaction as well as fiat transaction, two events of different order types will be sent for the same orderId. 1. CHECKOUT - Payment done by user using Fiat currency 2. PAYOUT - Withdraw Fiat request done by user 3. CRYPTO - Payment done by user using Crypto currency 2. `orderId`: It provides a unique identification of the order which is managed by Pay3. 3. `orderStatus`: It indicates the various status in which an order can be. Details about different kind of statuses can be find below ([Order Status](docId\:kw6rKJoQsYoUftKUvgyhq)). 4. `paymentStatus`: It indicates the payment status of the order. Details about different kind of payment statuses can be find below ([Payment Status](docId\:kw6rKJoQsYoUftKUvgyhq)) 5. `walletAddress`: It shows the wallet address assigned to the order. 2. `error` (Type Object, Optional): Following keys will be present if there is an error. Please refer to [SDK Errors](docId\:upvtC67WkwGNCSCjVAQ0v) for reference 1. `code` (Type number): Error code. 2. `message` (Type string): Error message. 3. `requestId` : Request Id that was passed by App while initialising the modal. 4. `type` : Type of the event. 1\. For all Order status / Payment Status changes, the type will be **pay3-sdk-transaction-status**. Refer [Status Reference](docId\:kw6rKJoQsYoUftKUvgyhq) for all order and payment status details. ## Usage of Webhooks functionality The payload of webhooks is in the form of Json Web Tokens (JWT). These tokens can be decoded using a secret to retrieve the status for a given order. This secret will be shared by Pay3 team. Sample code to decode data : ```javascript const jwt = require('jsonwebtoken'); let inputData = 'eyJhbGciOiJIUzM4NCJ9.eyJvcmRlclR5cGUiOiJGSUFUIiwib3JkZXJJZCI6IjdhZWQwNjRiLWNiMmQtNDJmOC05NTYwLTc3NDEzZGNjNWZjNCIsIm9yZGVyU3RhdHVzIjoiQ09NUExFVEVEIiwib2ZmZXJJZCI6IjMzMGNkNGJiLTE4YTUtNGVkZC1hMWY0LWNkMzczMzU2ZGEwOCJ9.DmIg6ontoWke1hEGVV62gDDNKlT9L3fcRQRWemnLqjf565pH28L3_Nr7_b1C2KTp'; let secret = 'YOUR_CLIENT_SECRET'; let decodedData = jwt.verify(data, secret); ``` Some of our downstream partners don't provide with all the statuses , in those cases some events might be skipped. But COMPLETED / FAILED will always be the terminal events. *** [title] Create Fiat Checkout Order [path] Pay3 API Documentation/ This API creates a payin order to enable users to make checkout transactions. It accepts amount and currency details. On creating an order a dynamic `token` is returned from this api which is required to be passed to Pay3 SDK This api requires access token that can be generated using [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA) API. :::ApiMethodV2 ```json { "name": "Create Checkout Order", "method": "POST", "url": "https://your-hostname.pay3.app/v1/client/checkout/create-order", "description": "Create an order with payin details from application's backend", "tab": "examples", "examples": { "languages": [ { "id": "nyfSHp7J-NrsuqTH3FW7t", "language": "curl", "code": "curl --location 'https://api.prod.pay3.app/v1/client/checkout/create-order' \\\n--header 'signature: {{signature}}' \\\n--header 'access-token: eyJraWQiOiIxYmI5NjA1YzM2ZVRCWkJMOHllMDRmcjBkcEo2OTM4NjgzMDIwMmIyZCIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIxY2VjOGM3YS1kNjMzLTQzMDUtYmJkZi00N2M3ZWJlYWU1YmEiLCJpc3MiOiJodHRwczovL3M4ZXFtbWE5ZDguZXhlY3V0ZS1hcGkudXMtZWFzdC0xLmFtYXpvbmF3cy5jb20vcHJvZC92MS91c2VyLW1hbmFnZW1lbnQvLndlbGwta25vd24vandrcy5qc29uIiwiaWF0IjoxNzU2NDU2MTgxLCJleHAiOjE3NTY0NTc5ODF9.mzRmTnht4TsGUQpV5P_QfNdlODyq12ootG_hmb5NelsfpOjIiPMk2xz9rrIqtvQG3uVxvZXdRl5VjKsi9HbIkcaj543fUBjTEsumFnYGaVbbRXCVki_TUanWYZPi4GCJs7JD7VA35AfWbiEC0spYGn9quxhyiEHu9n5u0_05kf11GeDa99HNCHGSxKxYY0aOFGWcdoietZIGHIZjQqERzMnmR8ehuSzzt7_ulD2Vrpj8oowRvDbHLboKICKalNQUzgROTWUQRPFmRRb5yREpiCFfjEyuJzjtEwuNqh5M2oEGZwuTBzaXOSdZda7uhMp7hFh5lm5WhVMz6HR_k8GNdw' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"currencyId\": \"usd_usa\",\n \"fiatAmount\": \"10.00\",\n \"paymentMethodId\": \"all\",\n \"email\": \"user@email.com\",\n \"clientId\": \"4894a422-1209-4371-9961-7e60008ec3e1\",\n \"requestId\": \"889938983\",\n \"mode\": \"returnUrl\",\n \"callbackUrl\": \"https://www.google.com\"\n}'", "customLabel": "" } ], "selectedLanguageId": "nyfSHp7J-NrsuqTH3FW7t" }, "results": { "languages": [ { "id": "VQyRchSR38UbBEhATUpjh", "language": "200", "code": "{\n \"requestId\": \"9824649238\",\n \"token\": \"a35dc551-9fb4-491c-9f9b-44d9c2ef4b32\",\n \"status\": \"CREATED\",\n \"offerInfoData\": {\n \"userAddress\": \"user@email.com\",\n \"clientId\": \"your-client-id\",\n \"selectedPaymentMethod\": \"your-paymentMethodId\",\n \"totalFiatAmount\": \"10.00\",\n \"expiryTs\": \"2025-04-21T16:12:09.287975+00:00\",\n \"currencyId\": \"your-currency-id\",\n \"type\": \"BUY\"\n }\n}", "customLabel": "" }, { "id": "tIvoQbUSKGnrqallvNDVQ", "language": "401", "code": "{\n error: {\n code: '7001',\n message: 'Order already exists for given requestId'\n }\n}", "customLabel": "" } ], "selectedLanguageId": "VQyRchSR38UbBEhATUpjh" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [ { "name": "signature", "kind": "required", "type": "string", "description": "Signature generated with sha256 followed by base64 encoding. Check below section for more details", "children": [] }, { "name": "access-token", "kind": "required", "type": "string", "description": "Access token received from Access token API. You can reuse the access token across multiple API calls till it is expired", "children": [] } ], "bodyDataParameters": [ { "name": "currencyId", "kind": "required", "type": "string", "description": "This will be provided by Pay3 during onboarding", "": "This will be provided by Pay3 during onboarding" }, { "name": "fiatAmount", "kind": "required", "type": "string", "description": "Amount user have to Pay in string format. Maximum two decimal places are allowed", "": "Amount user have to Pay in string format. Maximum two decimal places are allowed" }, { "name": "email", "kind": "required", "type": "string", "description": "User email to identify the user, which will be available in reporting dashboard", "": "required" }, { "name": "requestId", "kind": "required", "type": "string", "description": "Identifier that is created by client application's backend. This will be passed in relevant events and webhooks from Pay3 to Application. It is required to be globally unique example UUID.", "": "Identifier that is created by client application's backend. This will be passed in relevant events and webhooks from Pay3 to Application. It is required to be globally unique example UUID." }, { "name": "clientId", "kind": "required", "type": "string", "description": "Client id. Application's identifier", "children": [] }, { "name": "paymentMethodId", "kind": "optional", "type": "string", "description": "Unique string identifier. This will be provided by Pay3 during onboarding ", "": "optional" }, { "name": "userId", "kind": "optional", "type": "string", "description": "It is a type of UUID. It will used as unique identifier of the user. If this is not passed, email will be used as a unique identifier of the user within Pay3.", "": "It is a type of UUID. It will used as unique identifier of the user. If this is not passed, email will be used as a unique identifier of the user within Pay3." }, { "name": "userMessage", "kind": "optional", "type": "string", "description": "Short meaningful name of the asset user is about to purchase. ", "": "Short meaningful name of the asset user is about to purchase. " }, { "name": "firstName", "kind": "optional", "type": "string", "description": "First name of the user with maximum length of 50 characters.", "": "First name of the user with maximum length of 50 characters." }, { "name": "lastName", "kind": "optional", "type": "string", "description": "Last name of the user with maximum length of 50 characters.", "": "Last name of the user with maximum length of 50 characters." }, { "name": "phoneNumber", "kind": "optional", "type": "string", "description": "This is the phone number of the user in E.164 format [+][country code][number including area code] which can have a maximum of fifteen digits.", "": "This is the phone number of the user in E.164 format [+][country code][number including area code] which can have a maximum of fifteen digits." }, { "name": "mode", "kind": "optional", "type": "string", "description": "returnUrl - In this mode, the API returns a Pay3 payment URL that can be embedded directly into the client’s application. This is useful when the client wants to open the Pay3 URL inside a WKWebView (iOS), WebView (Android/React Native), or an