Payment initiation service (PIS)

LUXHUB One provides a unified interface to access the PSD2 APIs of multiple providers, establishing a common data model, security profiles and authorization flows to overcome the complexities caused by differing implementation standards.

Therefore, as a consumer of LUXHUB One, you are able to seamlessly integrate the APIs of various PSD2 providers and thus provide easy access to PSD2 account information and payment initiation services (PIS) to your customers.

In this tab you will find an explanation on PIS flow and implementation details:

• Introduction
• PIS flow
• API calls
  
  • Retrieving a list of providers
  • Making a payment
  • Retrieving payment status
  • Additional API calls

Please refer to "Documentation" tab for general implementation details prior to reviewing PIS  implementation details below.

Introduction

In addition to account information related services, LUXHUB One enables you to initiate a payment order, with the account holder’s explicit consent, from their online payment account.

LUXHUB One provides the option to leverage the different payment-related features of covered PSD2 APIs.

For example, the API-initiated payment could be either a one-off transaction or a recurring one; it could concern a single transaction or multiple simultaneous transactions.

PIS flow

 1. End-user starts a payment. It is assumed that the end user is already logged into the consumer’s system and that the user has already provided - or that you already have available - the payment details, such as the receiving account reference; the amount and currency, etc.

2. Consumer obtains the list of available providers from LUXHUB One. LUXHUB One will return only providers setup for your organisation out of all supported providers.

3. Consumer shows the list of available providers to the end-user. 

4. End-user selects the bank out of which the payment will be paid.

5. The consumer forwards the request to LUXHUB One.

6. LUXHUB One obtains the access token from the bank if necessary. The payment initiation request is transformed to match the bank’s PIS PSD2 API specification and forwarded.

7. The provider sends back the response for the payment initiation request.

8. LUXHUB One checks if an SCA is required to authorize the payment and it forwards the URL to do so, together with the payment id and its status.

9. The end user authorizes the payment by performing the SCA.

10. Additionally, the consumer can initiate a request to get the payment status - but note, this operation is not supported by all providers.

11. LUXHUB One transforms the payment status request to match the bank’s PIS PSD2 API specification and forwarded.

12. The provider sends back the response for the payment status request.

13. LUXHUB One forwards the provider's response to the consumer.

API calls

Note: the client credentials access token (Oauth2 credentials) obtained from the developer portal during the onboarding process must be added to every call made to LUXHUB One API through header “Authorization”. E.g.: Authorization: Bearer ACCESS_TOKEN. 

Retrieving a list of providers 

To retrieve a list of your providers and provider specific information, you will need to make a call to [GET] /providers endpoint. Below an example of how to retrieve provider list.

curl –location –request GET ‘https://apis-sbx.luxhub.com/oneapi/v1/providers’

As part of the response message, you will get provider details and also additional information about provider implementation, for example what payment products are supported by the provider.

Making a payment

In order to initiate a payment, consumers must send a request to endpoint [PUT] /payments.
This endpoint does not require a permission to be created in advance, since the user will be requested to authorize the payment every time a payment is created.

Note that the debtor account must belong to the user that will perform the SCA.

Please find below and example.

curl –location –request POST ‘https://apis-sbx.luxhub.com/oneapi/v1/payments’ \
--header ‘LH-BIC-Provider: DEMOLULLLBG’ \
--header ‘LH-USER-Id: {the user id}’ \
--header ‘X-Request-ID: 6d8bcdd1-f172-4582-bf78-ae51f4b361b9’ \
--header ‘Signature: {the calculated signature (see message signing section)}’ \
--header ‘TPP-Signature-Certificate: {the certificate downloaded from portal}’ \
--header ‘Date: Mon, 22 Jun 2020 12:25:30 GMT’ \
--header ‘PSU-IP-Address: 127.0.0.1’
--header ‘TPP-Redirect-URI: https://localhost’ \
--header ‘Content-Type: application/json’ \
--data-raw ‘{
  “originator”: {
    “debtorAccount”: {
      “iban”: “FR1530066959878814769786878”,
      “currency”: “EUR”
    },
    “debtorName”: “John Smith”,
    “initiatingParty”: “My application”
  },
  “beneficiary”: {
    “creditorName”: “Sarah Doe”,
    “creditorAccount”: {
      “iban”: “FR7612345987650123456789015”,
      “currency”: “EUR”
    }
  },
  “paymentDetails”: {
    “creationDateTime”: “2020-06-10T09:33:48.734Z”,
    “instructedAmount”: {
      “amount”: “2”,
      “currency”: “EUR”
    },
    “paymentTypeInformation”: {
      “categoryPurpose”: “DVPM”
    },
    “requestedExecutionDate”: “2020-06-09T22:00:00Z”,
    “endToEndIdentification”: “a6358e361a4e4863a3cff814d42b8d24”,
    “instructionIdentification”: “603d3de12e634333831763ae046c5e1e”,
    “remittanceInformation”: “A comment”
  },
  “paymentProduct”: “sepa-credit-transfers”
}’

As response, consumers will receive the following structure:

{
  “authorization_uri”: “https://….”,
  “paymentId”: “6004924001000001”,
  “paymentStatus”: “RCVD”,
  “transactionFees”: {
    “amount”: “12.25”,
    “currency”: “EUR”
  }
}

When authorization_uri property is present in response, it means that consumers must redirect the end-user to the given URL to perform SCA for authorization. 

At the end of authorization process, provider will redirect the end-user back to your application.

Retrieving payment status

To retrieve payment status you can use either  via  [GET] /payments/{paymentId} endpoint (to get payment details including payment status) or via [GET] ​/payments​/{paymentId}​/status (to get payment status only). You will need to provide the paymentId of the payment that you would like to retrieve payment status.

Additional API calls

Please refer to the "Endpoints" tab for a full list of API operations.