The base URL for the Payment Initiation Service API is: /xs2a/routingservice/services/ob/pis/v3

POST Scheduled Payments

Endpoint: POST /scheduled-payments

This endpoint is used by the Initiating Party to set up payment initiation for an ASPSP.

These endpoints are used to cancel a payment on behalf of the Payment Service User. Strong Customer Authentication might be required by the ASPSP, the response will indicate which step is required to complete the payment.

DELETE Payments

Endpoint: DELETE /payments/{paymentId}

Endpoint: DELETE /periodic-payments/{paymentId}

Endpoint: DELETE /scheduled-payments/{paymentId}

Endpoint: DELETE /bulk-payments/{paymentId}

Data model

Request	Response (click to enlarge)
	If the ASPSP doesn’t require an SCA for the deletion of a payment, the response will be empty with the HTTP code 204 (deleted). If SCA is required the response will be given with HTTP 200, and the following response:

POST Cancellation-Identification

Endpoint: POST /payments/{paymentId}/cancellation-identification

This API is used to start an authorization process explicitly in the Decoupled Approach, where the PSU identification isn’t given in the DELETE payment already. 

Data model

Request	Response

POST Cancellation-Authorisations

Endpoint: POST /payments/{paymentId}/cancellation-authorisations

This endpoint is used to start an authorization process explicitly which is required for some ASPSPs. As well it is used in Multi-Authorization scenarios (supported in an extended PIS service) and in Embedded Approach.

Data model

Request	Response (click to enlarge)

PUT Cancellation-Authorisations

Endpoint: PUT /payments/{paymentId}/cancellation-authorisations/{authorisationId}

This endpoint is used in Embedded Approach to provide the required information according to the necessary steps driven by the ASPSP due to the Links section. 

Data model

Request	Response (click to enlarge)

Additional Payment Services can be provided by the Open Banking Service. The functions are designed to support the complete payment lifecycle.

Authorised payment will be validated by the bank and executed according to the payment type. 

You can learn about payment execution progress either by polling the payment status by yourself or by subscribing to our push notifications. If you choose to subscribe to push notifications, we will continuously check with the bank on payment authorisation and execution progress and proactively notify you of  the changes. 

Endpoint: POST /payments/{paymentId}/confirmation

Endpoint: POST /periodic-payments/{paymentId}/confirmation

Endpoint: POST /scheduled-payments/{paymentId}/confirmation

Endpoint: POST /bulk-payments/{paymentId}/confirmation

This API is used to confirm a payment. Confirmation can be required when the payment is in the 'AUTHORISED' state:

1. When its required by the ASPSP standard
2. When a payment fee is involved, in that case the response of the payments status api will provide a link to this api in the 'FeePaymentConfirmationUrl' field.

Data model

Request	Response

The authorization of payments depends greatly on the approach chosen by the ASPSP. In the standard Redirect Approach with implicit start of authorization, no further endpoint needs to be called by the Initiating Party. There is a redirection of the PSU’s browser to the ASPSP, which will handle all steps for authorization without involving the Initiating Party.

However, the ASPSP might require an explicit start of authorization for the Redirect Approach as well. In that case, the endpoint POST Authorizations must be used. In the Decoupled Approach, the authorization must also be started explicitly; usually, for that, the identification of the PSU is required. Therefore, the POST Identification endpoint must be called.

For the Embedded Approach, data has to be added to the authorization by multiple requests to the PUT Authorization endpoint.

These endpoints are defined for Scheduled Payments, Periodic Payments and Bulk Payments separately, but the endpoint definition differs only in the path of the endpoint. All other parameters are identical

POST Payment Identification

Endpoint: POST /payments/{paymentId}/identification

Endpoint: POST /periodic-payments/{paymentId}/identification

Endpoint: POST /scheduled-payments/{paymentId}/identification

Endpoint: POST /bulk-payments/{paymentId}/identification

This API is used to start an authorization process explicitly in the Decoupled Approach, where the PSU identification isn’t given in the POST payment already. 

Data model

Request	Response

POST Authorisations

Endpoint: POST /payments/{paymentId}/authorisations

Endpoint: POST /periodic-payments/{paymentId}/authorisations

Endpoint: POST /scheduled-payments/{paymentId}/authorisations

Endpoint: POST /bulk-payments/{paymentId}/authorisations

This endpoint is used to explicitly start an authorization process, which is required by some ASPSPs. It is also used in Multi-Authorization scenarios (supported as an extended service) and in the Embedded Approach.

In the Multi-Authorization scenario, this endpoint will have to be used for each individual authorization, since the ASPSP requires an explicit start of authorization for each of the individual authorizations to be carried out by multiple PSUs for the same payment.

Data model

Request	Response (click to enlarge)

PUT Authorisations

