VOP | Documentation

Verify Account Details

POST /v1.0/account-verifications

Checks the state of the account being verified and if "name" or "account identity" information provided by the requesting party matches with the details held by the PSP holding the account, the details of the account that can be verified depending on the country and capabilities of the responder. Some responders may be able to verify only the state of the account and may not verify the "name" or "account identity".

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 requestor for every request in UUID4 format for cross reference purpose.

Request Body

Attribute	Type	Condition	Description
data	Object	Mandatory
data.verification	Object	Mandatory	Data to be verified
data.verification.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 check available on an account depends on the capability of the account verification service responder.Allowed values are "STATUS", "NAME" and "ID".
data.verification.initiator	Object	Conditionally Mandatory	Information about the initiator of the account verification request
data.verification.initiator.idType	String	Conditionally Mandatory	Identification details of the account verification request is collected in identification-type/identification-value pair format. This parameter is represents the identification type. Example: ICQX, ICS, VAT
data.verification.initiator.idValue	String	Conditionally Mandatory	Identification details of the account verification request is collected in identification-type/identification-value pair format. This parameter is represents the identification type's value
data.verification.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.verification.account	Object	Mandatory	Account information used for verification.
data.verification.account.type	String	Optional	Specifies the type of account. Allowed values are "BUSINESS", "PERSONAL"
data.verification.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 case 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.E.g:<Doe,John,,Ms, ; Doe,Jane,,Ms> or <,,,Mr John Doe ; ,,,Ms Jane Doe>
data.verification.account.idScheme	String	Mandatory	Specifies the account identification scheme code. Allowed values are "IBAN", "ACNR", "CUID", "UPIC" and "SCAN"
data.verification.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 this 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 varies by the identification type
data.verification.account.secondaryId	String	Optional	Secondary reference for the account, generally used in collection accounts like credit cards and building societies. In other words sub-account number. An example of secondary reference is the roll number of a building society.
data.verification.account.holdingEntity	Object	Optional	The entity that holds the account. Typically, a bank, building society or an account holding payment services provider. Uses a entity-type/entity-type-value pair format to identify the entity
data.verification.account.identities	Array	Optional	Unique identifiers of an entity (typically an organisation - but, can be a person as well) represented as identification-type/identification-type-value pair format.
data.verification.account.holdingEntity.type	String	Mandatory	Refer to data.verification.account.holdingEntity above, This field represents that entity type that must be used in conjunction with identity type value to identify the holding entity. Example: BICFI (used in most countries), INFSC (India), USPID & USABA (USA)
data.verification.account.holdingEntity.value	String	Mandatory	Refer to data.verification.account.holdingEntity above, This field represents that 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.verification.account.identities.type	String	Mandatory	Refer to data.verification.account.identities above. Unique account identities are represented as 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), 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.verification.account.identities.value	String	Mandatory	Refer to data.verification.account.identities above. Unique account identities are represented as identity-type/identity-type-value pair format and this is the identity-type-value pair 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 requestor for every request in UUID4 format for cross reference purpose.
Responder-SLA-Seconds	Integer	Optional	Response time SLA of the responder for sending a response.
Expected-Response-Seconds	Integer	Optional	Expected response from the responder in seconds which is based on past responses.
Retry-After	Integer	Optional	Seconds after which a new request can be sent.

Response Body

