PSP - debit flow

The payment service provider needs to implement a debit endpoint for the Partner API to make the initial debit request.

The endpoint that the payment service provider needs to expose must be in the following format:
<https://{{payment-service-provider-host}}/v1/debit>

📘

User interface

The payment service provider is responsible for managing the user interface for the payment.

Debit steps:

1. The user chooses to pay using a payment service provider on the merchant website.
2. The Partner API sends a debit request to the payment service provider.
3. The payment service provider responds with the redirect URL where the user interface for the payment service provider platform is hosted. In the response, the result code should be 000.200.000 if successful.
4. The payment service provider's user interface widget is displayed on the merchant's site for the user to interact with. During this step, all interactions with the user, for example, capturing second-factor authentication information like OTP, continues in the user interface screens between the user and the payment service provider. The Checkout plugins integration guidelines section describes best practices on how to ensure that the user interface is rendered correctly in e-commerce plugins.
5. The user submits the relevant information to the payment service provider for validation and fulfilment of the payment.
6. The payment service provider redirects back to the shopperResultUrl with the unique ID.
7. The Partner API sends a transaction status request to the payment service provider.
8. The payment service provider responds with the final status of the transaction: 000.000.000 for success in LIVE, and 000.100.110 for success in TEST.
9. The Partner API sends the final status of the transaction to the merchant.

PSP - refund flow

If a refund option is provided by the payment service provider, they must implement the refund endpoint provided by the Partner API to process refund transaction requests from the merchant.

The endpoint that the payment service provider needs to expose must be in the following format:
<https://{{payment-service-provider-host}}/v1/refund/{debitUniqueId}>

Both full and partial refunds are supported by the Partner API.

📘

Note

If the payment service provider does not support:

• Refunds, they should respond with a 404 HTTP status code for refund requests.
• Partial refunds, they should respond with the 900.100.202 result code for partial refund requests.

Refund steps:

1. The merchant initiates a refund request.
2. The Partner API sends a refund request to the payment service provider.
3. The payment service provider sends the refund response to the Partner API. The 700.400.200 result code should be used if the refund amount exceeds the original debit amount.
4. The Partner API sends the refund response to the merchant.

Partner API - webhook flow

The payment service provider must send a webhook to the Partner API whenever a transaction status event occurs.

A transaction status event refers to whenever the status of the transaction being processed changes, for example, from a pending status to a failed or successful status.

See the API reference section for sample webhook requests.

PSP - transaction status flow

A transaction status endpoint must be implemented by the payment service provider in order to allow the Partner API to query the transaction status at any given point in the transaction life cycle.

This endpoint is called when the Partner API needs to query the status of a specific transaction. The Partner API sends a unique ID and the payment service provider must respond with the details of the transaction linked to that ID.

The endpoint that the payment service provider must expose must be in the following format:
<https://{{payment-service-provider-host}}/v1/status/{uniqueId}>

Transaction status steps:

1. The Partner API sends a transaction status request with a unique ID to the payment service provider.
2. The payment service provider responds with the details of the transaction linked to the unique ID.
3. The Partner API sends the transaction status to the merchant.

PSP - transaction cancel flow (Optional)

The Partner API supports an optional transaction cancelation endpoint. This endpoint can be used by payment service providers who require users to explicitly cancel a pending transaction.

The endpoint is limited to canceling pending transactions and cannot be used to reverse successful transactions.

The endpoint that the payment service provider must expose must be in the following format:
<https://{{payment-service-provider-host}}/v1/cancel/{uniqueId}>

Transaction cancel steps:

1. The user chooses to pay using a payment service provider on the merchant website.
2. The Partner API sends a debit request to the payment service provider.
3. The payment service provider responds with the redirect URL where the user interface for the payment service provider platform is hosted.
4. The payment service provider user interface widget is displayed on the merchant's site for the users to interact with. During this step, all interactions with the user, for example, capturing second-factor authentication information like OTP, continues on the user interface screens between the user and the payment service provider.
5. The user clicks cancel on the merchant website to cancel the transaction.
6. The Partner API sends a POST /cancel/{uniqueId} request to the payment service provider.
7. The payment service provider processes the request and responds to the Partner API with the appropriate result code - 100.396.101 if successful.
8. The Partner API sends the final cancel status response for the transaction to the merchant.

📘

Note

A 404 HTTP status code should be returned if a cancel request is initiated and the payment service provider does not support cancel functionality.