Endpoint: PUT /payments/{paymentId}/authorisations/{authorisationId}

Endpoint: PUT /periodic-payments/{paymentId}/authorisations/{authorisationId}

Endpoint: PUT /scheduled-payments/{paymentId}/authorisations/{authorisationId}

Endpoint: PUT /bulk-payments/{paymentId}/authorisations/{authorisationId}

This endpoint is used in the Embedded Approach to provide the required information according to the necessary steps driven by the ASPSP due to the Links section.

Data model

Request	Response (click to enlarge)

Payments have different status depending on the actual state of processing: 

• Open
• Authorised
• PartiallyAuthorised
• SettlementIinProcess
• SettlementCompleted
• ReceivedByCreditorBank
• ReceivedOnCreditorAccount
• Cancelled
• CancelledAtTPP
• Error
• Expired
• Pending (The Apsps put the payment in a pending state, this can happen for multiple reasons. This is not a final state, another get payments/status should be made to get an update on the status)

Not all ASPSPs are differentiating between all the status values listed above. The Status PartiallyAuthorised can be given for a payment in multi-authorizations if the first PSU has authorised and there are still authorizations of additional PSUs are outstanding. The Multi-Authorization is an extended service of Accout-to-Account payments.

For some ASPSPs the status of a payment isn’t updated furthermore when the Authorised status is achieved. For most ASPSPs the final status is SettlementCompleted. Information on the final status for payments for given ASPSPs can be retrieved form the Reach API.

Open Banking Services

In the following picture the status values are shown in a state diagram:

Bank Selection Interface

While using the Bank selection interface the following payment status flow is applicable:

GET Payment Status

These endpoints are used to retrieve the status of a payment.

Endpoint: GET /payments/{paymentId}/status

Endpoint: GET /periodic-payments/{paymentId}/status

Endpoint: GET /scheduled-payments/{paymentId}/status

Endpoint: GET /bulk-payments/{paymentId}/status

Data model

Request	Response (click to enlarge)

Example

Request

Address: https://localhost:8443/xs2a/routingservice/services/ob/v3/payments/11376380/status

    HttpMethod: GET

    Headers: {Accept=application/json, Digest=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, 
X-Request-ID=de875f27-5eb7-2b3d-bb88-86e0fe0cdf65, Authorization=Bearer ec464ba833a955952646cbc834f4e6b, MessageCreateDateTime=2022-03-24T14:48:16.143Z}

Response

ResponseCode: 200

    Headers: { X-Request-ID=283c264a-3212-4240-a039-01b229fa854f, MessageCreateDateTime=2022-03-24T14:48:16.541Z}
    Payload: {"CommonPaymentData":
    "PaymentStatus": "SettlementCompleted",
    "PaymentId": "11376380",
    "AspspPaymentId": "00015952769469210",
    "AspspId": "10002"
}}

The payer needs to approve payment execution to their bank. Payer’s bank will apply a strong customer authentication (SCA) to ensure payer's identity. This can lead to multiple flows in which a payment can be completed. 

If you are Using the Worldline Open Banking functions directly, depending on the payment flow, you have to implement the Payment Authentication API's.

For faster integration and better user experience we offer a Bank Selection Interface that could be customised with your branding allowing to choose the payer's bank and handling the complexity of different PSD2 authorization flows (redirect / decoupled / embedded), so that you will be able to focus on your product and leave the boring stuff to us. 

As part of this stage you submit a payment to Worldline using Payment API.

Worldline performs technical validations of the payment and forwards the payment request to the bank.

Click on the relevant payment type to learn specific implementation details:

• Single Payment
• Scheduled Payment
• Periodic Payment
• Bulk Payment

As part of this step, you will determine payment details such as payment amount, payment product (e.g. SEPA Credit, SEPA Instant credit, domestic or cross-border payments), whether  it is a single or bulk payment etc. Typically, this will be done as part of shopper’s check out or in context of invoice payment and will be handled by your software.  

You will need to let the payer choose their bank out of the list returned by the Reach Directory. We recommend refreshing the list of banks and their attributes once a day. Please note that some of the banks require additional information such as payer’s IBAN to be collected in advance.  You will find this information under the bank details provided by the Reach API. In addition, you can determine the preferred payment authorisation flow out of the ones supported by the bank (redirect / embedded / decoupled). 

As there is a lot of complexity related to the implementation of different payment flows and handling bank specific information, we recommend using our Bank Selection Interface for single payments – this is a set of predefined screens that can be customised to match your branding. As they are already integrated with the Reach API and Payment API, you only need to embed them as part of the user flow in your system. This will simplify the integration effort but its usage is optional.

In case you decided to not use the Bank selection interface, once you gathered all the necessary details, you can move to Step 2 - payment initiation.