Documentation

Client hosted - Creating a single payment

Suggest Edits

Prerequisites

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

  • 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

Before you're able to make a request for payment, 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 payment request. If you have not received these values yet, please contact support.

Client Hosted UI and UX Guide

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. Full list here
  2. Create payment request - creates the payment request within the Ordo platform and allows us to provide status updates on that payment.
  3. Initiate payment request - provide 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 payment request.

🚧

Prerequisites

Refunds

If you intend to use Ordo's refund capability and the bank that your end customer selects supports the sharing of refund data, you must inform the end customer that you will be collecting their payer details during the payment request authorisation process. This is a requirement set out in the Open Banking standards and is outlined in the Ordo client hosted contract.

Not all banks support the sharing of refund data and therefore it is recommended that you only display any messaging when they select a bank that supports this flow. This information will be in the response of the GET Institutions call.

Example copy:

We will ask your bank to share your sort code and account number with us. If you ask for a refund, we will use these to process your refund request.

We will not use these details for any other reason.

For more information on Ordo Refunds, please go to the Refund page.

Institutions

The bank names and logos provided in the Get Institutions response are regularly updated to ensure the naming conventions and branding is up to date, and when new banks are added, therefore it is a requirement to call this API during each end user journey and to also display the ordoInstitutionIdand icon to the end user as per API response.

Example copy:

We will ask your bank to share your sort code and account number with us. If you ask for a refund, we will use these to process your refund request.

We will not use these details for any other reason.

For more information on Ordo Refunds, please go to the Refund page.

Get Institutions

The bank names and logos provided in the Get Institutions response are regularly updated to ensure the naming conventions and branding is up to date, and when new banks are added, therefore it is a requirement to call this API during each end user journey and to also display the ordoInstitutionIdand icon to the end user as per API response.

Example - Institution endpoint:

GET
https://test.api.ordopay.com/Payments/v1/institutions
HTTP/1.1

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

[
    {
        "media": {
            "logoUrl": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
            "iconUrl": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0"
        },
        "refundDataAvailable": false,
        "ordoInstitutionId": "int_modelo_sandbox",
        "name": "Modelo Sandbox"
    }
]

📘

Scope

registry smartrequests obi

Refer to the API reference for further information on Get Institutions

Example - Create payment request:

POST
https://test.api.ordopay.com/Payments/v1/create
HTTP/1.1

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

JSON Body:
{
  "senderParticipantId": 1234,
  "billerParticipantId": 1234,
  "billerReference": "EXAMPLE REFERENCE",
  "billerAccountId": "d91439d3-3855-494c-a096-6734f822af2f",
  "payerAliasType": "EMAIL",
  "payerAliasValue": "[email protected]",
  "payerReference": "EXAMPLE REFERENCE",
  "amountDue": 10.50,
  "dueDate": "2022-10-19T07:51:52+00:00",
  "partialPaymentAllowed": false,
  "dueDateExtensionsAllowed": false,
  "attachmentBatchId": "",
  "amountCurrency": "GBP",
  "partialPaymentsRemaining": 0,
  "expiryDate": "2022-10-20T07:51:52+00:00",
  "bdrRedirectURL": "https://example.com/redirectUrl",
  "bdrCancelURL": "https://example.com/cancelUrl",
  "bdrErrorURL": "https://example.com/errorUrl",
  "refundAccountRequired": true
}

{
  "bdRlink": "https://rfpdevwebportal.azurewebsites.net/2dGhIcjmTnK",
  "smartRequestId": "95a43002-5ba3-44a7-a4e1-cbd50bf5cb70",
  "creationDateTime": "2022-10-19T10:36:05",
  "status": "PENDING",
  "paymentStatus": "UNPAID",
  "billerParticipantId": 1234,
  "billerContactEmail": null,
  "billerContactPhone": null,
  "billerReference": "EXAMPLE REFERENCE",
  "billerAccountId": "d91439d3-3855-494c-a096-6734f822af2f",
  "payerParticipantId": null,
  "payerAliasType": "EMAIL",
  "payerAliasValue": "[email protected]",
  "payerReference": "EXAMPLE REFERENCE",
  "amountDue": 10.50,
  "amountCurrency": "GBP",
  "dueDate": "2022-10-19T07:51:52+00:00",
  "expiryDate": "2022-10-20T07:51:52+00:00",
  "dueDateExtensionsAllowed": false,
  "partialPaymentAllowed": false,
  "partialPaymentsRemaining": 0,
  "attachmentBatchId": "",
  "refundAccountRequired": true,
  "smartRequestUrls": {
     "bdrRedirectURL": "https://example.com/redirectUrl?srID=95a43002-5ba3-44a7-a4e1-cbd50bf55cb70",
     "bdrCancelURL": "https://example.com/cancelUrl?srID=95a43002-5ba3-44a7-a4e1-cbd50bf55cb70",
     "bdrErrorURL": "https://example.com/errorUrl?srID=95a43002-5ba3-44a7-a4e1-cbd50bf55cb70"
  }
}

Example - Initiate endpoint:

POST
https://test.api.ordopay.com/Payments/v1/initiate
HTTP/1.1

Headers:
{
  Authorization: Bearer {access_token},
  "Ocp-Apim-Subscription-Key": {subscription_key},
  "payerAliasvalue":"[email protected]"
  "payerAliastype":"EMAIL"
  "content-type": "application/json"
}

JSON Body:
{
    "ordoInstitutionId": "int_modelo_sandbox",
    "amount": 10.00,
    "currency": "GBP",
    "smartRequestId": "47406800-101b-408f-b3c9-66a3f73173fc"
}

{ 
"authorisationUrl": "https://example.com/redirect_url_to_institution", 
"paymentIdempotencyId": "ORD91094d548f1940f3975c6cffc3b7c92f"}
}

Success and errors states

As the Open Banking payment 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 newSmartRequestBDRLink endpoint features 2 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:

  • bdrRedirectURL - redirect back to merchant, payment successful
  • bdrErrorURL - redirect back to merchant, payment error at bank

These fields are designed to give you flexibility for handling all known payer journeys. Please note that the bdrCancelURL is only needed for the Ordo hosted flow in order to redirect an end customer from the hosted solution back to the merchant.

More information can be found within the API section.

Updated 6 months ago