Documentation

Client hosted - Creating a recurring payment mandate

Suggest Edits

Having gone through the Get Started guide, you should now have the following information to allow you to create a mandate:

  • subscription_key - The key used to access the Ordo API Management gateway.
  • client_id - Unique string identifying your application.
  • client_secret - Secret key used to authenticate your application with our platform.
  • billerParticipantId - which is your unique ID within Ordo.
  • billerAccountId - unique proxy of your account details for where payments will be received into.

If you do not have the above information, please go to See here for how to get started

Client hosted orchestration

Using Ordo's client hosted flow allows you to maintain your own UI and UX whilst still taking advantage of Ordo's Open Banking connectivity and orchestration.

  1. Get Institutions - provides you with a list of all the banks that Ordo has integrated with that an end customer can select to pay you from. If you know which bank your end customer has an account with, you can choose to only present that bank or make that the top choice on the list. Full list here
  2. Create mandate - creates the mandate within the Ordo platform and allows us to provide status updates on that mandate and any transactions under the mandate. This has the same content as the existing Ordo hosted Create mandate API.
  3. Initiate mandate - provides you the redirect to the selected bank so you can direct your end customer to their bank for authorisation
  4. End customer returns to you via your redirect URL provided in the creation of the mandate.

Example - Institution endpoint:

GET
https://test.api.ordopay.com/recurring-payments/institutions
HTTP/1.1

Headers:
{
  Authorization: Bearer {access_token},
  "Ocp-Apim-Subscription-Key": {subscription_key},
  "participantId: 1234,
  "vrpEnabled": true,
  "content-type": "application/json"
}

[
  {
      "ordoInstitutionId": "no-rbs",
      "name": "RBS",
      "media": {
            "iconUrl": "https://rfpprodstaukslrsh02.blob.core.windows.net/institutionmedia/no-rbs-icon.png",
            "logoUrl": "https://rfpprodstaukslrsh02.blob.core.windows.net/institutionmedia/no-rbs-logo.png"
        },
       "refundDataAvailable": true,
       "features": [
          "VRPSWEEPING",
          "VRPNONSWEEPING",
          "PIS",
          "AISBASIC",
          "VRPSWEEPING",
          "REFUNDS"
      ]
     }
]

📘

Scope

registry smartrequests vrp obi

Refer to the API reference for further information on Get Institutions

Example - Create mandate:

POST
https://test.api.ordopay.com/recurring-payments/mandate/create/sweeping
HTTP/1.1

Headers:
{
  Authorization: Bearer {access_token},
  "Ocp-Apim-Subscription-Key": {subscription_key},
  "participantid": 1234,
  "content-type": "application/json"
}


Body:
{
  vrpType: "SWEEPING",
  vrpMandateName: "Example Mandate",
  validFromDate: "2022-11-18T23:59:59Z",
  validToDate: "2022-12-31T23:59:59Z",
  billerParticipantId: {ORDO_BILLER_PARTICIPANT_ID},
  billerReference: "Biller Reference",
  billerAccountId: {ORDO_BILLER_ACCOUNT_ID},
  payerAliasType: "EMAIL",
  payerAliasValue: "[email protected]",
  payerReference: "Payer Reference",
  templateId: "ABC123",
  psuAuthenticationMethods: "SCA_NOT_REQUIRED",
  vrpControlParameters: {
    maximumIndividualAmount: 30.01,
    maximumIndividualAmountCurrency: "GBP",
    controlParameters: [
      {
        amount: 60.01,
        currency: "GBP",
        periodAlignment: "CALENDAR",
        periodType: "DAILY",
      },
      {
        amount: 120.01,
        currency: "GBP",
        periodAlignment: "CALENDAR",
        periodType: "WEEKLY",
      },
      {
        amount: 500.01,
        currency: "GBP",
        periodAlignment: "CALENDAR",
        periodType: "MONTHLY",
      },
    ],
  },
  attachmentBatchId: "myattachments",
  "refundAccountRequired": true,
  vrpURLs: {
    redirectURL: "https://www.example.com/redirectURL",
    cancelURL: "https://www.example.com/cancelURL",
    errorURL: "https://www.example.com/errorURL",
  },
}

