Payments HU API Flow

Payment APIs - Flow

1. Initiate payment

  1. Initiate single payment

    Your application connects to the bank and creates a payment resource, by making a POST /payments/payment-product

    The bank platform will perform validations on technical level (regarding compatibility with Berlin Group Specifications) and functional level (allowed information, as, for example, supported currencies).

    If some validations fail, then payment initiation fails and an error message is provided.

    If everything is ok, the bank responds with an identifier for the resource (paymentId), status RCVD and a redirect URL link (which can be used by the customer to authenticate and authorise the payment) in the field _links.scaRedirect. For redirection to the URL, the response header parameter ASPSP-SCA-Approach will be returned with value REDIRECT.

  2. Initiate a periodic payment

    Your application connects to the bank and creates a payment resource, by making a POST /periodic-payments/payment-product

    The bank platform will perform validations on technical level (regarding compatibility with Berlin Group Specifications) and functional level (allowed information, as, for example, supported currencies).

    If some validations fail, then payment initiation fails and an error message is provided.

    If everything is OK, the bank responds with an identifier for the resource (paymentId), status RCVD and a redirect URL link (which can be used by the customer to authenticate and authorise the payment) in the field _links.scaRedirect. For redirection to the URL, the response header parameter ASPSP-SCA-Approach will be returned with value REDIRECT.

2. Authorize Initiated Payment

You should forward the user to the scaRedirect URL in order to authorize the payment.

Some validations are performed before, during and after the PSU authenticates itself.

If validations fail, the PSU will be informed into the SCA page and the flow will be redirected back to your TPP-Nok-Redirect-URI, if such URL was sent by you in the payment initiation message.

If validations passes, the PSU will see the payment detail screen and will have the option to authorize the payment.

If PSU will fail to authorize the payment in a predefined time or if PSU will cancel the transaction, the flow will be redirected back to your TPP-Nok-Redirect-URI, if such URL was sent by you in the payment initiation message.

If the PSU authorizes the payment, the flow will be redirected back to your TPP-Redirect-URI, information sent by you in the payment initiation message.

In Sandbox: no SCA will be required for authorization, a disclaimer specifying this will be displayed.

In Real API: The bank will perform SCA for the client based on RTS.

3. Get Payment details (optional)

You can check the status of the initiated payment (with the paymentId) and get the payment details (as submitted in payment initiation). This is carried out by making a GET /payments/payment-product/{paymentId}/

4. Get Payment status (optional)

You can check the status of the initiated payment (with the paymentId). This is carried out by making a GET /payments/payment-product/{paymentId}/status request to the initiated payments resource.

Payment status code indicates the status of a single payment transaction and is according to ISO 20022 Payment status codes table.

  • RCVD [Received] - Payment received and successfully validated (regarding compatibility with Berlin Group Specifications)
  • ACTC [AcceptedTechnicalValidation] - Payment successfully authorized by PSU
  • ACCP with flag fundsAvailable=false [AcceptedCustomerProfile] - Payment accepted for execution but with “Insufficient funds”
  • ACSP [AcceptedSettlementInProcess] - Payment initiation has been accepted for execution
  • ACSC [AcceptedSettlementCompleted] - Settlement on the debtor’s account has been completed
  • RJCT [Rejected] - Payment initiation has been rejected
  • CANC [Cancelled] - Payment was cancelled by PSU

5. Cancellation of single/ periodic payments

For single payment you should perform a DELETE /payments/payment-product/{paymentId} request

For periodic payment you should perform a DELETE /periodic-payments/payment-product/{paymentId} request

Sandbox: Cancellation is allowed only for payments in status RCVD or ACTC.

Real API: Cancellation is allowed only for payments in status RCVD

The bank platform will perform validations on technical level (regarding compatibility with Berlin Group Specifications) and functional level.

If some validations fail, then payment cancellation fails and an error message is provided.

If everything is OK, the bank responds according to the payment status:

  1. If the status of the payment is RCVD: status CANC, no PSU authorization needed;
  2. If the status of the payment is ACTC: status ACTC and a redirect URL link (which can be used by the customer to authenticate and authorise the payment cancellation) in the field _links.scaRedirect. For redirection to the URL, the response header parameter ASPSP-SCA-Approach will be returned with value REDIRECT.

6. Authorize cancellation request for single/ periodic payments

You should forward the user to the scaRedirect URL in order to authorize the cancellation of the payment.

Some validations are performed before, during and after the PSU authenticates itself.

If validations fail, the PSU will be informed into the SCA page and the flow will be redirected back to your TPP-Nok-Redirect-URI, if such URL was sent by you in the payment cancellation message.

If validations passes, the PSU will see the payment detail screen and will have the option to authorize the payment delete request.

If PSU will fail to authorize the payment delete request in a predefined time the payment will remain in status ACTC and follow the processing flow (for a better testing experience predefined timer was not implemented in Sandbox).

If the PSU authorizes the payment, the flow will be redirected back to your TPP-Redirect-URI, information sent by you in the payment initiation message.

In Sandbox: no SCA will be required for authorization, a disclaimer specifying this will be displayed.

In Real API: The bank will perform SCA for the client based on RTS.

7. Clean-up endpoint

You can clean up your activity in Sandbox and start over by using a dedicated clean-up endpoint. This endpoint will be available only in Sandbox.

For single payments you need to use: DELETE /payments/clean-up

For periodic payment you need to use: DELETE /periodic-payments/clean-up