CoP | Developers

Verification of Payee check - Single

POST /v1.1/account-verifications

Checks the state of the account being verified and if "Name" or "Business ID type" information provided by the requesting party matches with the details held by the PSP holding the account.

Request Headers

Attribute	Type	Condition	Description
Authorization	String	Mandatory	An Authorization token as per https://tools.ietf.org/html/rfc6750
Transaction-XRef-Id	UUID	Optional	Unique Id sent by the requester for every request in UUID4 format for cross reference purpose.

Request Body

Attribute	Type	Condition	Description
data	Object	Mandatory
data.initiator.idType	String	Conditionally Mandatory	Identification details of the account verification request is collected in identification-type/identification-value pair format. This parameter represents the identification type. Example: ICQX, ICS, VAT
data.initiator.idValue	String	Conditionally Mandatory	Identification details of the account verification request is collected in identification-type/identification-value pair format. This parameter represents the identification type's value.
data.initiator.reference	String	Conditionally Mandatory	A reference to the relationship between the verification requesting party and the party whose account is subject to the verification, as specified by the initiator and justifies the purpose of the request. Examples include invoice number, purchase order number, payroll ID, etc. Recommended format - If the reference type is "Référence Unique de Mandat"/"Unique Mandate Reference", prefix the value with "RUM-".
data.query.types	Array	Mandatory	Account verifications can be performed based on various parameters. Describes whether the verification is done based on the account status or name or identifier. The types of checks available on an account depend on the capability of the account verification service responder. Allowed values are "STATUS", "NAME" and "ID".
data.query.xRefId	String	Optional	External reference ID for tracking.
data.query.account.type	String	Optional	Specifies the type of account. Allowed values are "BUSINESS", "PERSONAL".
data.query.account.name	String(150 Chars)	Optional	Payee's account name as specified by the payer. Accepts both structured (preferred) and unstructured format. Structured Format: <LastName, FirstName, Middle Name, Honorific>. Example: <Doe,John,,Mr>. Unstructured Format: <,,,Full Name>. Example: <,,,Mr John Doe>. In the case of joint accounts, the name of any one accountholder is sufficient. However, in case of joint accounts or other scenarios that allow more than one name, each name must be separated by a ; in either of the formats. Example: <Doe,John,,Ms, ; Doe,Jane,,Ms> or <,,,Mr John Doe ; ,,,Ms Jane Doe>.
data.query.account.idScheme	String	Mandatory	Specifies the account identification scheme code. Allowed values are "IBAN", "ACNR", "CUID", "UPIC", and "SCAN".
data.query.account.id	String	Mandatory	A number or alphanumeric string that is used in conjunction with ID scheme (data.verification.account.idScheme) to uniquely identify an account. For some schemes (example: IBAN), the ID is unique across all holding entities. However, for some schemes (example: ACNR), this is unique within an entity and must be used in conjunction with the account holding entity ID (refer to data.verification.account.holdingEntity) to uniquely identify the account across all account holding entities. Maximum length and pattern/format vary by the identification type.
data.query.account.secondaryId	String	Optional	Secondary reference for the account, generally used in collection accounts like credit cards and building societies. In other words, a sub-account number. An example of a secondary reference is the roll number of a building society.
data.query.account.holdingEntity.type	String	Mandatory	The entity that holds the account. Typically, a bank, building society, or an account-holding payment services provider. Uses an entity-type/entity-type-value pair format to identify the entity. Example: BICFI (used in most countries), INFSC (India), USPID & USABA (USA).
data.query.account.holdingEntity.value	String	Mandatory	This field represents the entity type value that must be used in conjunction with identity type to identify the holding entity. Example: BNPAFRPP (BICFI value for BNP Paribas), SBIN0001115 (INFSC value for State Bank of India), 021000021 (USABA value for JPMorgan Bank).
data.query.account.identities.type	String	Mandatory	Unique account identities are represented as an identity-type/identity-type-value pair format. Some of the allowed values for identity-type for organisations include: company registration number (CRN), tax identification number (TXID), and DUNS number (DUNS). Some of the allowed values for identity-type for persons include: national identification number, social security number, tax identification number, passport number, etc.
data.query.account.identities.value	String	Mandatory	Unique account identities are represented as an identity-type/identity-type-value pair format, and this is the identity-type-value that must be used in conjunction with identity-type.

Response Headers

