Overview

Introduction

If you have a need to manage receivables into a large number of different bank accounts, either for your own organisation or on behalf of multiple customers, then you can use Ordo's Financial Institution (FI) APIs to add as many bank accounts to your ‘request’ capability as you need. Typical use cases include:

• banks managing a portfolio of savings or loan accounts,
• EMIs offering pre-paid card accounts, and
• SaaS providers operating hosted solutions for multiple customers.

Each payment request would present the name of the account that funds are to go to, providing a more personalised touch to your customer experience. You can also segregate different customers/business lines by creating a range of participant IDs, and associate different accounts and white-labelling to each participant ID.

📘

NOTE

When adding a billing account in the Ordo Staging or Production environment, please ensure that the sort code and account number are numeric values and six-digits and eight-digits respectively. If you have an account number that is shorter than eight-digits, it should be padded with leading zeros to meet the required eight-digit length.

Client On-Boarding Prerequisites

Please see our Get Started section, to learn in detail how to On-Board onto our platform and register for our Financial Institution API.

API Ochestration Guide For Financial Institution Flows

Creation Of A User And Participant
A Participant is an individual/company/organisation that can be involved in a Payment Request. However it is Users that use the service. A User therefore needs User Credentials for authentication.

The association between User(s) and Participant(s) allows the Ordo platform to support a flexible model whereby a User can be associated with multiple Participants allowing them to manage these via a single identity / set of credentials

To create a User and Participant:

Obtain an access token from the identity service with Client Credentials context, using the supplied Client Id and Client Secret, with scope ‘users’
· Create User API (POST user)
· Create Participant API (POST user/participants)
· Send Registration email API
· Validate user email API (Enter password)
· Verify user email API

Create User API (POST user)
Set the parameter verificationEmailRequired: “Y”

example body is

{
  "email": "[email protected]",
  "verificationEmailRequired": "Y",
  "firstName": "Fred",
  "lastName": "Bloggs"
}

This must be a valid email as you will receive an email with a link to confirm your identity and allow you to set up a password.

🚧

Note

Make sure you check spam (email will come from …@myordo.com)

A UserPID will be returned for use in subsequent API calls.

Create Participant API (POST user/participants)
Typically, an Ordo API customer that is integrating into Ordo does so as a single User/Client and can create new Participants and add each of them to this single User. Adding multiple Participants allows the User/Client to easily manage and administer a range of their own customers/business areas that require payment to be made to them. For instance, a Council may wish to have a Participant per administrative area, one for Council Tax, another for Parking fines etc. Each Participant can have one or more Billing Accounts (bank accounts) assigned to it.

Example body (where UserPID is value from step 1 with both RequestingUserPID and contextUserPID being the same value)

{
  "RequestingUserPID" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "contextUserPID": " xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx ",
  "participantType": "ORG",
  "participantDisplayName": "Contis",
  "organisationType": "",
  "organisationId": "",
  "billerApprovedName": null,
  "logo": null   
  "BillerStatus":"Y",
  "payerStatus": "Y",
  "participantDescription": "Y",
  "emailAddress": "[email protected]",
  "phoneNumber": "+918888888888",
  "address": {
    "addressLine1": "DLF",
    "addressLine2": "6 th floor",
    "addressLine3": "ramapuram",
    "addressLine4": "porur",
    "addressLine5": "CHN",
    "careOf": "Mr. DURAI",
    "poBox": "ABC",
    "premises": "MADRAS",
    "Locality": "Chennai",
    "Region": "Tamil Nadu",
    "Postcode": "600125",
    "Country": "India"
  }
}

A participantId will be returned

The UserPID will be supplied to you as part of the integration steps into our SIT, and then Production environments. The UserPID can be included in both the "requestingUserPID" and "contextUserPID", object fields with "requestingUserPID" being optional.

Add Biller Account API (returns Biller Account Id)
A Biller requires a bank account to receive payment into, and rather than providing these details in the Payment Request message, the Biller Account Id is used instead. When the end-customer pays the Payment Request, Ordo provides the actual account details to the payer’s bank. A Participant Administrator can add/remove account details. Bank Account details will be validated by the Financial Institution as part of the Know Your Customer (KYC) process.

To create a Participant within Ordo, you need to obtain a token using the Authorization Code flow. You obtain a token initially by logging in using your credentials and storing the bearer and refresh token. You then use the refresh token to obtain a new bearer token without the need to logon. You should do this periodically to ensure that you always have a valid token.

Once you have created a User, Participant and a Participant Alias, you will be able to use the Add Biller Account API to create a Biller Account

{
    "participantId": 1,
    "accountType": "PERSONAL",
    "accountSubType": "CURRENTACCOUNT",
    "paymentServiceProvider": "CGI",
    "currency": "GBP",
    "schemeName": "SortCodeAccountNumber",
    "accountName": "Account Name",
    "sortCode": "999999",
    "accountNumber": "99999999",
    "identification": "",
    "secondaryIdentification": ""
}

AccountType = PERSONAL / BUSINESS
AccountSubType = CURRENTACCOUNT

PaymentServiceProvider – Is optional

Once this is done, you're ready to create payment requests in favour of this account