Ordo hosted - Creating a recurring payment mandate
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
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 5 months ago