{
    "vrpAuthUrl": "https://dev.myordo.com/2dLVX941IPd",
    "vrpMandate": {
        "vrpMandateId": "a634339b-2da6-4dda-8e69",
        "vrpMandateName: "Example Mandate",
        "vrpType": "SWEEPING",
        "creationDate": "2022-11-18T23:59:59.253",
        "status": "INITIATED",
        "validFromDate": "2022-11-18T23:59:59Z",
        "validToDate": "2022-12-31T23:59:59Z",
        "billerParticipantId: {ORDO_BILLER_PARTICIPANT_ID},
        "billerApprovedName": null,
        "billerReference: "Biller Reference",
        "billerAccountId: {ORDO_BILLER_ACCOUNT_ID},
        "payerParticipantId": 0,
        "payerAliasType: "EMAIL",
        "payerAliasValue": "[email protected]",
        "payerReference": "Payer Reference",
        "templateId: "ABC123",
        "payerRead": false,
        "psuAuthenticationMethods": "SCA_NOT_REQUIRED",
        "vrpControlParameters": {
            "maximumIndividualAmount": 30.01,
            "maximumIndividualAmountCurrency": "GBP",
            "controlParameters": [
                {
                    "amount": 60.01,
                    "currency": "GBP",
                    "periodAlignment": "CALENDAR",
                    "periodType": "DAILY"
                },
                {
                    "amount": 120.01,
                    "currency": "GBP",
                    "periodAlignment": "CALENDAR",
                    "periodType": "WEEKLY"
                },
                {
                    "amount": 500.01,
                    "currency": "GBP",
                    "periodAlignment": "CALENDAR",
                    "periodType": "MONTHLY"
                }
            ]
        },
        "refundAccountRequired": true
    },
    "vrpURLs": {
        "redirectURL": "https://www.example.com/redirectURL?mandateId=a634339b-2da6-4dda-8e69",
        "cancelURL": "https://www.example.com/cancelURL?mandateId=a634339b-2da6-4dda-8e69",
        "errorURL": "https://www.example.com/errorURL?mandateId=a634339b-2da6-4dda-8e69"
    }

Example - Initiate endpoint:

POST
https://test.api.ordopay.com/recurring-payments/mandate/initiate
HTTP/1.1

Headers:
{
  Authorization: Bearer {access_token},
  "Ocp-Apim-Subscription-Key": {subscription_key},
  "participantId":1234,
  "content-type": "application/json"
}

JSON Body:
{
    "ordoInstitutionId": "no-rbs",
    "vrpMandateId": "8f4a4337-f185-4b06-b476"
}

{
    "authorisationUrl": "https://api.sandbox.rbs.co.uk/authorize?client_id......",
    "consentId": "VRP-4077fefd-ae2b-4303-9fd1-d083c045a57a",
    "state": "ItYObexI4wWwt4zlYVUoJcSddyOEiP3A"
}

Success and errors states

As the Open Banking authorisation flow is dependent on the banks, it is important to recognise that the end customer can, infrequently, fall into an unhappy path. As such, you can provide Ordo redirect URLs to cover the below failure scenarios.

The create mandate endpoint features 3 object fields that allow our API customers to input a URL to redirect your customers to the correct merchant hosted webpage. These are outlined below:

  • redirectURL - redirect back to merchant, authorisation successful
  • cancelURL - redirect back to merchant, cancelled at bank
  • errorURL - redirect back to merchant, authorisation error at bank

These fields are designed to give you flexibility for handling all known authorisation journeys.

More information can be found within the API section.

Updated 6 months ago