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

This API creates a payout order to enable users to withdraw funds. 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 [pay3Pay.openPayout()](docId\:Wr9g8-0vvAo95lsm3g1ye) 

This api requires access token that can be generated using [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA) API.

**Note**: Actual response may change based on partner integration.

:::ApiMethodV2
```json
{
  "name": "Create Fiat Payout Order",
  "method": "POST",
  "url": "https://your-hostname.pay3.app/v1/client/payout/create-order",
  "description": "Create an order with payout details from application's backend",
  "tab": "examples",
  "examples": {
    "languages": [
      {
        "id": "eXhyHL9RWXfgU_lG6oq1Q",
        "language": "curl",
        "code": "curl --location 'https://your-hostname.pay3.app/v1/client/payout/create-order' \\\n--header 'signature': \"generated-signature\"\\\n--header 'access-token' : \"dynamic-access-token\" \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--data '{\n    \"currencyId\": \"currency-id\",\n    \"fiatAmount\": \"0.02\",\n    \"requestId\": \"9824649238\",\n    \"paymentMethodId\": \"payment-method-id\",\n    \"email\": \"user@address.com\",\n    \"clientId\": \"your-client-id\",\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"taxId\": \"tax-id\"\n}'",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "eXhyHL9RWXfgU_lG6oq1Q"
  },
  "results": {
    "languages": [
      {
        "id": "VQyRchSR38UbBEhATUpjh",
        "language": "200",
        "code": "{\n    \"requestId\": \"3966274f-f8b2-4992-9313-56962699b2fa\",\n    \"token\": \"f52d592a-a67a-4037-b8a2-8b7020332c6d\",\n    \"url\": null,\n    \"warning\": \"The payout account balance (999999999992444999.55) is below the configured threshold (999999999992549599.55).\",\n    \"verificationDetails\": {\n        \"isVerificationEnabled\": true,\n        \"isVerified\": true,\n        \"fullName\": \"John Doe\",\n        \"accountNumber\": \"xxxxxx8292\",\n        \"bankName\": \"Bank BRI\",\n        \"message\": \"Account verified\"\n        \"fullName\": \"John Doe\",\n        \"pixKey\": \"user@address.com\"\n    }\n}\n",
        "customLabel": ""
      },
      {
        "id": "66DvgM2SsFyRRj4NnmNJ1",
        "language": "400",
        "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 Application's backend. This will be passed in relevant events and webhooks from Pay3 to Application",
        "children": []
      },
      {
        "name": "currencyId",
        "kind": "required",
        "type": "string",
        "description": "Currency id supported in the payout flow. This will be provided by Pay3 during onboarding"
      },
      {
        "name": "fiatAmount",
        "kind": "required",
        "type": "string",
        "description": "Amount user can withdraw in string format. Maximum two decimal places are allowed",
        "children": []
      },
      {
        "name": "paymentMethodId",
        "kind": "required",
        "type": "string",
        "description": "Unique string identifier. This will be provided by Pay3 during onboarding ",
        "children": []
      },
      {
        "name": "clientId",
        "kind": "required",
        "type": "string",
        "description": "Client id. Application's identifier",
        "children": []
      },
      {
        "name": "email",
        "kind": "required",
        "type": "string",
        "description": "User email to identify the user, which will be available in reporting dashboard",
        "children": []
      },
      {
        "name": "taxId",
        "kind": "required",
        "type": "string",
        "description": "Tax ID issued to the user by their country",
        "": "required"
      },
      {
        "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": "firstName",
        "kind": "optional",
        "type": "string",
        "description": "Optional first name of the user",
        "children": []
      },
      {
        "name": "lastName",
        "kind": "optional",
        "type": "string",
        "description": "Optional last name of the user",
        "children": []
      },
      {
        "name": "pixKey",
        "kind": "optional",
        "type": "string",
        "description": "PIX Key is a unique identifier that links to a Brazilian user’s bank account and determines where the funds will be received.",
        "children": []
      },
      {
        "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.\n\ncreateVerify - In this mode, the API does not generate any website URL or UI. Instead, it returns the verification details required by the downstream partner. These fields allow the partner to verify the beneficiary and then process the payout directly based on the verified information.",
        "": "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.\n\ncreateVerify - In this mode, the API does not generate any website URL or UI. Instead, it returns the verification details required by the downstream partner. These fields allow the partner to verify the beneficiary and then process the payout directly based on the verified information."
      },
      {
        "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": "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.",
        "": "lang"
      }
    ],
    "formDataParameters": []
  },
  "currentNewParameter": {
    "label": "Body Parameter",
    "value": "bodyDataParameters"
  },
  "response": [
    {
      "name": "requestId",
      "kind": "optional",
      "type": "string",
      "description": "Identifier that is created by Application's backend. This will be passed in relevant events and webhooks from Pay3 to Application"
    },
    {
      "name": "token",
      "kind": "optional",
      "type": "string",
      "description": "A unique token returned after creating the payout/verification order. This token must be passed to the Execute API to complete the processing flow.",
      "children": []
    },
    {
      "name": "url",
      "kind": "optional",
      "type": "string",
      "description": "Returned only when the mode supports UI flow (mode = returnUrl). When no UI is required (mode = createVerify) this field will be null.",
      "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. ",
      "children": []
    },
    {
      "name": "verificationDetails",
      "kind": "optional",
      "type": "object",
      "description": "This block contains the results of the beneficiary verification process, including indicators of whether verification is required and completed, along with the validated user information returned by the downstream partner.",
      "children": [
        {
          "name": "isVerificationEnabled",
          "kind": "optional",
          "type": "boolean",
          "description": "Indicates whether verification is required for this transaction flow based on configuration or partner rules."
        },
        {
          "name": "isVerified",
          "kind": "optional",
          "type": "boolean",
          "description": "Shows whether the user’s account or payment details have been successfully verified by the downstream partner."
        },
        {
          "name": "fullName",
          "kind": "optional",
          "type": "string",
          "description": "The full verified name of the user returned by the partner."
        },
        {
          "name": "pixKey",
          "kind": "optional",
          "type": "string",
          "description": "The verified PIX key associated with the user."
        },
        {
          "name": "accountNumber",
          "kind": "optional",
          "type": "string",
          "description": "A masked version of the verified account number returned by the partner."
        },
        {
          "name": "bankName",
          "kind": "optional",
          "type": "string",
          "description": "The name of the bank with which the user’s payment account is registered."
        },
        {
          "name": "message",
          "kind": "optional",
          "type": "string",
          "description": "A partner-provided message summarizing the verification outcome (e.g., \"Account verified\")."
        }
      ]
    }
  ],
  "hasTryItOut": false,
  "autoGeneratedAnchorSlug": "create-fiat-payout-order",
  "legacyHash": "mXfLMxmKKFuBlvI3p8dgN"
}
```
:::

## Signature Generation

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

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

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

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

```

***