link

# 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

  1. The merchant wants to verify that a specific bank account belongs to a specific person or company.
  2. The merchant sends a request to SurePay containing a bank account number and a name (see below for details).
  3. 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:

# 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"
}
Last updated: 19/10/2022 15:19 UTC