Fiat Payout Server-Side API

6 min

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 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 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 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.

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 .

Step 3: Call Create Fiat Payout Order 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 theisVerified flag is set to true in the response.

Sample Payload with all possible fields

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": "[email protected]", //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

{
    "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 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

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

Sample Response

{
    "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 to retrieve the latest payout details.