Validate API - Examples

• Introduction
• Getting a Token
  • Extras
  • Project Examples
• Account Number
  • BACS Details
  • CC&C Details
  • CHAPSS Details
  • FPS Details
• Address
  • Autocomplete
  • Search
• CoP
• Email Address
• IBAN
• Phone Number
• Using on a form
• Using the Test Service
  • Account Number
  • Address
  • CoP
  • Email Address
  • IBAN
  • Phone Number

Introduction

This repository is meant to show you how to use Paygate’s API’s, by requesting a token and then using that to call the endpoint of your choice. There are runnable examples in each folder relating to each project, but the main bulk of it is here.

In the examples here I’m going to be using JavaScript with Axios

Getting a Token

We use oAuth2 to secure our endpoints, you should be given a secret key/api key, this must remain secret from anyone otherwise they will be able to request tokens and act as if they were you, think of it as your password.

Once you have your secret key you can request a token from our token endpoint https://portal.paygateservice.com/IdentityServer/identity/connect/token to do this you need to make a post request.

axios.post(
  'https://portal.paygateservice.com/IdentityServer/identity/connect/token',
  'grant_type=client_credentials&scope=API',
  {
    auth: {
      username: '**api_name**',
      password: '**api_key**'
    }
  }
);

This (if it’s right) will return an object like this.

{
  "access_token": "eyJ0eXA...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

You can then use this in the auth header of your request.

let tokenResponse = {'...response from above...'}

axios.get('http://somecovidapi/api/[action]',{
  headers: { Authorization: `Bearer ${tokenResponse.access_token}` }
})

Extras

You do not need to request a new token for each request, in the token response you’ll notice there’s a expires_in property this is the amount of seconds from requesting the token on when it will expire, in the example above, that would be an hour, so you can use this token for an hour before it expires.

You will have to manage this yourself, although there are a few libraries out there that can help with this. Identity model is a good choice

Project Examples

• Validate C# .Net Core
• Validate NodeJs

Account Number

The main call will allow a sort code and/or an account number, it will validate this information, along with this there are other calls to get service specific information.

BACS Details

A United Kingdom specific function that returns information specific to the BACS service for a given bank branch. Returns details or information use specifically for BACS electronic payments. The function can be used to determine that.

• The branch is a full BACS scheme member or a sponsored institution or not able to process BACS payments
• The branch can handle Electronic Direct Debit Instrutions (DDI)
• The branch can accept credits, debits
• Details of any disallowed transactions.types.
• Redirection sort codes. The sort codes that the payment needs to be directed to if the branch is unable to handles BACS payments directly.

CC&C Details

A United Kingdom specific function that returns information specific to the C&CC service for a given bank branch. Returns details or information use specifically for the C&CC Service. The function can be used to determine that.

• The branch is a C&CC scheme member, a full agency, a debit agency or does not participate in C&CC; does not accept C&CC payments.
• The bank ID of the settlement bank
• The Debit Agency Sortcode, if applicable

CHAPSS Details

A United Kingdom specific function that returns information specific to the CHAPS Sterling service for a given bank branch. Returns details or information use specifically for CHAPS Sterling payments. The function can be used to determine that.

• The branch accepts CHAPS Sterling payments directly, indirectly or does not participate in the CHAPS Sterling Payment scheme
• The routing BIC is the branch accepts CHAPS Sterling payments indirectly
• The CHAPS Sterling ID

FPS Details

A United Kingdom specific function that returns information specific to the UK Faster Payments service for a given bank branch.

Address

There are two ways to work with address lookups, the first is a search with the results populating a list, and the second is via autocomplete.

Autocomplete

There is only one endpoint for autocomplete /Address/Autocomplete this will always return an object with a list of addresses, but this will contain data to determine if the selected address is the final address. You will recursively call the same function passing in different sid’s until you reach an array with 1 address in that has the selected boolean set to true, for the initial search we recommend using a debounced function on the input event, this way you can populate the initial list while the user is typing.

This is a bit harder to implement, but does create some nice UX. You can see the images below for an example

The flow for this would follow this logic

Search

There are two endpoints for searching addresses, one is a lookup which will return an array of addresses and another which will return more details about an address. The way that you implement this is up to you, however you will always have to call lookup first, as this will give you the address id to pass to the /Address endpoint to get a structured address response back.

While we cannot force how you implement this, we suggest getting a user to enter their postcode and pressing a button to populate a select list with available addresses, then when one is selected call the /Address endpoint to get the formatted address data.

The two images below are an example of this.

The flow for this would follow this logic

CoP

CoP (Confirmation of Payee/Payer) is a name checking service for UK-based payments. The aim of the service is to reduce certain types of fraud as well as misdirected payments. Today, volumes of Confirmation of Payee/Payer requests are averaging more than one million per day. In short, this will check a name against bank account details to see if they match.

To make this request you will have to pass in the CustomerName, AccountNumber, SortCode and AccountType (along with keycode information) So for example.

{
  "CustomerName": "Example",
  "AccountNumber": "11111113",
  "SortCode": "111111",
  "AccountType": "Personal",
  "SecondaryReference": "",
  "Keycode": "ExampleKeyCode"
}

The AccountType must be Personal or Business depending on the bank account you’re checking against. Below is an example of all the possible responses you may get.

Email Address

Email address validation will not only validate that an email address is in the correct format but also validate that it is still in use and in general is a good email to use.

Validity will depend on the response of the email address, if the response is “ok” or “unknown” the email address will be classed as valid.

Below are the responses that can be returned.

IBAN

Verifies that an IBAN is valid, decomposes the IBAN and returns useful information such as bank/branch information and BIC.

Phone Number

Verifies that a phone number is valid and in use, it will return the original network details associated with the phone number, along with the current network details.

The international country calling code is required for this request, our advice on this (if you’re only accepting telephone numbers from a single country) is to prefix this yourself (example in the section below).

Using on a form

The intended use of this is to use this on a form, so you can have validation at entry, however due to costs per call, we recommend doing validation on form submit. An example of this would be using it on a form for registering direct debits.

Using the Test Service

We’ve created an endpoint so that you can test your integration before occurring any costs, these have either faked data or a small sample set to test out multiple calls resulting in both good and bad results.

This service will still expect the correct authentication and keycode, the calls below will not include these details, you will have to append them, you will not be charged for using this service.

You can access the API Documentation here

The base url for the test service is https://validate.paygateservice.com/validateonlineapitestservice/

Below is a list of the data to send to receive what response.

Account Number

Address

CoP

You can use whatever customer name you like, but for an example, I’ve used “John Doe”, the same goes with the sort code

Email Address

IBAN

Phone Number