# 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:

# 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"
}