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.

Initiate Account Verification Check

Endpoint:

POST /account-verifications

Purpose:

• Verify that a beneficiary account's name and account details (IBAN) match.

• Reduce failed payouts/refunds and compliance risks by confirming account ownership.

Request Body Example (EUR Account):

{
  "account": {
    "name": "John Doe",
    "iban": "GB33BUKB20201555555555",
    "currency": "EUR"
  },
  "virtualAccountId": "pa:8DbPteGnytmMbKXdnWTReeRB6cYWKXZ84JgLTBC7fKL4:5zKcENpV"
}

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.

Response Examples:

Full Match:

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

Close Match:

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

No Match:

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

Verification not possible:

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

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.

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.

Payouts

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

Sample Request

{
  "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"
    }
  }
}

Refunds

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

Sample Request

{
  "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"
    }
  }
}

Workflow Summary

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.

Sandbox Testing

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

If you have any feedback about the developer documentation, please contact devdocs@token.io