Attribute	Type	Condition	Description
data	Object	Mandatory
data.result	Object	Mandatory	Verification result summary
data.result.id	String	Mandatory	Unique network reference identifier for a verification
data.result.message	String	Optional	A confirmation message sent
data.result.account	Object	Optional	Account details included in the verification results. This includes the account status and also replays some of the account information sent in the account verification request
data.result.responder	Object	Optional	Information pertaining to the responder of the account verification request and its endpoint
data.result.account.id	String	Mandatory	Account id that was included in the account verification request and replayed in the response. Refer to data.verification.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.verification.account.secondaryId
data.result.account.status	String	Mandatory	Status of the account, primarily used to determine whether the account can accept incoming payments. If the Account is an Active account, it returns ACTIVE.If account is Inactive or Dormant it returns INACTIVE.If Account has been closed it returns CLOSED. If account verification is not allowed on an account it returns FORBIDDEN and if account could not be found by responder it returns NOT_FOUND and if Responder is unable to match, it returns UNABLE_TO_MATCH status.
data.result.account.respondedName	String	Optional	Account name, as held by the responder, that is sent to the requestor, typically in case of PARTIAL_MATCH results. The decision to share the name with the requestor rests with the responder or the entity that holds the account
data.result.account.nameCheckStatus	String	Optional	Name verification status result.
data.result.account.identities	Object	Optional	Unique identifiers of an organisation, person or entity, specified by type and value that was included in the account verification request and replayed in the result
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.verification.account.identities.type
data.result.account.identities.value	String	Mandatory	Identity type value used to identify an entity that was included in the account verification request and replayed in the result data.verification.account.identities.value
data.result.responder	Object	Mandatory
data.result.responder.accountVerificationScheme	String	Mandatory	Responding account verification scheme. Example: Banfico Account Verification Scheme,COP UK, SEPAMail, etc.
data.result.responder.apiVersion	String	Optional	Api version from 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.schemeResponseCode	Array	Optional	List of verification result codes from the responder. API documentations are available here.
data.result.responder.receivedTime	String	Optional	Date and time at which the resource was received from respective scheme
data.result.responder.data	byte	Mandatory	Original response from the respective scheme as base64-encoded characters, for example, cGVwaW5pbGxvcwo=
data.result.responder.entity	Object	Optional	Entity responding to the account verification request. This could be a bank, fintech, centralised scheme operator, etc.
data.result.responder.entity.idType	String	Mandatory	Responding entity identity is represented using a id-type/id-type-value format and this is the entity id type, that must be used in conjunction with entity id type value to uniquely identify the entity
data.result.responder.entity.idValue	String	Mandatory	Responding entity identity is represented using a id-type/id-type-value format and this is the entity id type value, that must be used in conjunction with entity id type to uniquely identify the entity
data.result.responder.entity.reference	String	Optional	Unique reference provided by responder or scheme operator. API documentations are available here.

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

Example 1: Account type as PERSONAL, Scheme Name as SCAN with secondary Identification

Request

POST /v1.0/account-verifications
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "verification": {
      "types": [
        "NAME"
      ],
      "account": {
        "type": "PERSONAL",
        "idScheme": "SCAN",
        "name": "Doe, John",
        "id": "90070012345678",
        "secondaryId": "9876543210"
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "result": {
      "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
      "account": {
        "id": "90070012345678",
        "secondaryId": "9876543210",
        "status": "ACTIVE",
        "nameCheckStatus":  "FULL_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "UK_COP",
        "apiVersion": "1.0",
        "receivedTime": "2024-02-19T15:43:05.420Z",
        "data": "ewogICJkYXRhI...CiAgfQp9=",
        "entity": {
            "idType": "PARTICIPANT_ORG_ID",
            "idValue": "0015800001ZEc1XAAT",
            "reference": "YOMI701335"
        }
      }
    }
  }
}

Example 2: Account type as BUSINESS and Scheme Name as SCAN

Request

POST /v1.0/account-verifications
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "verification": {
      "types": [
        "NAME"
      ],
      "account": {
        "type": "BUSINESS",
        "idScheme": "SCAN",
        "name": "ABC Holdings Limited",
        "id": "90070098765432"
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "result": {
      "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
      "account": {
        "id": "90070098765432",
        "status": "ACTIVE",
        "nameCheckStatus":  "PARTIAL_MATCH",
        "respondedName": "ABC Holdings Limit"
      },
      "responder": {
        "accountVerificationScheme": "UK_COP",
        "apiVersion": "1.0",
        "schemeResponseCodes": [
          "MBAM"
        ],
        "receivedTime": "2024-02-19T15:43:05.420Z",
        "data": "ewogICJkYXRhI...CiAgfQp9=",
        "entity": {
            "idType": "PARTICIPANT_ORG_ID",
            "idValue": "0015800001ZEc1XAAT",
            "reference": "YOMI701335"
        }
      }
    }
  }
}

