Identity verification

SurePay

345 views February 1, 2019 May 20, 2019 2

SurePay is a lookup service for the Netherlands which can be used during an identity verification 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.

If you are interested in SurePay, you should know that there are two main ways in which you can use it through the Signicat platform: as a standalone microservice or in combination with iDIN. Both options can also be used as a step within a longer onboarding process.

SurePay as a microservice

SurePay can be used as a standalone microservice. What this means is that, once you have integrated towards the Signicat platform, you will be able to use SurePay in any context you see fit, including the services offered by Signicat (identity verification, authentication, and signing), but also independently. The main advantage is that integrating towards the Signicat platform allows you to use not only SurePay, but also any other service provided by Signicat: from other lookup services to different ID methods from several different countries.

How it 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”.

SurePay combined with iDIN

SurePay can also be used in combination with iDIN within an identity verification process. This plugin will make the process of verifying a user’s bank account number much more convenient for both the user and the merchant, with the added benefit that the merchant will be able to gather the user’s personal details from a trusted source.

How it works

  1. The merchant redirects the user to the identity verification process.
  2. The user uses iDIN to authenticate their identity and consents to sharing their identity attributes.
  3. A plugin prompts the user to enter the IBAN of their bank account and provide consent. If the IBAN is already known before starting the identity verification process, it can be included in the redirect URL, in which case the IBAN will be prefilled in this step, and the user will not be able to edit it.
  4. Signicat sends the IBAN (from the plugin) and the user’s identity attributes (from iDIN) to SurePay. The IBAN will always be converted to uppercase, both when it is entered by the user and when it is prefilled.
  5. The merchant gets a response which includes the IBAN, the user’s identity attributes, and whether or not there is a match. If there appears to be a typo in the name, the response will also include a name suggestion. Bear in mind that a message indicating a successful execution does not mean that the IBAN provided by the user is valid or real, just that the communication with SurePay has been successful. The response fields that indicate whether an IBAN is valid and exists are “valid” and “found”, respectively.

If an error prevents the SurePay check from being carried out, only the result of the iDIN authentication will be returned. This includes cases in which the end-user cancels the operation without entering or confirming an IBAN.

How to integrate

Integration with SurePay is done via the same API as Signicat’s ID methods. See “Get started with authentication“ for more information. Through the single point of integration, one will get access to Signicat’s wide portfolio of integrated ID methods and other services like identity paper verificationlookups, and video assurance.

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: id.signicat.com/surepay/prc

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:

  • SIGNICAT
  • RESELLER
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 valid
  • NAME_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 +
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 organization. In this case, the legal name of the organization is provided.
  • If no name was provided in the request and the IBAN belongs to an organization.
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 account
  • ORG: an organization
  • UNKNOWN: 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"
}

Was this helpful?