# About SurePay
SurePay is a lookup service for the Netherlands which can be used during an identity proofing process to cross-check that a specific bank account is owned by the end-user. This service can be useful in several scenarios; for example, if a company needs to make regular payments to their users' bank accounts, they may want to verify the accounts during onboarding. In this scenario, being able to confirm that the bank account provided by the user is indeed owned by them can help prevent fraud and mistakes, which in turn improves the user's experience. SurePay can also be used to check the ownership of a company's bank account.
The main advantage of using SurePay through Signicat is that, by integrating towards the Signicat Identity Platform, you will be able to use not just SurePay, but also all the other lookups, eID methods and other services offered by Signicat.
# How the SurePay microservice works
- The merchant wants to verify that a specific bank account belongs to a specific person or company.
- The merchant sends a request to SurePay containing a bank account number and a name (see below for details).
- SurePay sends a response indicating whether or not there is a match. It is also possible to get MISTYPE in a response, this means that there might be a match but there seems to be a typo e.g. the merchant sent "Thomas" in the name and there is a match with the same bank account but the name is spelled "Tomas".
# How to integrate
Integration with the service is done via the same API as Signicat’s ID methods. See Getting started with authentication for more information. Through the single point of integration, you will get access to Signicat’s wide portfolio of integrated ID methods and other services like identity proofing and registry lookups.
# How to use the SurePay microservice
This section describes how to use the SurePay microservice from the Signicat platform.
# Location
The SurePay microservice is available at:
- https://eu01.signicat.com/surepay/prc (opens new window)
- id.signicat.com/surepay/prc (opens new window)
# Method description
The SurePay microservice only has one method, which checks if a combination of an IBAN and a name matches the data in the SurePay database. It also checks that the specified IBAN is a valid IBAN and that it is found in the known list of IBANs. Both the input and the output may contain special characters. When it comes to diacritics specifically, the matching algorithm does not take them into account for matching. Name suggestions in the response will include diacritics, if applicable.
# Request method
POST
# Request headers
Header name | Mandatory | Default value | Maximum length | Description |
---|---|---|---|---|
Content-Type | yes | application/json | Supported content type. | |
Authorization | yes | Contains the access token. You do not need to generate it as it will be provided by Signicat. |
# Request body
Data element | Mandatory | Type | Maximum length | Description |
---|---|---|---|---|
name | yes | string | 70 | Name of the account holder. |
iban | yes | string | 34 | The account IBAN (must be valid). |
origin | yes | string | This field indicates if the request is being sent by Signicat or by a reseller.Possible values:SIGNICATRESELLER | |
resellerOrigin | no | string | If the value of origin is RESELLER, this field is mandatory. The field must contain the name of the company that the reseller is reselling to. | |
correlationId | no | string | If no correlation ID is specified, one will be created automatically. |
# Request example
curl -H'Authorization: Bearer eyJraWQiOiJhbnkub2lkYy50ZXN0Lmp3ay52LjEiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJnYXRsaW5nLXRlc3QiLCJzY3AiOlsiY2xpZW50LnN1cmVwYXkucHJjIl0sInNubSI6Im5iaWRtb2JpbGUiLCJpc3MiOiJodHRwczpcL1wvZGV2MDEuc2lnbmljYXQuY29tXC9vaWRjIiwiZXhwIjoxNTQ5NDYzNDkyLCJpYXQiOjE1NDk0NjE2OTIsImp0aSI6IjRsaHRQQnFEMzRUYWgyalExaXZ1UnFfcVZqSFFqeHk0IiwiY2lkIjoiZ2F0bGluZy10ZXN0In0.p9TBJRzyEGvLR4i9jqt5sMtQJN_KnaXC8TiFnVGSfA2HqineqvE3_O_LhhXCL7IlJhAbGGt791ck-laI5oK-ENL_YLAGA8ND-cFv7UTTLRvBb79OgHqvyt94h6l03HVgdBYtN8DAwFt38qUGMnHdwlVwkIxNAAGAvA1dHhh0OKIy1NKdpwm-kEi_7Id3Dfi0kOyLfvHTJwoFZzT5i-2gxl7mJVJB9CN3je1b5dFZtdJzeH18iIOpUfIpU1XnQuy7meAHG13GH9Z-P1gUcN8hcU8X61A9Th8xYQqVO0AuHbtM-j0zWo1fZ4gk_4J_nEdlNXBLuLYWtnRbPlRNKwtqCA' -H'Content-Type: application/json' --data '{"iban":"NL58ABNA0529868903","name":"Elise Bothe","origin":"SIGNICAT"}' http://localhost:9616/surepayprc
# Response headers
Header name | Default value | Description |
---|---|---|
Content-Type | application/json;charset=UTF-8 | Content type and encoding of the response. |
# Response body
Data element | Mandatory | Type | Level | Description |
---|---|---|---|---|
check | yes | + | ||
iban | yes | ++ | ||
valid | yes | boolean | +++ | True if and only if the specified IBAN has a valid format, false otherwise. |
found | yes | boolean | +++ | True if and only if the system knows the IBAN. If false, it may still be a valid account that the system does not know about. |
name | no | ++ | ||
validity | yes | enum | +++ | Indicates if the name has a valid format. Possible values:VALID: name field is validNAME_TOO_SHORT: if the name is shorter than the minimum of 3 characters or if only the first name is entered.NAME_TOO_LONG: if the name exceeds the maximum of 70 characters including spaces and punctuation marks. |
ibanNameMatching | no | + | Available only in cases where the IBAN is found and the status is not INACTIVE. | |
type | yes | enum | ++ | Indicates if there is a match. Possible values:MATCHING: the specified name matches one of the names in the SurePay database.NOT_MATCHING: the specified name does not match any of the names for that IBAN in the SurePay database.MISTYPE: the specified name is a close match with one of the names in the SurePay database. In this case, a name suggestion will also be returned. |
nameSuggestion | no | string | ++ | A name suggestion is returned in some cases:If the value of "type" is MISTYPE.If the value of "type" is NOT_MATCHING and the IBAN belongs to an organisation. In this case, the legal name of the organisation is provided.If no name was provided in the request and the IBAN belongs to an organisation. |
Account | no | + | ||
status | yes | enum | ++ | Indicates a special status of a bank account:INACTIVE: the account is not in use.If the status is unknown or active, this field will be omitted. |
foreign | yes | boolean | ++ | Indicates that an IBAN is issued by non-Dutch bank. |
countryCode | yes | string | ++ | Two-letter country code from the IBAN in ISO 3166-1 alpha-2 format. |
accountHolder | no | + | Available only if the IBAN is found and the account status is not INACTIVE. | |
type | yes | enum | ++ | Indicates the type of account holder:NP: a personal accountORG: an organizationUNKNOWN: account type is unknown |
jointAccount | no | boolean | ++ | Available only if the type is MATCHING or MISTYPE.The field will be true if there is more than one account holder. If this information is not available or if the account type is UNKNOWN, this field is not provided. |
numberOfAccountHolders | no | integer | ++ | Available only if the type is MATCHING or MISTYPE.This field contains the number of account holders. If the account type is UNKNOWN, this field is not provided. |
residence | no | ++ | ||
municipality | yes | string | +++ | Municipality of residence of the business account holder. This value isn't set if the information isn't available. Only returned for ORG type accounts. |
correlationId | yes | string | + | The correlation ID sent in the request. |
# Response example
{
"account": {
"countryCode": "NL",
"foreign": false
},
"accountholder": {
"residence": {
"municipality": "Amsterdam"
},
"type": "NP"
},
"check": {
"iban": {
"found": true,
"valid": true
},
"name": {
"validity": "VALID"
}
},
"ibanNameMatching": {
"type": "MATCHING"
},
"correlationId": "correlationId sent in request"
}