Example 3: Account type as PERSONAL and Scheme Name as IBAN

Request

POST /v1.0/account-verifications
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "verification": {
      "types": [
        "NAME"
      ],
      "account": {
        "type": "PERSONAL",
        "idScheme": "IBAN",
        "name": "Doe, John",
        "id": "GB15ABBY30000012345678"
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "result": {
      "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
      "account": {
        "id": "GB15ABBY30000012345678",
        "status": "ACTIVE",
        "nameCheckStatus":  "FULL_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "UK_COP",
        "apiVersion": "1.0",
        "receivedTime": "2024-02-19T15:43:05.420Z",
        "data": "ewogICJkYXRhI...CiAgfQp9=",
        "entity": {
            "idType": "PARTICIPANT_ORG_ID",
            "idValue": "0015800001ZEc1XAAT",
            "reference": "YOMI701335"
        }
      }
    }
  }
}

Example 4: Account type as BUSINESS and Scheme Name as IBAN

Request

POST /v1.0/account-verifications
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "verification": {
      "types": [
        "NAME"
      ],
      "account": {
        "type": "BUSINESS",
        "idScheme": "IBAN",
        "name": "ABC Holdings Limited",
        "id": "GB15ABBY30000098765432"
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "result": {
      "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
      "account": {
        "id": "GB15ABBY30000098765432",
        "status": "ACTIVE",
        "nameCheckStatus":  "FULL_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "UK_COP",
        "apiVersion": "1.0",
        "receivedTime": "2024-02-19T15:43:05.420Z",
        "data": "ewogICJkYXRhI...CiAgfQp9=",
        "entity": {
            "idType": "PARTICIPANT_ORG_ID",
            "idValue": "0015800001ZEc1XAAT",
            "reference": "YOMI701335"
        }
      }
    }
  }
}

Example 5: Unable to find the Account - Account type as PERSONAL and Scheme Name as IBAN

Request

POST /v1.0/account-verifications
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "verification": {
      "types": [
        "NAME"
      ],
      "account": {
        "type": "PERSONAL",
        "idScheme": "IBAN",
        "name": "Doe,John",
        "id": "GB15ABBY30000012340000"
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "result": {
      "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
      "account": {
        "id": "GB15ABBY30000012340000",
        "status": "NOT_FOUND",
        "nameCheckStatus": "UNABLE_TO_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "UK_COP",
        "apiVersion": "1.0",
        "schemeResponseCodes": [
          "AC01"
        ],
        "receivedTime": "2024-02-19T15:43:05.420Z",
        "data": "ewogICJkYXRhI...CiAgfQp9=",
        "entity": {
            "idType": "PARTICIPANT_ORG_ID",
            "idValue": "0015800001ZEc1XAAT",
            "reference": "YOMI701335"
        }
      }
    }
  }
}

Example 6: Payee has opted out - Account type as PERSONAL and Scheme Name as SCAN

Request

POST /v1.0/account-verifications
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Accept: application/json
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "verification": {
      "types": [
        "NAME"
      ],
      "account": {
        "type": "PERSONAL",
        "idScheme": "SCAN",
        "name": "Doe,John",
        "id": "90070012345600"
      }
    }
  }
}

Response

