Returning payments with SEPA Instant Credit Transfer (pacs.004 and pacs.002)

08 Apr 2024
8 Minutes to read

Print
Share
Dark
Light

Returning payments with SEPA Instant Credit Transfer (pacs.004 and pacs.002)

Updated on 08 Apr 2024
8 Minutes to read

Print
Share
Dark
Light

Article Summary

Share feedback

Thanks for sharing your feedback!

This tutorial describes how you can return SEPA Instant Credit Transfer (SCT Inst) payments with the Payments Hub API.

For this tutorial, consider a scenario where you are a payment provider, and your merchant has a customer who purchases an item for which they accidently send a duplicate payment. The Payments Hub API can be used to return the money of the duplicate payment from the merchant to the customer’s account.

This tutorial describes, in 2 separate sections, how:

You can initiate a return for an SCT Inst payment using the ISO pacs.004 message.
You can retrieve the return status using the ISO pacs.002 message.

Note
The instructions in this tutorial apply to the sandbox environment.

Prerequisites

Before obtaining the access token, make sure you have a public-private key pair that you can use to sign JWT Bearer tokens.

Click here to email your public key, along with the kid and iss claim values you will use in your JWT Bearer tokens.

Note

The public key must be created with RSA and sent in PEM format, without password encryption, and must have a length of at least 2048 bits. If these criteria are not met, the token will be rejected.

If you don't have a public-private key pair yet, you can use a predefined JWT Bearer token in the sandbox with no need to create or sign your own tokens for authentication:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ikh1YnRlc3RfcHJvX3NhbmRib3gifQ.eyJzdWIiOiJxTWtaOTBxb0hBTjVJbkE2V2xNYVZBaE41dDhBQWVPeCIsImlzcyI6IlNhbnRhbmRlciIsImlhdCI6MTY2MTMyNzQyNSwibmJmIjoxNjYxMzI3NDI1LCJleHAiOjE2OTI4NjM0MjUsImp0aSI6IjRmMjM0ZmIxLWM3ODAtNGVhNS05YmI5LTBkMTZiYzU3MmFmNyJ9.lz19moa2xSUeBoz4-55qF15CY_LU-1Vb7bh14Q1pGjqR7hEL3OdxK9-EnWSP4eDMivMZWTHOXbFTj9WcH0eiX1u7fNJVVhyWTUqvIfI5Qcpal2j2pQElLe9mv7bytMGPbDpK-9kNqkuNX4J_LB7qLZJtPwSbsFtICORpLrBeMHwqWLRnaFVOMuiMM14CXG31YaKNVphowthVA_21CuE0P5Tl5iIlJIx0MENoq_pbmQpFkuN0VlxW7gv9Zrqo44Vd4TtoZiF4uY-PgbT3JDnbEe5pRa7C4vF-LHrdgfpNW9fjW9kut-ZuyeEIH240t6emstsdtcFAC18TpZjo9HM3sw

In the sandbox environment, you can use a predefined test SCA JWT Bearer token:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6IjA3SjlVSEFkY0krdTgyenp0VzhYME1FUWtCWC9zRFJlMHNnS05nUmg3R2c9Iiwibm9uY2UiOiI1N2I2NTI0MWNhOGVkNzg0NTZlZiIsImFsZyI6IlNIQTI1NiIsImlhdCI6MTcxMjMxMTg1NCwibmJmIjoxNzEyMzExODU0LCJleHAiOjE3NDM4NDc4NTQsImp0aSI6Ijk1ZjBiN2Y4LTJhNmMtNDc5Mi05NjQ5LTQwMDNlYjlhZDU5MSJ9.KMOYktVluCjl8AU8P8PlQBBkyyW0tNPfAo4l-V0auDsIF0euag7t9n75vYaTUPiOvXQG6u2IkVUVc90J1Xhx7OymGxxImbyI1FeaADCbFu9m61Hq_KY03yidHe0zzDBGt2gbZc47KxSQ9EW0aSt2-YjNMKDmFNVHfXVbbYC7T1EiFLlAH-4-jUOqpDoLrvYngr0PRL010Rc5YGCzTtZKVO2HYlfjUNj5JDbRADzsTWwwR7sPpGNFIX24uwmMPz9JwaY4yC690tZTCvx4Cf1uIqOvI0TchiL2tqDzpIWJwULuiOichc3iCbHmOPbxox4D76XPeuy_DBTG_apSDbZNZA

