Payment Return

The tutorials in the section provide examples of creating a payment return request using the PagoNxt Payments Hub API pacs.004.001.09 message format. For each tutorial example, the following sections must be completed.

Return the payment

This section describes how to return a payment via a pacs.004 HTTP request to the Payments Hub API. It also illustrates a successful response.

Request

Create and send a request using the following operation:

POST https://sandbox.api.pagonxt.com/payments/pacs004/v09

Headers

The request must contain the headers shown in the following table.

Values

Header name	Description	Required/ Optional	Values
X-Client-Id	Client ID	Required	<Client ID>
sca-token	SCA JWT bearer token: In the sandbox environment, you can use a predefined test SCA JWT Bearer token (see the Prerequisites section). In the live environment, you must create the token based on the message body (see tutorial) and sign it with your private key. For more information on the token details, see the Appendix in Authentication guide.

Header name

Description

Required/ Optional

Values

X-Client-Id

Client ID

Required

sca-token

SCA JWT bearer token:

In the sandbox environment, you can use a predefined test SCA JWT Bearer token (see the Prerequisites section).
In the live environment, you must create the token based on the message body (see tutorial) and sign it with your private key. For more information on the token details, see the Appendix in Authentication guide.

Request body

The request must include a JSON payload object in the request body. The JSON payload is a pacs.004 ISO message with the pmtRtr root element, and it contains the request details for returning a payment. The tutorials provide examples of commonly used fields. For details on all the required and optional message fields, see full field message definition pacs.004

Tutorials

SEPA Instant example

Response

If the request is valid, you receive an HTTP 201 Created response, which means that the payment return request was successfully submitted. In addition, the response body returns the data JSON object, which contains payment return details. If the request is submitted again with the same message ID, you receive an HTTP 200 OK response. For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling.

Element	Description	Data type
paymentsHubId	Payments Hub ID, which uniquely identifies your payment return request in Payments Hub. You can use it if you later need to retrieve the payment return details.	String
paymentId	Message ID you defined in the request as the grpHdr.msgId field value	String
status	Current status of the payment return. Since Payments Hub stores all requests for a while before performing the transaction settlement, this value is returned as PENDING.	String
creationDateTime	Date and time of creation	String

Example response body:

{
    "data": {
        "paymentsHubId": "01838244-f53a-35ff-b870-fd81c8f3b64d",
        "paymentId": "MsgId-6186662747",
        "status": "PENDING",
        "creationDateTime": "2022-06-09T11:23:09.6006"
    }
}