Guides

Making Payouts

Suggest Edits

Making Payouts

To process withdrawals for your users, you can make payouts from your Fiat Republic accounts, to the external bank accounts of your users.

📘

Currencies and Payment Schemes

You can find more information about the supported currencies and payment schemes here.

In order to make payouts, you will first need to create a Payee.

Step 1: Create a Payee for End Users

To create a new Payee using the API, you will need to use the create Payee endpoint and provide the endUserId of the user for whom you wish to create a Payee.

📘

Required Fields for Bank Details

The details required for creating a Payee will depend on the currency that you want to make payouts and receive payins in. More information on this can be seen here.

POST Payees request example

curl --request POST \
     --url https://sandbox.fiatrepublic.com/api/v1/payees \
     --header 'Content-Type: application/json' \
     --data '
{
   "endUserId":"eus_2pjbyge1l2n0d9z8kl",
   "type":"PERSON",
   "name":"John Doe",
   "currency":"GBP",
   "address":null,
   "bankDetails":{
      "routingCodes":[
         {
            "type":"SORT_CODE",
            "value":"101000"
         }
      ],
      "accountNumber":"12345678"
   },
   "additionalDetails":null,
   "metadata":null
}

{
    "id": "pye_5opkx8g1jl40lz4m3e",
    "owner": {
        "type": "END_USER",
        "id": "eus_2pjbyge1l2n0d9z8kl"
    },
    "type": "PERSON",
    "name": "John Doe",
    "currency": "GBP",
    "address": null,
    "paymentSchemes": [
        "FPS",
        "CHAPS"
    ],
    "bankDetails": {
        "routingCodes":[
         {
            "type":"SORT_CODE",
            "value":"101000"
         }
      ],
        "accountNumber": "12345678"
    },
    "additionalDetails": {},
    "createdAt": 1649937567871,
    "updatedAt": 1649937567871,
    "metadata": null,
    "status": "CREATED"
}

The response will contain a paymentSchemes field which indicates the payment schemes that can used to make a payment to this payee.

As this is an asynchronous process, the response will return a Payee object in a CREATED status. The Payee will become ACTIVE typically within a couple of seconds.

You can monitor the Payee's status using the GET Payee endpoint or by consuming the PAYEE.STATUS_UPDATED event. In practice, you can simply check the Payee status before you make the first payment to it or add a 10 second delay between creating a new Payee and creating a payment to it.


Step 2: Create a Payment

You can now create a payment from the End User's Virtual Account, to the Payee you created for them using the relevant payment scheme.

POST Payment request example

curl --request POST \
     --url https://sandbox.fiatrepublic.com/api/v1/payments \
     --header 'Content-Type: application/json' \
     --data '
{
   "from":{
      "id":"vac_5opkx8g1jo50lz4m3e",
      "type":"VIRTUAL_ACCOUNT"
   },
   "to":{
      "id":"pye_5opkx8g1jl40lz4m3e",
      "type":"PAYEE"
   },
   "reference":"Withdrawal",
   "amount":"1000",
   "paymentScheme":"FPS",
   "metadata":null
}
'

{
    "id": "pmt_8ovyep1rebx0kx65n2",
    "from": {
        "id": "vac_5opkx8g1jo50lz4m3e",
        "type": "VIRTUAL_ACCOUNT"
    },
    "to": {
        "id": "pye_5opkx8g1jl40lz4m3e",
        "type": "PAYEE"
    },
    "direction": "PAYOUT",
    "reference": "Withdrawal",
    "amount": "1000.00",
    "currency": "GBP",
    "paymentScheme": "FPS",
    "status": "CREATED",
    "createdAt": 1649952068273,
    "updatedAt": 1649952068273,
    "metadata": null
}

📘

Payments from Virtual Accounts

As with Payins, when you make a Payout from a Virtual Account the balance will be debited from the associated Master Fiat Account.

While it is possible to make the payout directly from the Master Fiat Account, it is advisable to do so from the Virtual Account so you can easily keep track of all the payments for a particular user.

Once the request has been accepted, the payment status will be set to CREATED and ultimately transition to COMPLETED.

Step 3: Listen for the Payment Status Event

You can keep track of the changes in the status of the payment via the PAYMENT.STATUS_UPDATED event. More details of on the various statuses of a Payment can be found here.

PAYMENT.STATUS_UPDATED event example

{
  "id": "evt_n5ev10g6oznm6vx5lo4azjdkl2",
  "event": "PAYMENT.STATUS_UPDATED",
  "data": {
    "id": "pmt_8ovyep1rebx0kx65n2",
    "from": {
      "id": "vac_5opkx8g1jo50lz4m3e",
      "type": "VIRTUAL_ACCOUNT"
    },
    "to": {
      "id": "pye_5opkx8g1jl40lz4m3e",
      "type": "PAYEE"
    },
    "direction": "PAYOUT",
    "reference": "Withdrawal",
    "amount": "1000.00",
    "currency": "GBP",
    "paymentScheme": "FPS",
    "status": "COMPLETED",
    "createdAt": 1649952068273000,
    "updatedAt": 1649952074395000,
    "metadata": null
  },
  "previousValues": {
    "id": "pmt_8ovyep1rebx0kx65n2",
    "status": "PROCESSING"
  },
  "createdAt": 1649952074498
}

Updated about 1 month ago