Run an unreferenced refund for a card payment

A merchant can return a payment to a customer’s card without a paymentId by running an unreferenced refund.

Integration steps

Step 1. 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.

Note: You need to generate a new Bearer token before the previous Bearer token expires.

Example request

$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.

1{
2 "access_token": "eyJhbGc....adQssw5c",
3 "expires_in": 3600,
4 "scope": "service_a service_b",
5 "token_type": "Bearer"
6}

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.
$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.

Step 1. Refund the payment

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

Request parameters

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

Example request

POST
/v1/refunds
1curl -X POST https://api.payroc.com/v1/refunds \
2 -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3 -H "Authorization: Bearer <token>" \
4 -H "Content-Type: application/json" \
5 -d '{
6 "channel": "pos",
7 "processingTerminalId": "1234001",
8 "order": {
9 "orderId": "OrderRef6543",
10 "description": "Refund for order OrderRef6543",
11 "amount": 4999,
12 "currency": "USD"
13 },
14 "refundMethod": {
15 "type": "card",
16 "cardDetails": {
17 "entryMethod": "keyed",
18 "keyedData": {
19 "dataFormat": "plainText",
20 "device": {
21 "model": "paxA920",
22 "serialNumber": "1850010868"
23 },
24 "cardNumber": "4539858876047062",
25 "expiryDate": "1225"
26 }
27 }
28 },
29 "customFields": [
30 {
31 "name": "yourCustomField",
32 "value": "abc123"
33 }
34 ]
35}'

Response fields

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

Example response

Response
1{
2 "refundId": "CD3HN88U9F",
3 "processingTerminalId": "1234001",
4 "order": {
5 "orderId": "OrderRef6543",
6 "description": "Refund for order OrderRef6543",
7 "amount": 4999,
8 "currency": "USD",
9 "dateTime": "2024-07-02T15:30:00Z"
10 },
11 "card": {
12 "type": "Visa Credit",
13 "entryMethod": "keyed",
14 "cardNumber": "453985******7062",
15 "expiryDate": "1225"
16 },
17 "transactionResult": {
18 "type": "refund",
19 "status": "ready",
20 "responseCode": "A",
21 "responseMessage": "OK5",
22 "approvalCode": "000000",
23 "authorizedAmount": -4999,
24 "currency": "USD"
25 },
26 "customFields": [
27 {
28 "name": "yourCustomField",
29 "value": "abc123"
30 }
31 ]
32}