Making Payouts
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 29 days ago