---
title: Create Fiat Checkout Order
slug: create-fiat-checkout-order
docTags: 
createdAt: 2025-05-02T10:40:00.252Z
---


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 <iframe> in a web app.\n\nreturnAppUrl - In this mode, the api will return supported Android / iOS application url. This requires valid targetApp parameter in the body.",
        "": "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 <iframe> in a web app.\n\nreturnAppUrl - In this mode, the api will return supported Android / iOS application url. This requires valid targetApp parameter in the body."
      },
      {
        "name": "targetApp",
        "kind": "optional",
        "type": "string",
        "description": "This is required when the user chooses a perticular iOS/Android application to complete the payment.",
        "": "This is required when the user chooses a perticular iOS/Android application to complete the payment."
      },
      {
        "name": "deviceContext",
        "kind": "optional",
        "type": "object",
        "description": "Information about the mobile environment",
        "": "Information about the mobile environment",
        "children": [
          {
            "name": "deviceOS",
            "kind": "optional",
            "type": "string",
            "description": "ANDROID or IOS"
          }
        ],
        "schema": [
          {
            "name": "deviceOS",
            "kind": "optional",
            "type": "string",
            "description": "ANDROID or IOS"
          }
        ]
      },
      {
        "name": "pixKey",
        "kind": "optional",
        "type": "string",
        "description": "This is the unique identifier for a user in the PIX system, provided by the user. It can be an email address, phone number, CPF, or a random key.",
        "": "This is the unique identifier for a user in the PIX system, provided by the user. It can be an email address, phone number, CPF, or a random key."
      },
      {
        "name": "intlBankAccount",
        "kind": "optional",
        "type": "string",
        "description": "This is the International Bank Account Number (IBAN) entered by the user. It follows the standard IBAN format, which includes the country code, check digits, and the bank account number.",
        "": "This is the International Bank Account Number (IBAN) entered by the user. It follows the standard IBAN format, which includes the country code, check digits, and the bank account number."
      },
      {
        "name": "bankAccount",
        "kind": "optional",
        "type": "string",
        "description": "This is the bank account number entered by the user. It is specific to the user's bank and is used to identify the user's account within the financial institution.",
        "": "This is the bank account number entered by the user. It is specific to the user's bank and is used to identify the user's account within the financial institution."
      },
      {
        "name": "docType",
        "kind": "optional",
        "type": "string",
        "description": "This specifies the type of document, which for instance for Brazil is CPF (Cadastro de Pessoas Físicas). CPF is the Brazilian individual taxpayer registry identification.",
        "": "This specifies the type of document, which for instance for Brazil is CPF (Cadastro de Pessoas Físicas). CPF is the Brazilian individual taxpayer registry identification."
      },
      {
        "name": "docId",
        "kind": "optional",
        "type": "string",
        "description": "This is the Documentation ID, entered by the user. It corresponds to the specific identifier for the type of document (e.g., CPF number) provided.",
        "": "This is the Documentation ID, entered by the user. It corresponds to the specific identifier for the type of document (e.g., CPF number) provided."
      },
      {
        "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. ",
        "": "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. "
      },
      {
        "name": "lang",
        "kind": "optional",
        "type": "string",
        "description": "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.",
        "": "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."
      },
      {
        "name": "  requestDescription",
        "kind": "optional",
        "type": "string",
        "description": "This parameter accepts a string value and is used to provide a short description of the purpose of the transaction, such as \"Shoes Purchase\", \"Bill Payment\", etc.\n\nAlthough this is an optional parameter, it may be mandatory for certain geographies or currencies based on regulatory or compliance requirements. If applicable, the Pay3 team will inform you during the integration process.",
        "": "string"
      },
      {
        "name": "billingData",
        "kind": "optional",
        "type": "object",
        "description": "This parameter is an object that accepts these fields :- \n\"address\", \"street\" , \"city\" , \"state\" , \"country\" (In two letter format) , and \"postalCode\". \n\nAlthough this is an optional parameter, it may be mandatory for certain geographies or currencies based on regulatory or compliance requirements. If applicable, the Pay3 team will inform you during the integration process.",
        "": "object",
        "children": [
          {
            "name": "address",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "street",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "city",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "state",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "country",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "postalCode",
            "kind": "optional",
            "type": "string",
            "description": ""
          }
        ],
        "schema": [
          {
            "name": "address",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "street",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "city",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "state",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "country",
            "kind": "optional",
            "type": "string",
            "description": ""
          },
          {
            "name": "postalCode",
            "kind": "optional",
            "type": "string",
            "description": ""
          }
        ]
      },
      {
        "name": "metadata",
        "kind": "optional",
        "type": "object",
        "description": "This key accepts a JSON object that can be used to pass additional details for future reference in the Order Details API.\n\nFor example:\n\n{\n  \"metadata\": {\n    \"notes\": \"payment for August invoice\",\n    \"merchant_name\": \"xyz\"\n  }\n}\n",
        "": "This key accepts a JSON object that can be used to pass additional details for future reference in the Order Details API.\n\nFor example:\n\n{\n  \"metadata\": {\n    \"notes\": \"payment for August invoice\",\n    \"merchant_name\": \"xyz\"\n  }\n}\n"
      }
    ],
    "formDataParameters": []
  },
  "currentNewParameter": {
    "label": "Body Parameter",
    "value": "bodyDataParameters"
  },
  "hasTryItOut": false,
  "autoGeneratedAnchorSlug": "create-checkout-order",
  "legacyHash": "706EUjTSNEFgKfL4kKq4S"
}
```
:::

##

## Signature Generation

The request for creating checkout order requires a header `signature`. This can be generated using following code snippet.&#x20;

```javascript
const crypto = require('crypto');

// Required Parameters
const secretKey="Api-Secret-Provided-By-Pay3";
const fiatAmount =  "0.02";
const requestId = "Order-Id-Generated-By-Application";
const clientId = "your-client-id";
const accessToken = "dynamic-access-token";

const getSignature = (secretKey, fiatAmount, requestId) => {
    // Prepare the string to sign in same format. 
    // fiatAmount followed by requestId
    const stringToSign = 'fiatAmount=' + fiatAmount + '&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, fiatAmount, requestId);
```

***