---
title: Fiat Payout Server-Side API
slug: fiat-payout-server-side-api
docTags: 
createdAt: 2025-11-05T12:30:13.684Z
---

This document explains how to create a fiat payout order and process user withdrawals using a backend-only, server-to-server API without any user interface.

The [Create Fiat Payout Order](docId\:cz-cuTNjfgEFE_EokAwiO)**  **API creates a payout order and returns the parameters required to process the withdrawal.  When **mode=**`createVerify` is passed, no website URL or UI is generated. Instead, the API response will share the required details by our downstream partner like `fullName`, `accountNumber`, `bankName`, `upiId`, `pixKey`, `message`. 

Once you receive these parameters, your backend can call the [Execute Fiat Payout Order](docId\:A3yTB3ovV03fgjWUX7XOz)  API to complete the withdrawal. This final API asyncronously submits the transaction to our downstream partner and share a status. 

Pay3 backend sends events to your backend service with real-time updates on the payout status. When you receive an event, you may call the [Get Fiat Order Details](docId\:EvzG5iQKqdzSR1_pKKNDs) API to fetch the latest payout information. 
**Note**: Refer to the `exchangeAmount` field to verify the paid sum.

## Steps

### Step 1: Get Access Token 

To generate the Access Token, you will call the API with the api-secret and client-id. Please refer to the [Access Token](docId\:lq-v6fF_2i-h1O3XD5KKA). 

### Step 2: Create a Signature with Parameters

The payout request requires a signature in the header. This can be generated using the javascript code snippet at [Fiat Payout Signature Generation](docId\:cz-cuTNjfgEFE_EokAwiO) . 

### Step 3: Call  [Create Fiat Payout Order](docId\:cz-cuTNjfgEFE_EokAwiO) API

Send the required parameters and ensure mode = `createVerify` is enabled**.**

You will have to share required fields mandated by your respective payment processor which will be shared during onboarding.  

The API creates an order and optionally checks with downstream processor with the data provided. This API will respond back with `verificationDetails`. When the downstream payment processor has mandatory verification requirement `isVerificationEnabled` flag is set to `true`. Please make sure to check the`isVerified` flag is set to `true` in the response. 

**Sample Payload with all possible fields**

```javascript
const payloadFiatPayout = {
  "currencyId": "brl_bz", // Please reach out to Pay3 team for enabled currencies in your clientId 
  "fiatAmount": "1000.00", // Fiat amount to be processed for the transaction
  "paymentMethodId": "pix", // Please reach out to Pay3 team for enabled payment methods in your clientId 
  "email": "user@example.com", //Pass the email of the user (uniqueId)
  "requestId": "...", // TODO: Application’s Order Id, send unique id for every order (preferably UUID)
  "clientId": "...", // TODO: your clientId
  "firstName": "John",
  "lastName": "Doe",
  "pixKey": "1234567890",
  "taxId": "12345678901",
  "mode": "createVerify", 
  "userId": "b418ae8f-7d1f-4c09-b32f-456abc789d12",
  "upiId": "john.doe@upi",
  "accountNumber": "123456789012",
  "bankCode": "BANK123",
  "branchCode": "BR001",
  "transferMode": "ACH",
  "callbackUrl": "https://www.example.com/callback",
  "lang": "en",
  "phoneNumber": "+1234567890",
  "userDocumentId": "doc_9876543210",
  "userDocumentType": "passport",
  "mercadoPagoUserName": "john_doe_mp",
  "address": "123 Main St, City, Country",
  "latitude": "40.712776",
  "longitude": "-74.005974",
  "userMessage": "Description."
}
```

**Sample response**

```javascript
{
    "requestId": "b8238df5-339f-4fa0-b1dd-38f432305278",
    "token": "c5fa58b3-8385-4e79-85e6-047cab79404d",
    "url": null,
    "verificationDetails": {
        "isVerificationEnabled": true,
        "isVerified": true,
        "fullName": "John Doe",
        "pixKey": "john.doe.upi"
        "accountNumber": "xxxxxx8292",
        "bankName": "Bank BRI",
        "message": "Account verified"
    }
}
```

### Step 4: Call the [Execute Fiat Payout Order](docId\:A3yTB3ovV03fgjWUX7XOz)  API.

Using the header access token, `clientId`, `token`**, **`requestId`**, **call the API. This API processes the payout and returns the final payout result.

**Sample Payload**

```javascript
const payloadFiatPayout = {
    "token":"45452aae-581d-49db-94be-ac0973e39e86",
    "requestId":"239e667a-3a54-4928-a265-09c003d7ec73",
    "clientId":"...."
}
```

**Sample Response**

```javascript
{
    "requestId": "239e667a-3a54-4928-a265-09c003d7ec73",
    "orderId": "776cd238-0d49-4a6b-b5e0-a8ca245036a2",
    "orderType": "PAYOUT",
    "status": "ORDER_PAYMENT_INITIATED"
}
```

### Step 5: Listen for Webhook Events 

Pay3 backend sends webhook notifications with status updates.
Upon receiving an event, you may call the [Get Fiat Order Details](docId\:EvzG5iQKqdzSR1_pKKNDs)  to retrieve the latest payout details.

***