# Integration Guide

## Overview

The Account Verification API introduces a new endpoint and updates existing payout and refund endpoints. It allows Third Party Providers (TPPs) to perform account verification and provide evidence of VoP validation for euro-zone based accounts.

br
## Initiate Account Verification Check

**Endpoint**:


```
POST /account-verifications
```

br
**Purpose:**

- Verify that a beneficiary account's name and account details (IBAN) match.
- Reduce failed payouts/refunds and compliance risks by confirming account ownership.


br
**Request Body Example (EUR Account):**

br
**Settlement Account Use Case (for Payout and Refunds)**


```json
{
  "account": {
    "name": "Isabelle Marie Dubois",
    "iban": "FR9317569000707197247234A34",
    "currency": "EUR"
  },
  "virtualAccountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
}
```

br
**Payment Initiation for non-settlement account use case (requires contractual agreement)**


```json
{
  "account": {
    "name": "Isabelle Marie Dubois",
    "iban": "FR9317569000707197247234A34",
    "currency": "EUR"
  }
}
```

br
**Possible Status Values:**

- **MATCH**: Full match confirmed.
- **CLOSE_MATCH**: Partial match (e.g., slight name mismatch).
- **NO_MATCH**: Account details and name do not match.
- **VERIFICATION_NOT_POSSIBLE**: Unable to complete the check due to non response from underlying bank.


br
**Response Examples:**

br
**Full Match:**


```json
{
  "id": "avr-01K7H6CPPPAZ6JR456E9YRSJ2D",
  "result": {
    "status": "MATCH",
    "reason": ["EXACT_MATCH"],
    "details": "The account details match."
  }
}
```

br
**Close Match:**


```json
{
  "id": "VOP0000001",
  "result": {
    "status": "CLOSE_MATCH",
    "reason": [
      "NAME_MISMATCH"
    ],
    "details": "The name provided is a close match.",
    "matched": {
      "name": "H. C. Andersen"
    }
  }
}
```

br
**No Match:**


```json
{
  "id": "VOP0000001",
  "result": {
    "status": "NO_MATCH",
    "reason": [
      "ACCOUNT_MISMATCH",
      "NAME_MISMATCH"
    ],
    "details": "The account and name do not match."
  }
}
```

br
**Verification not possible:**


```json
{
  "id": "VOP0000001",
  "result": {
    "status": "VERIFICATION_NOT_POSSIBLE",
    "reason": [
      "UNKNOWN"
    ],
    "details": "The check cannot be completed."
  }
}
```

br
You should securely store the `accountVerificationId` returned from the verification check, as it serves as the reference linking a verified account to subsequent payment operations.

> **While the ID remains valid indefinitely, it is required to generate a new `accountVerificationId` for each new payout or refund to ensure the most accurate and up-to-date verification and align with VoP regulation.**


br
## Executing a Payout or Refund

- Use the updated payout and refund endpoints, including the `accountVerificationId` for EUR/IBAN-based accounts.
- The system validates the `accountVerificationId` and match status.
- Transactions with invalid IDs are rejected.
- While the field is optional, it is **strongly recommended for all Modulr-related refunds and payouts**. This position may change in the future to be more restrictive.


br
### Payouts

The payout endpoint will now include the `accountVerificationId` parameter within the `"creditor"` object.

br
**Sample Request**


```json
{
  "initiation": {
    "description": "e49j-2145-sp17-k3h0",
    "refId": "9htio4a1sp2akdr1aa",
    "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
    "amount": {
      "value": "10.23",
      "currency": "EUR"
    },
    "debtor": {
      "accountId": "a12345"
    },
    "creditor": {
      "name": "Customer Inc.",
      "ultimateCreditorName": "Customer Inc.",
      "bankName": "string",
      "iban": "GB29NWBK60161331926819",
      "bic": "BOFIIE2D",
      "accountNumber": "12345678",
      "sortCode": 123456,
      "accountVerificationId": "avr-01K7H6CPPPAZ6JR456E9YRSJ2D"
    }
  }
}
```

br
### Refunds

The payout endpoint will now include the `accountVerificationId` parameter within the `"initiation"` object.

br
**Sample Request**


```json
{
  "initiation": {
    "description": "e49j-2145-sp17-k3h0",
    "refId": "9htio4a1sp2akdr1aa",
    "amount": {
      "value": "10.23",
      "currency": "EUR"
    },
    "originalPaymentId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
    "registrationId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
    "localInstrument": "SEPA_INSTANT",
    "onBehalfOfId": "c5a863bc-86f2-4418-a26f-25b24c7983c7",
    "accountVerificationId": "avr-01K7H6CPPPAZ6JR456E9YRSJ2D",
    "corporateApiDebtor": {
      "accountId": "c5a863bc-86f2-4418-a26f-25b24c7983c7"
    }
  }
}
```

br
## Workflow Summary

| Step | Action | Outcome |
|  --- | --- | --- |
| **Initiate Account Verification Check** | Call `POST /verification` with account details | Receive `accountVerificationId` and match status |
| **Store Verification ID** | Securely store the `accountVerificationId` | Ensure ID is available for payout/refund requests |
| **Execute Payout / Refund** | Include `accountVerificationId` in requests | Validate ID and process transaction if valid |
| **Handle Exceptions** | Address failed or ambiguous verification results | Retry, escalate, or seek user confirmation |


br
## Best Practices

1. Always include the **currency** field to ensure correct matching rules.
2. Handle **partial matches (CLOSE_MATCH)** with additional manual checks before payout.
3. Log error trace IDs from error responses for debugging and support from Token.


br
## Sandbox Testing

The sandbox environment allows you to test all four verification scenarios by providing specific inputs:

br
### Match


```json
{
  "account": {
    "name": "Isabelle Marie Dubois",
    "iban": "FR9317569000707197247234A34",
    "currency": "EUR"
  },
  "virtualAccountId": "{{accountId}}" //not required for non-settlement use case
}
```

br
### Close Match


```json
{
  "account": {
    "name": "Isabelle Marie",
    "iban": "FR9317569000707197247234A34",
    "currency": "EUR"
  },
  "virtualAccountId": "{{accountId}}" //not required for non-settlement use case
}
```

br
### No Match


```json
{
  "account": {
    "name": "Jhon Nowak",
    "iban": "FR9317569000707197247234A34",
    "currency": "EUR"
  },
  "virtualAccountId": "{{accountId}}" //not required for non-settlement use case
}
```

br
### Verification Not Possible


```json
{
  "account": {
    "name": "TinTin",
    "iban": "NL19INGB2128949858",
    "currency": "EUR"
  },
  "virtualAccountId": "{{accountId}}" //not required for non-settlement use case
}
```

br
If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)