# Verification of Payee (VoP)

The Verification of Payee (VoP) API allows you to instantly verify that a creditor's name matches the provided account details (IBAN) and display the result to your PSU, e.g. when they create a new supplier card in your system. With this API, you can provide enhanced security for your PSU's financial operations by reducing the risk of fraud and misdirected payments. 

> Requests to the VoP API require an [access token](get_access_token.md) with `scope` set to `paymentinitiation` `corporate`.

##

### Submit Verification Request

To request a VoP, provide the creditor's name and IBAN. The system will then check the specified name against the registered name of the account holder and return one of four possible verification results to display to your PSU.

#### Endpoint 

```http
POST /premium/v1/payee-verifications
```

#### Request Headers 

| Name               | Type         | Description                                                                                                       |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `X-Request-ID`     | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party.                                 |
| `PSU-ID`           | string       | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. |
| `PSU-Corporate-ID` | string       | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL.        |

#### Request Body 

| Name              | Type   | Description                                        |
| ----------------- | ------ | -------------------------------------------------- |
| `party`           | object | The full name of the payment recipient.            |
| `partyAccount`    | object | The account to which the payment will be credited. |
| `partyAgent`      | object | The BIC of the payment recipient's bank.           |

```bash
curl -X POST "https://api.openbankingplatform.com/premium/v1/payee-verifications" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 36b35854-204a-445a-9f30-aae61dacbf8e" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -d '{
        "party": {
          "name": "Acme"
        },
        "partyAccount": {
          "iban": "SE4550000000058398257466"
        },
        "partyAgent": "ESSESESS"
      }'
```


#### Response

**Match**

```json
{
  "partyNameMatch": "MTCH"
}
```

**Close Match**

```json
{
  "partyNameMatch": "CMTC",
  "matchedName": "Acme AB",
  "tppMessages": [
    {
      "category": "WARNING",
      "code": "CREDITOR_NAME_CLOSE_MATCH",
      "text": "Creditor name closely matches the registered name of the account." 
    }
  ]
}
```

**No Match**

```json
{
  "partyNameMatch": "NMTC",
  "tppMessages": [ 
    {
      "category": "WARNING",
      "code": "CREDITOR_NAME_MISMATCH",
      "text": "Creditor name does not match the registered name of the account." 
    }
  ]
}
```

**Not Applicable**

```json
{
  "partyNameMatch": "NOAP",
  "tppMessages": [
    {
      "category": "WARNING",
      "code": "CREDITOR_NAME_UNVERIFIED",
      "text": "Creditor name cannot be verified for this account." 
    }
  ]
}
```

### Submit Bulk Verification Request

It is also possible to perform multiple VoPs at once by submitting a list of creditor details to verify. A `uetr` parameter containing a GUID must be provided for each creditor in the request body. The same `uetr` value is echoed back in the corresponding response object, allowing each verification result to be correlated with the original creditor.

#### Endpoint 

```http
POST /premium/v1/bulk-payee-verifications
```

#### Request Headers 

| Name               | Type         | Description                                                                                                       |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `X-Request-ID`     | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party.                                 |
| `PSU-ID`           | string       | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. |
| `PSU-Corporate-ID` | string       | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL.        |

#### Request Body 

| Name                        | Type  | Description                               |
| --------------------------- | ----- | ----------------------------------------- |
| `partyVerificationRequests` | array | The list of payment recipients to verify. |

```bash
curl -X POST "https://api.openbankingplatform.com/premium/v1/bulk-payee-verifications" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: 8255b3ad-218e-4c7d-9ac1-3e3a258f7ca0" \
  -H "PSU-ID: 199002092386" \
  -H "PSU-Corporate-ID: 5560160680" \
  -d '{
        "partyVerificationRequests": [
          {
            "uetr": "ab450982-a52d-49b6-90a7-a949535a5ca1",
            "party": {
              "name": "Acme"
            },
            "partyAccount": {
              "iban": "SE4550000000058398257466"
            },
            "partyAgent": "ESSESESS"   
          },
          {
            "uetr": "a1874514-a2ae-408c-93fc-588228876394",
            "party": {
              "name": "Company"
            },
            "partyAccount": {
              "iban": "FI2112345600000785"
            },
            "partyAgent": "NDEAFIHH"   
          },
          {
            "uetr": "4932e93d-e04b-4813-b126-49df7d321f3f",
            "party": {
              "name": "Other Company"
            },
            "partyAccount": {
              "iban": "FI4950009420002319"
            },
            "partyAgent": "OKOYFIHH"   
          }  
        ]
      }'
```

#### Response

```json
{
  "partyVerificationResponses": [
    {
      "uetr": "ab450982-a52d-49b6-90a7-a949535a5ca1",
      "partyNameMatch": "MTCH"
    },
    {
      "uetr": "a1874514-a2ae-408c-93fc-588228876394",
      "partyNameMatch": "CMTC",
      "matchedName": "Company AB",
      "tppMessages": [
        {
          "category": "WARNING",
          "code": "CREDITOR_NAME_CLOSE_MATCH",
          "text": "Creditor name closely matches the registered name of the account." 
        }
      ]
    },
    {
      "uetr": "a1874514-a2ae-408c-93fc-588228876394",
      "partyNameMatch": "NMTC",
      "tppMessages": [
        {
          "category": "WARNING",
          "code": "CREDITOR_NAME_MISMATCH",
          "text": "Creditor name does not match the registered name of the account." 
        }
      ]
    }
  ]
}
```