HTTP/1.1 200 OK
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "result": {
      "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
      "account": {
        "id": "90070012345600",
        "status": "FORBIDDEN",
        "nameCheckStatus": "UNABLE_TO_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "UK_COP",
        "apiVersion": "1.0",
        "schemeResponseCodes": [
          "OPTO"
        ],
        "receivedTime": "2024-02-19T15:43:05.420Z",
        "data": "ewogICJkYXRhI...CiAgfQp9=",
        "entity": {
            "idType": "PARTICIPANT_ORG_ID",
            "idValue": "0015800001ZEc1XAAT",
            "reference": "YOMI701335"
        }
      }
    }
  }
}

Error Examples

400

The server cannot or will not process the request.

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": "The field is invalid, unexpected value",
      "path": "data.verification.account.schemeName",
      "url": "https://{banfico.portal.error.descriptions}"
    },
    {
      "errorCode": "MISSING_FIELD",
      "message": "Must not be null",
      "path": "data.verification.account.id",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

401

Authentication is required and has failed or has not yet been provided.

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": "MISSING_SIGNATURE",
      "message": "Missing signature",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

403

The server is refusing action, may be due the user not have the proper permissions to access the resource.

HTTP/1.1 403 Forbidden
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

The requested resource could not be found

HTTP/1.1 403 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

The server timed out waiting for the request.

HTTP/1.1 408 Request Timeout
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": "CoP Responder time out",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

421

The request was directed at a server that is not able to produce a response

HTTP/1.1 421 Misdirected Request
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

The user has sent too many requests in a given amount of time

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
Retry-After: 10

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

A generic error message, given when an unexpected condition was encountered in the server

HTTP/1.1 500 Internal Server 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}"
    }
  ]
}

503

The server cannot handle the request because it is down or overloaded

HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8
Transaction-XRef-Id: 12345678901234567890
Retry-After: 10

{
  "id": "3e6e4d1c-9af9-42cd-8ec9-e2a136a56940",
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service unavailable",
  "errors": [
    {
      "errorCode": "SERVICE_UNAVAILABLE",
      "message": "Service currently unavailable, Please try after sometime or contact technical support",
      "url": "https://{banfico.portal.error.descriptions}"
    }
  ]
}

Fetch Result using ID

GET/v1.0/account-verifications/{id}

This API is used to check the response of an account verification request using the unique network reference identification.

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 requestor for every request in UUID4 format for cross reference purpose.

Response Body

Attribute	Type	Condition	Description
data	Object	Mandatory
data.result	Object	Mandatory	Verification result summary
data.result.id	String	Mandatory	Unique network reference identifier for a verification
data.result.message	String	Optional	A confirmation message sent
data.result.account	Object	Optional	Account details included in the verification results. This includes the account status and also replays some of the account information sent in the account verification request
data.result.responder	Object	Optional	Information pertaining to the responder of the account verification request and its endpoint
data.result.account.id	String	Mandatory	Account id that was included in the account verification request and replayed in the response. Refer to data.verification.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.verification.account.secondaryId
data.result.account. status	String	Mandatory	Status of the account, primarily used to determine whether the account can accept incoming payments. If the Account is an Active account, it returns ACTIVE.If account is Inactive or Dormant it returns INACTIVE.If Account has been closed it returns CLOSED. If account verification is not allowed on an account it returns FORBIDDEN and if account could not be found by responder it returns NOT_FOUND and if Responder is unable to match, it returns UNABLE_TO_MATCH status.
data.result.account. respondedName	String	Optional	Account name, as held by the responder, that is sent to the requestor, typically in case of PARTIAL_MATCH results. The decision to share the name with the requestor rests with the responder or the entity that holds the account
data.result.account. nameCheckStatus	String	Optional	Name verification status result.
data.result.account. identities	Object	Optional	Unique identifiers of an organisation, person or entity, specified by type and value that was included in the account verification request and replayed in the result
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.verification.account.identities.type
data.result.account. identities.value	String	Mandatory	Identity type value used to identify an entity that was included in the account verification request and replayed in the result data.verification.account.identities.value
data.result.responder	Object	Mandatory
data.result.responder. accountVerificationScheme	String	Mandatory	Responding account verification scheme. Example: Banfico Account Verification Scheme,COP UK, SEPAMail, etc.
data.result.responder. apiVersion	String	Optional	Api version from 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. schemeResponseCode	Array	Optional	List of verification result codes from the responder. API documentations are available here.
data.result.responder. receivedTime	String	Optional	Date and time at which the resource was received from respective scheme
data.result.responder. data	byte	Mandatory	Original response from the respective scheme as base64-encoded characters, for example, cGVwaW5pbGxvcwo=
data.result.responder. entity	Object	Optional	Entity responding to the account verification request. This could be a bank, fintech, centralised scheme operator, etc.
data.result.responder. entity.idType	String	Mandatory	Responding entity identity is represented using a id-type/id-type-value format and this is the entity id type, that must be used in conjunction with entity id type value to uniquely identify the entity
data.result.responder. entity.idValue	String	Mandatory	Responding entity identity is represented using a id-type/id-type-value format and this is the entity id type value, that must be used in conjunction with entity id type to uniquely identify the entity
data.result.responder. entity.reference	String	Optional	Unique reference provided by responder or scheme operator. API documentations are available here.