Attribute	Type	Condition	Description
Transaction-XRef-Id	String	Mandatory	Unique Id sent by the requester for every request in UUID4 format for cross reference purpose
Retry-After	Integer	Optional / Mandatory in some error cases	Seconds after which a new request can be sent

Response Body

Attribute	Type	Condition	Description
data	Object	Mandatory
data.result.id	String	Mandatory	Unique network reference identifier for a verification
data.result.message	String	Optional	A confirmation message sent
data.result.account.id	String	Mandatory	Account ID that was included in the account verification request and replayed in the response. Refer to data.query.account.id
data.result.account.secondaryId	String	Optional	Secondary reference of the account that was included in the account verification request and replayed in the response. Refer to data.query.account.secondaryId
data.result.account.status	String	Mandatory	Status of the account, primarily used to determine whether the account can accept incoming payments. Possible values: ACTIVE (Account is active), INACTIVE (Inactive or dormant), CLOSED (Account has been closed), FORBIDDEN (Verification not allowed), NOT_FOUND (Responder could not find the account), UNABLE_TO_MATCH (Responder was unable to match the account)
data.result.account.nameCheckStatus	String	Optional	Name verification status result
data.result.account.respondedName	String	Optional	Account name, as held by the responder, shared in PARTIAL_MATCH cases. The decision to share the name with the requestor rests with the responder or the entity that holds the account
data.result.account.identities.status	String	Mandatory	Specifies the validation status result of identity provided in the request to be validated
data.result.account.identities.type	String	Mandatory	Identity type used to identify an entity that was included in the account verification request and replayed in the result. Refer to data.query.account.identities.type
data.result.account.identities.value	String	Mandatory	Identity value used to identify an entity that was included in the account verification request and replayed in the result. Refer to data.query.account.identities.value
data.result.responder.accountVerificationScheme	String	Mandatory	Responding account verification scheme. Examples: BANFICO LTD Account Verification Scheme, COP UK, SEPAMail, EPC VOP
data.result.responder.apiVersion	String	Optional	API version used by the respective scheme
data.result.responder.urlVerificationScheme	String	Optional	URL pointed to the swagger file for the specific verification scheme to help the client parse the original response stored as base64 in data field. API documentations are available here
data.result.responder.receivedTime	String	Optional	Date and time at which the resource was received from the respective scheme
data.result.responder.data	String (base64)	Mandatory	Original verification response from the respective scheme, base64-encoded (e.g., cGVwaW5pbGxvcwo=)
data.result.responder.entity.idType	String	Mandatory	Responding entity identity is represented using an id-type/id-type-value format. This field contains the entity ID type, which must be used alongside idValue to uniquely identify the entity
data.result.responder.entity.idValue	String	Mandatory	Responding entity identity is represented using an id-type/id-type-value format. This field contains the entity ID type value, which must be used alongside idType to uniquely identify the entity
data.result.responder.entity.reference	String	Optional	Unique reference provided by the responder or scheme operator. API documentations are available here
data.result.responder.scheme-response-code.status	String	Optional	Status of the scheme response
data.result.responder.scheme-response-code.name	String	Optional	Name associated with the scheme response
data.result.responder.scheme-response-code.response-code-id.identificationType	String	Optional	Type of identification issue
data.result.responder.scheme-response-code.response-code-id.reasonCode	String	Optional	Code explaining the reason for identification failure

Response Codes

Status Code	Description
200	OK
202	Accepted
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
429	Too Many Requests
500	Internal Server Error

Success Examples

200

Example 1a. Account Name is a Full Match - Croatia IBAN

REQUEST:

{
  "data": {
    "query": {
      "types": [
        "NAME"
      ],
      "account": {
        "idScheme": "IBAN",
        "id": "ES4604879976999668582488",
        "name": "Lucía Torres",
        "holdingEntity": {
          "type": "BICFI",
          "value": "BKFCPLSBSXX"
        }
      }
    }
  }
}

RESPONSE:

{
  "data": {
    "result": {
      "id": "SJFY1650",
      "account": {
        "id": "HR9225000093477339279",
        "status": "ACTIVE",
        "nameCheckStatus": "FULL_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "EPC_VOP",
        "apiVersion": "V0.3",
        "schemeResponseCodes": [
          {
            "name": "MTCH",
            "id": []
          }
        ],
        "receivedTime": "2025-03-03T10:52:52.582718534Z",
        "data": "eyJwYXJ0eU5hbWVNYXRjaCI6Ik1UQ0gifQ==",
        "entity": {
          "idType": "BICFI",
          "idValue": "BKFCHR22H3M",
          "reference": "SJFY1650"
        }
      }
    }
  }
}

