The Payment Process "Bulk payment" allows to send multiple payments at once: individual payments are bundled together into one single transaction. The Bulk Payment is used for processing refunds on PIS payments on the Routingservice. Once the refund is requested by the customer and accepted by the Initiating Party, or initialized by the Initiating Party, the IP can directly use the Refund API for Online Refunds to initiate either a single or up to ten payments on the Routing Service (using the Bulk Payment Interface).

Please also check the Refund Section

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

POST Bulk Payments

Endpoint: POST /bulk-payments

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

Example

Example of a bulk payment request body.

{
  "PaymentProduct": [
    "PSD2-SCT"
  ],
  "PaymentProductChangeable": false,
  "PsuData": {
    "AspspId": "20210",
    "AspspProductCode": "string",
    "Country": "FR"
  },
  "CommonPaymentData": {
    "PreferredScaMethod": [
      "Redirect"
    ],
    "DebtorInformation": {
      "Name": "Rob Smith",
      "Agent": "EG8BCROZMX8",
      "Account": {
        "SchemeName": "IBAN",
        "Identification": "DE89370400440532013000",
        "Currency": "EUR"
      }
    },
    "ChargeBearer": "DEBT",
    "Payments": [
      {
        "EndToEndId": "ID-0123456789-A",
        "Amount": {
          "Amount": "123.45",
          "Currency": "EUR"
        },
        "CreditorInformation": {
          "Name": "John Smith",
          "Account": {
            "SchemeName": "IBAN",
            "Identification": "DE89370400440532013012",
            "Currency": "EUR"
          },
          "Agent": "UZWHIKRXVHT",
          "UltimateCreditor": "John Media Shop U"
        },
        "RemittanceInformation": "Remittance Information",
        "RemittanceInformationStructured": {
          "Reference": "Remit-23-43-42",
          "ReferenceType": "structured",
          "ReferenceIssuer": "Reference Issuer"
        }
      },
      {
        "EndToEndId": "ID-0123456789-B",
        "Amount": {
          "Amount": "78.56",
          "Currency": "EUR"
        },
        "CreditorInformation": {
          "Name": "Simon Walker",
          "Account": {
            "SchemeName": "IBAN",
            "Identification": "NL98INGB6709624056",
            "Currency": "EUR"
          }
        },
        "RemittanceInformation": "Remittance Information"
      }
    ]
  }
}

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

POST Periodic Payments

Endpoint: POST /periodic-payments

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

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.