Handling Payins
Handle Payins
Step 1: Listen for Payin Event
You can get notified of new payins into Virtual Accounts by listening to the PAYMENT.STATUS_UPDATED
event.
PAYMENT.STATUS_UPDATED
event example
{
"id": "evt_r2pva4dgy9316az4zym031j9ln",
"event": "PAYMENT.STATUS_UPDATED",
"data": {
"id": "pmt_ka2yeb7y6d415np3jv",
"from": {
"id": "pyr_4jalpeo0epm7bkx39z",
"type": "PAYER"
},
"to": {
"id": "vac_5opkx8g1jo50lz4m3e",
"type": "VIRTUAL_ACCOUNT"
},
"direction": "PAYIN",
"reference": "Deposit from John",
"amount": "1000",
"currency": "GBP",
"paymentScheme": "FPS",
"status": "COMPLETED",
"createdAt": 1654363247796000,
"updatedAt": 1654363251739000
},
"previousValues": {
"id": "pmt_ka2yeb7y6d415np3jv",
"status": "CREATED"
},
"createdAt": 1654363251916
}
For a successful payin, you will receive an event containing the full PAYMENTS
object, including "direction": "PAYIN"
and "status": "COMPLETED"
fields. Payments with a status of COMPLETED
can be allocated to your user.
Completed payins to Virtual Accounts will result in a CREDIT
transaction being created on the associated Master Fiat Account, increasing its balance.
Compliance Review
We perform compliance checks on all payments as per regulatory requirements. Some payments may temporarily be held for a manual compliance review by our team.
In this instance, you will still receive a
PAYMENT.STATUS_UPDATED
event, but with the payment status beingCOMPLIANCE_REVIEW
. You will be able to see this payment on our system and can use this notification to inform your users of a potential delay in their payment being allocated to their account.At this point, the balance of your Master Fiat Account will not have been updated and therefore you should NOT update your user's account balance.
Once the payment has been reviewed and approved by our team you will receive another
PAYMENT.STATUS_UPDATED
webhook for the same payment, with"status": "COMPLETED"
.Now you will see your Master Fiat Account's balance will have increased and you can safely allocate the payment to your user.
Simulating Payins on Sandbox
On Sandbox, you can simulate a payin via the Dashboard by using the Add Funds options for an account.
You can also do this via the create payin endpoint, which will simulate a payin into the specified account and trigger relevant events to your webhook URL.
Step 2: Get Payer details
If you wish to perform your own checks on a payment e.g. verifying the Payer's bank account name, you can GET the details of the Payer and verify this information before you allocate the payment to your user.
GET Payer request example
curl --request GET \
--url https://sandbox.fiatrepublic.com/api/v1/payers/pyr_4jalpeo0epm7bkx39z \
--header 'Accept: application/json'
--header 'Authorization: Basic ZmlhdHJlcHVibGljOmZpYXRyZXB1YmxpYw==' \
{
"id":"pyr_4jalpeo0epm7bkx39z",
"owner":{
"type":"END_USER",
"id":"eus_2pjbyge1l2n0d9z8kl"
},
"type":"PERSON",
"name":"JOHN",
"bankDetails":{
"routingCodes":[
{
"value":"608371",
"type":"SORT_CODE"
}
],
"accountNumber":"45788726"
},
"additionalDetails":{
},
"createdAt":1653466413359,
"updatedAt":1653466413359,
"metadata":null
}
Updated about 2 months ago