Example 1b. Account Name Partial Match - Sweden IBAN:

REQUEST:

{
  "data": {
    "query": {
      "types": [
        "NAME"
      ],
      "account": {
        "idScheme": "IBAN",
        "id": "SE7582238463247747551338",
        "name": "Russ William Methli",
        "holdingEntity": {
          "type": "BICFI",
          "value": "BKFCSE22H3M"
        }
      }
    }
  }
}

RESPONSE:

{
  "data": {
    "result": {
      "id": "RLAO1652",
      "account": {
        "id": "SE7582238463247747551338",
        "status": "ACTIVE",
        "respondedName": "Russ William Methlie",
        "nameCheckStatus": "PARTIAL_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "EPC_VOP",
        "apiVersion": "V0.3",
        "schemeResponseCodes": [
          {
            "name": "CMTC",
            "id": []
          }
        ],
        "receivedTime": "2025-03-03T10:57:04.396314321Z",
        "data": "eyJwYXJ0eU5hbWVNYXRjaCI6IkNNVEMiLCJtYXRjaGVkTmFtZSI6IlJ1c3MgV2lsbGlhbSBNZXRobGllIn0=",
        "entity": {
          "idType": "BICFI",
          "idValue": "BKFCSE22H3M",
          "reference": "RLAO1652"
        }
      }
    }
  }
}

Example 1c. Account Name is a No Match - Lithuania IBAN:

REQUEST:

{
  "data": {
    "query": {
      "types": [
        "NAME"
      ],
      "account": {
        "idScheme": "IBAN",
        "id": "LT563718222128199785",
        "name": "Michael Nichol",
        "holdingEntity": {
          "type": "BICFI",
          "value": "BKFCLT22H3M"
        }
      }
    }
  }
}

RESPONSE:

{
  "data": {
    "result": {
      "id": "GWNF1656",
      "account": {
        "id": "LT563718222128199785",
        "status": "ACTIVE",
        "nameCheckStatus": "NO_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "EPC_VOP",
        "apiVersion": "V0.3",
        "schemeResponseCodes": [
          {
            "name": "NMTC",
            "id": []
          }
        ],
        "receivedTime": "2025-03-03T11:01:01.871926119Z",
        "data": "eyJwYXJ0eU5hbWVNYXRjaCI6Ik5NVEMifQ==",
        "entity": {
          "idType": "BICFI",
          "idValue": "BKFCLT22H3M",
          "reference": "GWNF1656"
        }
      }
    }
  }
}

Example 1d. Account not found - Slovakia IBAN:

REQUEST:

{
  "data": {
    "query": {
      "types": [
        "NAME"
      ],
      "account": {
        "idScheme": "IBAN",
        "id": "SK2783422848255241582172",
        "name": "Michael Nichol",
        "holdingEntity": {
          "type": "BICFI",
          "value": "BKFCLT22H3M"
        }
      }
    }
  }
}

RESPONSE:

{
  "data": {
    "result": {
      "id": "TBRV63289",
      "account": {
        "id": "SK2783422848255241582172",
        "status": "NOT_FOUND",
        "nameCheckStatus": "UNABLE_TO_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "EPC_VOP",
        "apiVersion": "V0.3",
        "schemeResponseCodes": [
          {
            "name": "NOAP",
            "id": []
          }
        ],
        "receivedTime": "2025-03-13T09:51:49.032955749Z",
        "data": "eyJwYXJ0eU5hbWVNYXRjaCI6Ik5PQVAifQ==",
        "entity": {
          "idType": "BICFI",
          "idValue": "BKFCLT22H3M",
          "reference": "TBRV63289"
        }
      }
    }
  }
}

Error Examples

400

Invalid IBAN and scheme name:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
    "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
    "code": "BAD_REQUEST",
    "message": "The request is invalid",
    "errors": [
        {
            "errorCode": "INVALID_FIELD",
            "message": "Invalid IBAN",
            "path": "data.query.account.id",
            "url": "https://{banfico.portal.error.descriptions}"
        },
        {
            "errorCode": "MISSING_FIELD",
            "message": "Must not be null",
            "path": "data.query.account.idScheme",
            "url": "https://{banfico.portal.error.descriptions}"
        }
    ]
}