1. Authenticate to get an access token

The Payments Hub API endpoints are protected with OAuth 2.0 JWT Bearer grant. To use the API, you must create a JWT Bearer token and use it to get an access token:

To create a JWT Bearer token, see the Appendix in Authentication guide . For a predefined token that you can use in the sandbox for testing purposes, see the Prerequisites in Authentication guide .
For detailed instructions on how to get the access token, see Authentication guide .

2. 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.apis.santander.com/payments/pacs004/v09

Headers

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

Table: Return the payment - Required request headers

Header name	Description	Required/ Optional	Values
Authorization	Authorization security header	Required	Bearer <Access token>
X-Santander-Client-Id	Client ID	Required	<Client ID>
Content-Type	Format of the request body	Required	application/json
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 (whose details are described below) and sign it with your private key. For more information on the token details, see the Appendix in Authentication guide .	Required	<SCA token>
Accept	Format of the response body	Required	application/json

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 following table only provides information about some especially important fields. For details on all the required and optional message fields, see Message field definition for pacs.004 .

Table: Return the payment - Relevant request body elements

Message field	Description	Data type	Required/Optional
grpHdr.msgId	Message ID, which must uniquely identify each request you send. This ID is used internally for idempotency of the API.	String	Required
grpHdr.creDtTm	Date and time of the payment return request	String	Required
grpHdr.nbOfTxs	Number of transactions within the message. Value: 1	Number	Required
grpHdr.sttlmInf.sttlmMtd	Settlement method. Value: CLRG	String	Required
txInf.rtrId	Unique payment return ID for the end customer	String	Required
txInf.rtrdIntrBkSttlmAmt	Data structure containing the payment currency and the amount to be returned. The currency must be EUR and the amount must be a positive value.	Object	Required
txInf.chrgBr	Charge bearer type. Value: SLEV	String	Required
txInf.rtrRsnInf.rsn.cd	Code for the payment reversal	String	Required
txInf.orgnlTxRef	Data structure containing the transaction reference used to identify the original transaction	Object	Required

Example request body:

{
    "pmtRtr": {
        "grpHdr": {
            "msgId": "MsgId-6186662747",
            "creDtTm": "2022-03-09T16:30:22.868+01:00",
            "nbOfTxs": "1",
            "sttlmInf": {
                "sttlmMtd": "CLRG"
            }
        },
        "txInf": [
            {
                "rtrId": "transactionId-6186662747",
                "rtrdIntrBkSttlmAmt": {
                    "value": 10.04,
                    "ccy": "EUR"
                },
                "intrBkSttlmDt": "2020-12-16",
                "chrgBr": "SLEV",
                "instgAgt": {
                    "finInstnId": {
                        "bicfi": "ABBYGB20XXX"
                    }
                },
                "instdAgt": {
                    "finInstnId": {
                        "bicfi": "BSCHESM0XXX"
                    }
                },
                "rtrRsnInf": [
                    {
                        "rsn": {
                            "cd": "AC01"
                        },
                        "addtlInf": [
                            "raw-code",
                            "raw-description"
                        ]
                    }
                ],
                "orgnlTxRef": {
                    "pmtTpInf": {
                        "svcLvl": [
                            {
                                "prtry": "SCT_INST"
                            }
                        ],
                        "lclInstrm": {
                            "prtry": "TRF"
                        }
                    },
                    "dbtr": {
                        "pty": {
                            "nm": "Debtor",
                            "pstlAdr": {
                                "twnNm": "Madrid",
                                "ctry": "ES",
                                "adrLine": [
                                    "Somewhere in Madrid"
                                ]
                            },
                            "id": {
                                "prvtId": {
                                    "othr": [
                                        {
                                            "id": "F99999"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "dbtrAcct": {
                        "id": {
                            "othr": {
                                "id": "12345678"
                            }
                        }
                    },
                    "dbtrAgt": {
                        "finInstnId": {
                            "bicfi": "ABBYGB20",
                            "clrSysMmbId": {
                                "mmbId": "777241"
                            }
                        }
                    },
                    "cdtrAgt": {
                        "finInstnId": {
                            "bicfi": "BSCHPTM0XXX",
                            "pstlAdr": {
                                "twnNm": "Lisbon",
                                "ctry": "PT",
                                "adrLine": [
                                    "Somewhere in Lisbon"
                                ]
                            }
                        }
                    },
                    "cdtrAcct": {
                        "id": {
                            "iban": "PT91BARC20032634945865"
                        },
                        "ccy": "EUR"
                    }
                }
            }
        ]
    }
}

Request example

The following example illustrates the request using raw HTTP code:

POST /payments/pacs004/v09 HTTP/1.1
Host: sandbox.apis.santander.com
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Santander-Client-Id: YOUR_CLIENT_ID
sca-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6InByb1BheW1lbnRzSHViU2IifQ.eyJoZCI6IjA3SjlVSEFkY0krdTgyenp0VzhYME1FUWtCWC9zRFJlMHNnS05nUmg3R2c9Iiwibm9uY2UiOiI1N2I2NTI0MWNhOGVkNzg0NTZlZiIsImFsZyI6IlNIQTI1NiIsImlhdCI6MTcxMjMxMTg1NCwibmJmIjoxNzEyMzExODU0LCJleHAiOjE3NDM4NDc4NTQsImp0aSI6Ijk1ZjBiN2Y4LTJhNmMtNDc5Mi05NjQ5LTQwMDNlYjlhZDU5MSJ9.KMOYktVluCjl8AU8P8PlQBBkyyW0tNPfAo4l-V0auDsIF0euag7t9n75vYaTUPiOvXQG6u2IkVUVc90J1Xhx7OymGxxImbyI1FeaADCbFu9m61Hq_KY03yidHe0zzDBGt2gbZc47KxSQ9EW0aSt2-YjNMKDmFNVHfXVbbYC7T1EiFLlAH-4-jUOqpDoLrvYngr0PRL010Rc5YGCzTtZKVO2HYlfjUNj5JDbRADzsTWwwR7sPpGNFIX24uwmMPz9JwaY4yC690tZTCvx4Cf1uIqOvI0TchiL2tqDzpIWJwULuiOichc3iCbHmOPbxox4D76XPeuy_DBTG_apSDbZNZA
Content-Length: 3780

{
    "pmtRtr": {
        "grpHdr": {
            "msgId": "MsgId-6186662747",
            "creDtTm": "2022-03-09T16:30:22.868+01:00",
            "nbOfTxs": "1",
            "sttlmInf": {
                "sttlmMtd": "CLRG"
            }
        },
        "txInf": [
            {
                "rtrId": "transactionId-6186662747",
                "rtrdIntrBkSttlmAmt": {
                    "value": 10.04,
                    "ccy": "EUR"
                },
                "intrBkSttlmDt": "2020-12-16",
                "chrgBr": "SLEV",
                "instgAgt": {
                    "finInstnId": {
                        "bicfi": "ABBYGB20XXX"
                    }
                },
                "instdAgt": {
                    "finInstnId": {
                        "bicfi": "BSCHESM0XXX"
                    }
                },
                "rtrRsnInf": [
                    {
                        "rsn": {
                            "cd": "AC01"
                        },
                        "addtlInf": [
                            "raw-code",
                            "raw-description"
                        ]
                    }
                ],
                "orgnlTxRef": {
                    "pmtTpInf": {
                        "svcLvl": [
                            {
                                "prtry": "SCT_INST"
                            }
                        ],
                        "lclInstrm": {
                            "prtry": "TRF"
                        }
                    },
                    "dbtr": {
                        "pty": {
                            "nm": "Debtor",
                            "pstlAdr": {
                                "twnNm": "Madrid",
                                "ctry": "ES",
                                "adrLine": [
                                    "Somewhere in Madrid"
                                ]
                            },
                            "id": {
                                "prvtId": {
                                    "othr": [
                                        {
                                            "id": "F99999"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "dbtrAcct": {
                        "id": {
                            "othr": {
                                "id": "12345678"
                            }
                        }
                    },
                    "dbtrAgt": {
                        "finInstnId": {
                            "bicfi": "ABBYGB20",
                            "clrSysMmbId": {
                                "mmbId": "777241"
                            }
                        }
                    },
                    "cdtrAgt": {
                        "finInstnId": {
                            "bicfi": "BSCHPTM0XXX",
                            "pstlAdr": {
                                "twnNm": "Lisbon",
                                "ctry": "PT",
                                "adrLine": [
                                    "Somewhere in Lisbon"
                                ]
                            }
                        }
                    },
                    "cdtrAcct": {
                        "id": {
                            "iban": "PT91BARC20032634945865"
                        },
                        "ccy": "EUR"
                    }
                }
            }
        ]
    }
}

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.

The following table shows the response body elements that are relevant for the current use case. For details on all the response body elements, see Message field definition for pacs.004.

Table: Return the payment - Relevant response body elements

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

Extract the value of the paymentsHubId key, as you'll need it in the next section.

Example response body:

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

3. Retrieve the payment return status

This section describes how to retrieve the payment return status via a pacs.002 HTTP request to the Payments Hub API. To send this request, you need to provide the Payments Hub ID that you received in the response to the pacs.004 HTTP request sent in the previous section, or that was provided in the notification (if you have it enabled for pacs.004 requests). For information, see Notifications . This section also illustrates a successful response.

Note
Notifications are not used in the sandbox environment.

Request

Create and send a request using the following operation:

GET https://sandbox.apis.santander.com/payments/pacs002/v10/{paymentsHubId}

Headers

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

Table: Retrieve the payment return status - Required request headers

Header name	Description	Required/Optional	Values
Authorization	Authorization security header	Required	Bearer <Access token>
X-Santander-Client-Id	Client ID	Required	<Client ID>
Accept	Format of the response body	Required	application/json

Parameters

The request must contain the path parameter shown in the following table.

Table: Retrieve the payment return status - Request parameter

Parameter type	Parameter name	Description	Data format	Required/Optional
Path	paymentsHubId	Payments Hub ID related to the payment return, received in the response to the pacs.004 request	String	Required

Request example

The following example illustrates the request using raw HTTP code:

GET /payments/pacs002/v10/YOUR_PAYMENTS_HUB_ID HTTP/1.1
Host: sandbox.apis.santander.com
Authorization: Bearer YOUR_ACCESS_TOKEN
X-Santander-Client-Id: YOUR_CLIENT_ID

Response

If the request is valid, you receive an HTTP 200 OK response, which means that the payment return status was successfully retrieved. For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling. In addition to the response code, the response body returns the fIToFIPmtStsRpt JSON object, which contains a pacs.002 ISO message.

The following table shows the response body elements that are relevant for the current use case. For details on all the response body elements, see Message field definition for pacs.002 .

Table: Retrieve the payment return status – Relevant response body elements

Element	Description	Data type
txInfAndSts.txSts	Payment return status. The possible values are based on the ISO standard. For example: ACCC (accepted) or RJTC (rejected). For more information on the status and the related codes that provide the reason for the payment acceptance or rejection, see Payment status and codes .	String

Element

Description

Data type

txInfAndSts.txSts

Payment return status.

The possible values are based on the ISO standard. For example: ACCC (accepted) or RJTC (rejected).

For more information on the status and the related codes that provide the reason for the payment acceptance or rejection, see Payment status and codes .

String

Extract the value of the txInfAndSts.txSts key to see the payment return status.

Example response body:

{
    "fitoFIPmtStsRpt": {
        "grpHdr": {
            "msgId": "3c5a5b71ce73414d8c5a3e03bc7ab798",
            "creDtTm": "2022-06-09T11:23:09.620Z"
        },
        "txInfAndSts": [
            {
                "orgnlGrpInf": {
                    "orgnlMsgId": "MsgId-6186662747",
                    "orgnlMsgNmId": "pacs.004.001.09"
                },
                "orgnlTxId": "transactionId-6186662747",
                "txSts": "ACCC",
                "stsRsnInf": [
                    {
                        "addtlInf": [
                            null,
                            null,
                            "SCT_INST:transactionId-6186662747",
                            null
                        ]
                    }
                ],
                "orgnlTxRef": {
                    "pmtTpInf": {
                        "svcLvl": [
                            {
                                "prtry": "SCT_INST"
                            }
                        ]
                    },
                    "rmtInf": {
                        "strd": [
                            {
                                "addtlRmtInf": [
                                    "transactionId-6186662747"
                                ]
                            }
                        ]
                    }
                }
            }
        ]
    }
}