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

📘

Simulainge 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
}