Missing name:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
    "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
    "code": "BAD_REQUEST",
    "message": "The request is invalid",
    "errors": [
        {
            "errorCode": "MISSING_FIELD",
            "message": "Name cannot be null for namechecks",
            "path": "data.query.account.name",
            "url": "https://{banfico.portal.error.descriptions}"
        }
    ]
}

Missing IBAN:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
    "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
    "code": "BAD_REQUEST",
    "message": "The request is invalid",
    "errors": [
        {
            "errorCode": "MISSING_FIELD",
            "message": "IBAN value cannot be null",
            "path": "data.query.account.id",
            "url": "https://{banfico.portal.error.descriptions}"
        }
    ]
}

Payee's bank is not a VOP participant:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
    "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
    "code": "BAD_REQUEST",
    "message": "The request is invalid",
    "errors": [
        {
            "errorCode": "NON_PARTICIPANT",
            "message": "Not a VOP participant",
            "url": "https://{banfico.portal.error.descriptions}"
        }
    ]
}

Invalid combination:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
    "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
    "code": "BAD_REQUEST",
    "message": "The request is invalid",
    "errors": [
        {
            "errorCode": "INVALID_FIELD_COMBO",
            "message": "Both name and ID cannot be provided in the same VOP request",
            "url": "https://{banfico.portal.error.descriptions}"
        }
    ]
}

Invalid header:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "BAD_REQUEST",
  "message": "The request is invalid",
  "errors": [
    {
      "errorCode": "INVALID_HEADER",
      "message": "Invalid header Transaction-XRef-Id, the server cannot process the request",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

Missing header:

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "BAD_REQUEST",
  "message": "The request is invalid",
  "errors": [
    {
      "errorCode": "MISSING_HEADER",
      "message": "Missing header Transaction-XRef-Id, the server cannot process the request",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

401:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "UNAUTHORISED",
  "message": "Unauthorized access",
  "errors": [
    {
      "errorCode": "UNAUTHORISED",
      "message": "{Unauthorised reason details}",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

403:

HTTP/1.1 403 Forbidden error
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "FORBIDDEN",
  "message": "Forbidden resource access",
  "errors": [
    {
      "errorCode": "FORBIDDEN",
      "message": "Forbidden resource access",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

404:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "NOT_FOUND",
  "message": "Resource not found",
  "errors": [
    {
      "errorCode": "NOT_FOUND",
      "message": "{not found resource reason}",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

408:

HTTP/1.1 408 Request Timeout
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "REQUEST_TIMEOUT",
  "message": "Request timeout",
  "errors": [
    {
      "errorCode": "REQUEST_TIMEOUT",
      "message": "{request timeout resource reason}",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

421:

HTTP/1.1 421 Method Not Allowed
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "METHOD_NOT_ALLOWED",
  "message": "Method is not allowed",
  "errors": [
    {
      "errorCode": "METHOD_NOT_ALLOWED",
      "message": "This endpoint doesn't currently support the account identification scheme or country where the account is held. Please contact technical support",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

429:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many request received",
  "errors": [
    {
      "errorCode": "TOO_MANY_REQUESTS",
      "message": "The client has sent too many request in short period of time",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

500:

HTTP/1.1 500 Unexpected Error
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "UNEXPECTED_ERROR",
  "message": "Unexpected error occurred",
  "errors": [
    {
      "errorCode": "UNEXPECTED_ERROR",
      "message": "The operation cannot be complete, an unexpected error occurred",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

502:

HTTP/1.1 502 Bad Gateway
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "BAD_GATEWAY",
  "message": "Bad Gateway",
  "errors": [
    {
      "errorCode": "BAD_GATEWAY",
      "message": "Bad Gateway",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

503:

HTTP/1.1 503 Service currently unavailable
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service unavailable",
  "errors": [
    {
      "errorCode": "SERVICE_UNAVAILABLE",
      "message": "VOP Responder system unavailable",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

504:

HTTP/1.1 504 VOP Responder time out
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service unavailable",
  "errors": [
    {
      "errorCode": "SERVICE_UNAVAILABLE",
      "message": "VOP Responder time out",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

Getting Started

Verification of Payee check - Single

Request Body

Response Headers

Response Body

Response Codes