***

title: Run a referenced refund for a card payment
icon: reply
published: true
intro: Return funds to a customer's account with a paymentId.
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.payroc.com/full-stack-guides/take-payments/payments/refunds/referenced-refunds/llms.txt. For full documentation content, see https://docs.payroc.com/full-stack-guides/take-payments/payments/refunds/referenced-refunds/llms-full.txt.

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.

<Note>
  **Note:** If the merchant runs a refund on a payment that is in an open batch, our gateway automatically cancels the payment.
</Note>

## 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

### Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:

1. Include your API key in the x-api-key parameter in the header of a POST request.
2. Send your request to [https://identity.payroc.com/authorize](https://identity.payroc.com/authorize).

<Note>
  **Note:** You need to generate a new Bearer token before the previous Bearer token expires.
</Note>

#### Example request

```bash
curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'
```

#### Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

```json
{
  "access_token": "eyJhbGc....adQssw5c",
  "expires_in": 3600,
  "scope": "service_a service_b",
  "token_type": "Bearer"
}
```

### Headers

To create the header of each POST request, you must include the following parameters:

* **Content-Type:** Include application/json as the value for this parameter.
* **Authorization:** Include your Bearer token in this parameter.
* **Idempotency-Key:** Include a UUID v4 to make the request idempotent.

```bash
curl
-H "Content-Type: application/json"
-H "Authorization: <Bearer token>"
-H "Idempotency-Key: <UUID v4>"
```

### Errors

If your request is unsuccessful, we return an error. For more information about errors, see [Errors](/api/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.

| Endpoint   | Prefix     | URL                                                                                                        |
| :--------- | :--------- | :--------------------------------------------------------------------------------------------------------- |
| Test       | `api.uat.` | [https://api.uat.payroc.com/v1/payments/\{paymentId}](https://api.uat.payroc.com/v1/payments/\{paymentId}) |
| Production | `api.`     | [https://api.payroc.com/v1/payments/\{paymentId}](https://api.payroc.com/v1/payments/\{paymentId})         |

<EndpointSchemaSnippet endpoint="GET /payments/{paymentId}" selector="request.path" />

### Example request

<EndpointRequestSnippet endpoint="GET /payments/{paymentId}" />

### Response fields

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

<EndpointSchemaSnippet endpoint="POST /bank-transfer-payments{paymentId}/refund" selector="response.body" />

### Example response

<EndpointResponseSnippet endpoint="GET /payments/{paymentId}" />

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

Send a GET request to the Payments endpoint.

| Endpoint   | Prefix     | URL                                                                              |
| :--------- | :--------- | :------------------------------------------------------------------------------- |
| Test       | `api.uat.` | [https://api.uat.payroc.com/v1/payments](https://api.uat.payroc.com/v1/payments) |
| Production | `api.`     | [https://api.payroc.com/v1/payments](https://api.payroc.com/v1/payments)         |

### Request parameters

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

<EndpointSchemaSnippet endpoint="GET /payments" selector="request.path" />

### Example request

<EndpointRequestSnippet endpoint="GET /payments" />

### Response fields

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

<EndpointSchemaSnippet endpoint="GET /payments" selector="response.body" />

### Example response

<EndpointResponseSnippet endpoint="GET /payments" />

## Step 2. Refund the payment

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

| Endpoint   | Prefix     | URL                                                                                                                      |
| :--------- | :--------- | :----------------------------------------------------------------------------------------------------------------------- |
| Test       | `api.uat.` | [https://api.uat.payroc.com/v1/payments/\{paymentId}/refund](https://api.uat.payroc.com/v1/payments/\{paymentId}/refund) |
| Production | `api.`     | [https://api.payroc.com/v1/payments/\{paymentId}/refund](https://api.payroc.com/v1/payments/\{paymentId}/refund)         |

### Request parameters

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

<EndpointSchemaSnippet endpoint="POST /payments/{paymentId}/refund" selector="request.body" />

### Example request

<EndpointRequestSnippet endpoint="POST /payments/{paymentId}/refund" />

### Response fields

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

<EndpointSchemaSnippet endpoint="POST /payments/{paymentId}/refund" selector="response.body" />

### Example response

<EndpointResponseSnippet endpoint="POST /payments/{paymentId}/refund" example="refundPayment" />

## Test cases

Before you run test cases, read the [Payments](/test/test-your-integration/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](https://api.uat.payroc.com/v1/payments/\{paymentId}/refund)

<Note>
  **Note:** To settle a payment, the terminal must first close the batch and then our gateway settles the payments within an hour. To adjust when the terminal closes a batch, use the terminal settings in the Merchant Portal.
</Note>

**Example response**

```json
{
	"paymentId": "C8Y177VHWR",
	"processingTerminalId": "3204001",
	"order": {
		"orderId": "Test_006",
		"dateTime": "2023-05-24T15:21:01+01:00",
		"amount": 4000,
		"currency": "USD",
		"standingInstructions": {
			"sequence": "subsequent",
			"processingModel": "recurring"
		}
	},
	"card": {
		"type": "Visa Credit",
		"entryMethod": "keyed",
		"cardNumber": "444433******1111",
		"expiryDate": "1226",
		"secureToken": {
			"secureTokenId": "MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA",
			"customerName": "",
			"token": "2967538502417872",
			"status": "cvv_validated",
			"link": {
				"rel": "self",
				"method": "GET",
				"href": "https://api.uat.payroc.com/v1/processing-terminals/3204001/secure-tokens/MREF_1a93f3a6-9029-419f-9e87-3e2db6f0ae85uA"
			}
		},
		"securityChecks": {
			"cvvResult": "M",
			"avsResult": "Y"
		}
	},
	"refunds": [
		{
			"refundId": "G6T6S6KF74",
			"dateTime": "2023-05-25T11:12:55+01:00",
			"amount": -4000,
			"currency": "USD",
			"status": "ready",
			"link": {
				"rel": "self",
				"method": "GET",
				"href": "https://api.uat.payroc.com/v1/refunds/G6T6S6KF74"
			}
		}
	],
	"transactionResult": {
		"type": "sale",
		"status": "ready",
		"approvalCode": "OK14486",
		"authorizedAmount": 4000,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK14486",
		"cardSchemeReferenceId": "JxDfFMHyOE2lyQJ2MnFp"
	}
}

```