For Partners/Merchants who would like to use the payment & E-Mandate setup flow, using their own User Interface, this section describes the APIs required.

In order to launch the Open Banking Payment and E-Mandate signup flow, in SELF_HOSTED mode, you must call a number of payment- and mandate-related APIs, as outlined below. A Postman collection may be provided upon request. Please contact your Account Manager for more details.

Payment APIs

The following APIs are required:

Service Endpoint Description
Retrieve Bank GET /banks Returns the list of banks to be displayed on the Bank Selection screen.
Create Payment POST /payments Creates the Open Banking payment.As part of this interaction the payer is:
  • Passed to the selected bank to authorise the payment.
  • Redirected back from the bank.
Retrieve Payment GET / payments/{paymentId} Retrieve the Payment Details to check its status = PAYMENT_RECEIVED or wait for the PaymentReceived Webhook (or both).
This call also retrieves the debtor details for the E-Mandate preparation step.

Create & Sign the Mandate/DDI

Once the payment has been successfully processed, the following services are required to complete the E-Mandate signing step:

Service Endpoint Description
Prepare E-Mandate POST /emandates This request returns a unique token used to render the E-Mandate screen. The Token encapsulates:
  • The Merchant configurations
  • Merchant-specific details (Creditor Scheme ID, Scheme Type, etc.)
  • Payer details (Address details, phone details, email, etc.)
The account details retrieved from the Open Banking payment are used to pre-populate the account details when the PSU goes to sign the E-Mandates. Note that these details are displayed in read-only mode, the user cannot modify the details.
Initialise Conversation (Optional) GET /conversations/init Call this service to see the next available steps in the conversation.
This is an optional step.
Retrieve E-Mandate Details (Optional) GET /conversations/sign Use this service to retrieve the E-Mandate details to be rendered for the payer to sign.
This is an optional step.
Sign Mandate POST /conversations/sign Call this service to sign the Mandate. This step is required. Certain response elements should be stored for use later.
  • The encodedMandateId and encodedSchemeId are required to build the URI where you can retrieve your Signed Mandate details.
  • You will also need this for matching of the MandateElectonicSign notification (if you have enabled the Mandate Signature Webhook.
Retrieve E-Mandate (Optional) GET /conversations/document After the E-Mandate is signed the PSU may receive a Mandate PDF via E-Mail. If you want to download the PDF for your records use this service.
This step is optional
Retrieve Mandate (Optional) GET /schemes/{schemeId}/mandates/{mandateId} Use this service to retrieve the mandate details after it has been signed.
This step is optional