Response Codes

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

Example 1: Personal Account May be a Match, Scheme Name as SCAN

Request

GET /v1.0/account-verifications/{id}
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
content-type: application/json

Response

HTTP/1.1 200 OK
Transaction-XRef-Id: 93bac548d2de4546b106
Content-Type: application/json

{
  "data": {
    "result": {
      "id": "AFRH44994",
      "message": "The account type is Personal Account",
      "account": {
        "id": "90070011100029",
        "status": "ACTIVE",
        "respondedName": "Susan Clark",
        "nameCheckStatus": "PARTIAL_MATCH"
      },
      "responder": {
        "accountVerificationScheme": "UK_COP",
        "apiVersion": "2.0.0",
        "receivedTime": "2024-06-24T15:13:16.505162Z",
        "data": "ewogICJEYXRhIiA6IHsKICAgICJWZXJpZmljYXRpb25SZXBvcnQiIDogewogICAgICAiTWF0Y2hlZCIgOiBmYWxzZSwKICAgICAgIlJlYXNvbkNvZGUiIDogIlBBTU0iLAogICAgICAiTmFtZSIgOiAiU3VzYW4gQ2xhcmsiCiAgICB9CiAgfSwKICAiTGlua3MiIDogewogICAgIlNlbGYiIDogIi9wYXkudWsvdjIuMC9jb25maXJtYXRpb24tcGF5ZWUvbmFtZS12ZXJpZmljYXRpb24iCiAgfSwKICAiTWV0YSIgOiB7IH0KfQ==",
        "schemeResponseCodes": [
          "PAMM"
        ],
        "entity": {
          "idType": "PARTICIPANT_ORG_ID",
          "idValue": "001580000103UBAAC2"
        }
      }
    }
  }
}

Getting Started

Internal Developer

External Developer

Verify Account Details

Request Headers

Request Body

Response Headers

Response Body

Response Codes

Example 1: Account type as PERSONAL, Scheme Name as SCAN with secondary Identification

Request

Response

Example 2: Account type as BUSINESS and Scheme Name as SCAN

Request

Response

Example 3: Account type as PERSONAL and Scheme Name as IBAN

Request

Response

Example 4: Account type as BUSINESS and Scheme Name as IBAN

Request

Response

Example 5: Unable to find the Account - Account type as PERSONAL and Scheme Name as IBAN

Request

Response

Example 6: Payee has opted out - Account type as PERSONAL and Scheme Name as SCAN

Request

Response

Error Examples

Fetch Result using ID

Request Headers

Response Body

Response Codes

Example 1: Personal Account May be a Match, Scheme Name as SCAN

Request

Response