The API allows us to upload a list of payee details in a file (.xls or .xlsx or .csv or .xml(pain.001 format)) and name verification check will be done against each row provided.
Account details have to be uploaded using this template to do name verification or JSON request payload.
The .xml file in pain.001 format can be uploaded to do name verification, and the verification results will be provided in the pain.002 format.
The data in the file will undergo a validation check prior to name verification check.
The files with no validation failures will be processed further for confirmation of payee details.
If the file has validation failures, it will not be processed.
In case the request body is invalid, the error will be reported in the API response.
Unique Id sent by the requester for every request in UUID4 format for cross reference purpose.
Request Body for multipart/form-data
Attribute
Type
Condition
Description
Content type
File
.xls or .xlsx or .csv
Mandatory
The payee details have to be uploaded using this template
Multipart/form-data
(OR)
Request Body Application/JSON
Attribute
Type
Condition
Description
types
String
Mandatory
Account verifications can be performed based on various parameters. Describes whether the verification is done based on the name or identifier. The types of check available on an account depends on the capability of the account verification service responder.
idScheme
String
Mandatory
Specifies the account identification scheme code like IBAN
id
String
Mandatory
A number or alphanumeric string that is used in conjunction with ID scheme
name
String
Optional
Payee's account name as specified by the payer.
secondaryId
String
Optional
Secondary reference for the account
holdingEntity
Object
Mandatory
The entity that holds the account like BICFI. 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.
identities
Object
Mandatory
Unique identifiers of an entity (typically an organisation - but, can be a person as well) represented as identification-type/identification-type-value pair format.
type
enum
Mandatory
This field represents that entity type that must be used in conjunction with identity type value to identify the holding entity. Example: COID
value
enum
Mandatory
This field represents that entity type value that must be used in conjunction with identity type to identify the holding entity. Example: "12345"
Response Headers
Attribute
Condition
Description
Transaction-XRef-Id
Mandatory
Unique Id sent by the requester for every request in UUID4 format for cross reference purpose
Retry-After
Optional/Mandatory in some error cases
Seconds after which a new request can be sent
Response Body
200 OK (Success Response)
Attribute
Type
Condition
Description
id
String
Mandatory
A unique id is generated for every bulk uploaded
message
String
Mandatory
This message will let us know whether the upload of bulk is successful
status
String
Mandatory
Status to show the request status "PENDING OR COMPLETE"
400 (Error Response)
Attribute
Type
Condition
Description
errorCode
enum
Mandatory
Low level textual error code, example INVALID_FIELD
message
String
Mandatory
A description of the error that occurred.
path
String
Optional
Recommended but optional reference to the JSON Path of the field with error, e.g., data.verification.type
url
String
Optional
URL to help remediate the problem, or provide more information, or to API Reference, or help etc
# Success Response for files with no validation failuresHTTP/1.1 200 Verification is pending
Content-Type: application/json;charset=utf-8
{"data":{"bulkResult":{"id":"1741005996LMd",
"xRefId":"63976a74-2dd2-47bd-8050-e6f7b8950fe0",
"message":"Verification is pending.",
"status":"PENDING"},
"result":[]}}
Failure Responses:
Failure Response for files with validation failures
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}"}]}
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}"}]}
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}"}]}
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 requests received",
"errors":[{"errorCode":"TOO_MANY_REQUESTS",
"message":"The client has sent too many requests in a short period of time",
"url":"https://{banfico.portal.error.descriptions}"}]}