---
updatedAt: 2025-06-12T23:54:55.000Z
agentTools:
  projectIndex: https://docs.fiatrepublic.com/llms.txt
---

# 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**

```json PAYMENT.COMPLETED event
{
  "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.

> 📘 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](https://docs.fiatrepublic.com/reference/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](https://docs.fiatrepublic.com/reference/get-payer) and verify this information before you allocate the payment to your user.

**GET Payer request example**

```curl GET Payer Request
curl --request GET \
     --url https://sandbox.fiatrepublic.com/api/v1/payers/pyr_4jalpeo0epm7bkx39z \
     --header 'Accept: application/json' 
     --header 'Authorization: Basic ZmlhdHJlcHVibGljOmZpYXRyZXB1YmxpYw==' \
```
```json Response
{
   "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
}
```