Run a referenced refund for a card payment

A merchant can use the payment details of a card payment to run a referenced refund. To run a referenced refund, the merchant should first retrieve the payment information in one of the following ways:

• Use the paymentId.
• Search for the payment using payment information such as the card number.

Integration steps

Step 1. Retrieve information about the original payment.
(Optional) Step 1a. Retrieve information about the payment using the paymentId.
(Optional) Step 1b. Retrieve information about the payment without the paymentId.
Step 2. Refund the payment.

Before you begin

Authenticate your requests before making API calls. If your request fails, see Errors.

Step 1. Retrieve information about the original payment

1a – (Optional) Retrieve information with the paymentId

Send a GET request with the paymentID to the Payments endpoint.

Example request

Response fields

If your request is successful, we retrieve the card payment information and return a response. The response contains the following fields:

Example response

1b (Optional) – Retrieve information without the payment ID

Send a GET request to the Payments endpoint.

Request parameters

To create the body of your request, use the following parameters:

Example request

Response fields

If your request is successful, we retrieve a list of card payments and return a response. The response contains the following fields:

Example response

Step 2. Refund the payment

To refund a card transfer payment, send a POST request to the Payments endpoint.

Request parameters

To create the body of your request, use the following parameters:

Example request

Response fields

If your request is successful, we refund the card payment and return a response. The response contains the following fields:

Example response

Test cases

Before you run test cases, read the Payments page in Test Your Integration.

Refund a card payment

Send a POST request to the following endpoint:

POST https://api.uat.payroc.com/v1/payments/{paymentId}/refund

Example response

1
{
2
	"paymentId": "C8Y177VHWR",
3
	"processingTerminalId": "3204001",
4
	"order": {
5
		"orderId": "Test_006",
6
		"dateTime": "2023-05-24T15:21:01+01:00",
7
		"amount": 4000,
8
		"currency": "USD",
9
		"standingInstructions": {
10
			"sequence": "subsequent",
11
			"processingModel": "recurring"
12
		}
13
	},
14
	"card": {
15
		"type": "Visa Credit",
16
		"entryMethod": "keyed",
17
		"cardNumber": "444433******1111",
18
		"expiryDate": "1226",
19
		"secureToken": {
20
			"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
21
			"customerName": "",
22
			"token": "2967538502417872",
23
			"status": "cvv_validated",
24
			"link": {
25
				"rel": "self",
26
				"method": "GET",
27
				"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
28
			}
29
		},
30
		"securityChecks": {
31
			"cvvResult": "M",
32
			"avsResult": "Y"
33
		}
34
	},
35
	"refunds": [
36
		{
37
			"refundId": "G6T6S6KF74",
38
			"dateTime": "2023-05-25T11:12:55+01:00",
39
			"amount": -4000,
40
			"currency": "USD",
41
			"status": "ready",
42
			"link": {
43
				"rel": "self",
44
				"method": "GET",
45
				"href": "https://api.uat.payroc.com/v1/refunds/G6T6S6KF74"
46
			}
47
		}
48
	],
49
	"transactionResult": {
50
		"type": "sale",
51
		"status": "ready",
52
		"approvalCode": "OK14486",
53
		"authorizedAmount": 4000,
54
		"currency": "USD",
55
		"responseCode": "A",
56
		"responseMessage": "OK14486",
57
		"cardSchemeReferenceId": "JxDfFMHyOE2lyQJ2MnFp"
58
	}
59
}