Creating a recurring payment mandate

Suggest Edits

After you have completed all you need to do at Get Started, you can now learn how to create a new payment mandate for your customer; this mandate is needed to set up recurring payments.

Introduction

Recurring Payment Mandates enable you to collect any customer payment on a repeating basis for fixed or variable amounts. Examples for this includes:

  • Fixed recurring payments, such as streaming subscriptions or rental payments
  • Regular, but differing amount, payments, such as utility bills or loan repayments
  • Ad-hoc payments, such as automated top-up of accounts when balances are low
  • One-click style checkouts, like paying for on-demand food delivery or ride-hailing services

You can set up a mandate with your customers that allows you to collect payments on a regular basis as long as it is in line with the parameters that has been agreed with both parties. There's no need for the customer to provide additional authorisation for each payment, which gives you and the customer more transparency, flexibility and security than the current services like Direct Debit, Standing Orders etc.

Types of recurring payment mandate

TypeDescription
SweepingEnables the transfer of money between two accounts belonging to the same person, also referred to as 'me-to-me' payments. Typical use-cases are for customers paying into their own savings account, making a loan repayment, or topping up a pre-paid card balance.
Non-SweepingEnables payment to third-parties, also referred to as 'me-to-business' payments. Typical use-cases are for 1-click checkout at an eCommerce site you use regularly or paying a utility bill.

Operating in the background, our Recurring Payment Mandate API is invisible to the end user and gives you complete control of your payments experience.

Creating a recurring payment mandate

To create a mandate, you need to provide Ordo with the parameters you want your customer to sign-up to. You also need to say whether the mandate is for a sweeping or non-sweeping use-case, see above for the different types of mandates.

Parameters

There are a number of parameters that you can choose to include within the mandate:

  • Maximum transaction amount; this is the maximum amount that you can collect from your customer in a single transaction
  • Start date; when you want the mandate to start (this must be a future date)
  • Expiry date; when you want the mandate to end (this can be open-ended)
  • Maximum period limit; this is the total amount that you can collect from your customer in a given period; you must choose at least one or more of daily, weekly, fortnightly, monthly, annually, depending on your use-case.

🚧

Note:

The details of a mandate cannot be changed after the mandate is created. For this reason, you need to make sure that all the parameters are correct at the time of creation. If they are incorrect, or over time need to be amended, you would need to create a new mandate with your customer and cancel the existing one.

Ordo Controls

Ordo performs checks on each transaction initiated under a mandate. This is to ensure that an individual transaction or period limit is not breached by the merchant or by a payer who might be initiating a transaction.

The ASPSP will also perform checks on each transaction where the VRP mandate is authorised

🚧

Note:

Both the Ordo and ASPSP checks mean that a ‘guarantee’ or liability model like that use with Direct Debit is not needed, so merchant can treat funds received as irrevocable.

Refunds

If you want to offer your end customer a refund, then you can set ReadRefundAccount to ‘True’ within the Create Mandate API endpoint.

The mandate must be authorised AND the bank involved support the sharing of refund data for the data to be made available to Ordo. Once the bank has shared the Payer account details with Ordo, Ordo will notify the merchant that the Payer account details have been captured. Ordo then store the payer’s account details against the mandate ID and the Merchant can retrieve data to make a push payment.

Mandate Creation - validFromDate

This API field can be used by a merchant to offer a future start date for the mandate. This could allow an end customer the option choose a future date that suits their regular income whilst in the merchant space, and then consenting at point of engagement.

🚧

Note

If the validFromDate has a date value that is present (current day) or in the past, then the date that the mandate is consented to at the ASPSP utilised.

The validFrom date can be used with both Consent and Calendar Period alignments.

Period Alignment - Consent vs Calendar

This API field specifies whether the recurring payment mandate value limits are calculated from the date/time of consent authorisation, a future ‘validFromDate’ as determined by the merchant, or aligns with the calendar for that period:

  • Week: 1st day of period will always be Monday
  • Fortnight: Not available for Calendar option
  • Month: 1st day of period will always be the first of the month
  • Year: 1st day of period will always be First January

As the ISO calendar does not support or provide any guidance on when a fortnight should start, hence for a PeriodType of Fortnight the PeriodAlignment must be Consent.

📘

Example: If the mandate parameters are period type is ‘month’, period alignment is ‘calendar’ and amount is ‘£30’

PeriodStartEndApplicable Limit
115-Jun-2330-Jun-2315.00 GBP
201-Jul-2331-Jul-2330.00 GBP
301-Aug-2331-Aug-2330.00 GBB

📘

Example: If the mandate parameters are period type is ‘month’, period alignment is ‘consent’ and amount is ‘£30’

PeriodStartEndApplicable Limit
115-Jun-2314-Jul-2330.00 GBP
215-Jul-2314-Aug-2330.00 GBP
315-Aug-2314-Sep-2330.00 GBP

Prerequisites

Before you're able to make a recurring mandate, your mock bank account must have been added by Ordo to your staging web profile.

This can be checked by logging in and navigating to Billing Accounts on the navigation panel on the left. See below for an example of what you should see. If a bank account has not been added, please contact support.

By this point you should also have received an email containing your billerParticipantId and billerAccountId which are required fields when creating a recurring payment mandate. If you have not received these values yet, please contact support.

Create a new VRP mandate

You can create a mandate to support recurring payments using Ordo. The response message will contain a link, which you can present to your customer. They can then use the link to authorise their bank to set up the mandate.

See below for an example request including headers and body to create a VRP mandate request.

Headers:
{
  Authorization: Bearer {access_token},
  "Ocp-Apim-Subscription-Key": {subscription_key},
  "participantid": 4567
  "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",
  },
}

Successful response:

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

If the POST is successful, the response will contain a vrpAuthUrl property. This URL is unique to this mandate request and can be provided to your customer by whatever method you choose. For testing purposes, on our staging environment, navigating to the URL for vrpAuthUrl will begin our authorisation flow and will allow you to complete the set up of a test mandate on our staging environment.

As part of this feature the Ordo platform will append the mandate ID ("mandateId") as a query string to the redirect URLs you supply when creating a VRP mandate.

These are outlined below:

redirectURL – redirect back to merchant, payment successful
cancelURL – Redirect back to merchant, payment cancelled
errorURL – redirect back to merchant, payment error at bank

These fields are designed to give you flexibility for handling all known VRP mandate authorisation journeys. More information can be found within the API section

Creates a new VRP transaction

Once your customer has authorised a recurring payment mandate with their bank, you can start to collect payment. This API triggers a payment instructions the customer's bank, which will be paid immediately provided the payment amount is within the parameters agreed by the customer and the customer has sufficient funds in their account.

Example transaction request

{
    "vrpMandateId": "2543c08c-985c-4b73-bdfc-e54ea2cdf20a",
    "paymentAmount": {
        "amount": "1.00",
        "currency": "GBP"
    },
    "billerReference": "E-Commerce Ref"
}

Successful response:

{
    "vrpTransactionId": "ac76a999-3650-41a0-bbff-0bedebdf263e",
    "vrpMandateId": "2543c08c-985c-4b73-bdfc-e54ea2cdf20a",
    "createdDate": "2023-01-13T10:51:50.4401016+00:00",
    "paymentDate": "2023-01-13T10:51:50.4208637+00:00",
    "status": "PENDING",
    "paymentStatus": "UNPAID",
    "paymentAmount": {
        "amount": 1.00,
        "currency": "GBP"
    },
    "billerReference": "E-Commerce Ref"
}

📘

Scope

obi vrp registry

Refer to the API reference for further information on creating a mandate and transactions

Updated 29 days ago

What’s Next