Reverse a card sale or a pre-authorization

An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).

If a customer requests a refund and the payment is still in an open batch, the merchant can use their POS to look up the card payment and cancel the transaction. To find the paymentId of the card payment that the merchant wants to reverse, they can retrieve a list of all the card payments that meet the search criteria that the merchant provides. They can then find the transaction that they want in the list of returned results.

Note: If the merchant runs a referenced refund on a bank transfer payment that is in an open batch, our gateway automatically reverses the payment.

Integration steps

Step 1. (Optional) List card payments.
Step 2. Reverse a card payment.

Before you begin

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

Step 1 (Optional) List payments

To retrieve a list of card payments, send a GET request to our Payments endpoint.

Use our filters to narrow down the search results.

Environment	URL
Test	https://api.uat.payroc.com/v1/payments
Production	https://api.payroc.com/v1/payments

Request parameters

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

Schema (`request.query`)

Query parameters for GET /payments

Example request

Request

GET https://api.payroc.com/v1/payments

Payment

curl

curl -G https://api.payroc.com/v1/payments \
     -H "Authorization: Bearer <token>" \
     -d after=8516 \
     -d before=2571 \
     --data-urlencode cardholderName=Sarah%20Hazel%20Hopper \
     --data-urlencode dateFrom=2024-07-01T15:30:00Z \
     --data-urlencode dateTo=2024-07-03T15:30:00Z \
     -d first6=453985 \
     -d last4=7062 \
     -d limit=25 \
     -d operator=Jane \
     -d orderId=OrderRef6543 \
     -d paymentLinkId=JZURRJBUPS \
     -d processingTerminalId=1234001 \
     -d settlementDate=2024-07-02 \
     -d settlementState=settled \
     -d status=accepted \
     -d status=ready \
     -d status=complete \
     -d tender=ebt \
     -d tipMode=noTip \
     -d tipMode=prompted \
     -d type=sale \
     -d type=preAuthorization

Payment

Python

import requests

url = "https://api.payroc.com/v1/payments"

querystring = {"after":"8516","before":"2571","cardholderName":"Sarah%20Hazel%20Hopper","dateFrom":"2024-07-01T15:30:00Z","dateTo":"2024-07-03T15:30:00Z","first6":"453985","last4":"7062","limit":"25","operator":"Jane","orderId":"OrderRef6543","paymentLinkId":"JZURRJBUPS","processingTerminalId":"1234001","settlementDate":"2024-07-02","settlementState":"settled","status":"[\"accepted\",\"ready\",\"complete\"]","tender":"ebt","tipMode":"[\"noTip\",\"prompted\"]","type":"[\"sale\",\"preAuthorization\"]"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

Payment

JavaScript

const url = 'https://api.payroc.com/v1/payments?after=8516&before=2571&cardholderName=Sarah%2520Hazel%2520Hopper&dateFrom=2024-07-01T15%3A30%3A00Z&dateTo=2024-07-03T15%3A30%3A00Z&first6=453985&last4=7062&limit=25&operator=Jane&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-02&settlementState=settled&status=%5B%22accepted%22%2C%22ready%22%2C%22complete%22%5D&tender=ebt&tipMode=%5B%22noTip%22%2C%22prompted%22%5D&type=%5B%22sale%22%2C%22preAuthorization%22%5D';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Payment

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/payments?after=8516&before=2571&cardholderName=Sarah%2520Hazel%2520Hopper&dateFrom=2024-07-01T15%3A30%3A00Z&dateTo=2024-07-03T15%3A30%3A00Z&first6=453985&last4=7062&limit=25&operator=Jane&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-02&settlementState=settled&status=%5B%22accepted%22%2C%22ready%22%2C%22complete%22%5D&tender=ebt&tipMode=%5B%22noTip%22%2C%22prompted%22%5D&type=%5B%22sale%22%2C%22preAuthorization%22%5D"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Payment

ruby

require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/payments?after=8516&before=2571&cardholderName=Sarah%2520Hazel%2520Hopper&dateFrom=2024-07-01T15%3A30%3A00Z&dateTo=2024-07-03T15%3A30%3A00Z&first6=453985&last4=7062&limit=25&operator=Jane&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-02&settlementState=settled&status=%5B%22accepted%22%2C%22ready%22%2C%22complete%22%5D&tender=ebt&tipMode=%5B%22noTip%22%2C%22prompted%22%5D&type=%5B%22sale%22%2C%22preAuthorization%22%5D")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Payment

Java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.payroc.com/v1/payments?after=8516&before=2571&cardholderName=Sarah%2520Hazel%2520Hopper&dateFrom=2024-07-01T15%3A30%3A00Z&dateTo=2024-07-03T15%3A30%3A00Z&first6=453985&last4=7062&limit=25&operator=Jane&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-02&settlementState=settled&status=%5B%22accepted%22%2C%22ready%22%2C%22complete%22%5D&tender=ebt&tipMode=%5B%22noTip%22%2C%22prompted%22%5D&type=%5B%22sale%22%2C%22preAuthorization%22%5D")
  .header("Authorization", "Bearer <token>")
  .asString();

Payment

PHP

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.payroc.com/v1/payments?after=8516&before=2571&cardholderName=Sarah%2520Hazel%2520Hopper&dateFrom=2024-07-01T15%3A30%3A00Z&dateTo=2024-07-03T15%3A30%3A00Z&first6=453985&last4=7062&limit=25&operator=Jane&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-02&settlementState=settled&status=%5B%22accepted%22%2C%22ready%22%2C%22complete%22%5D&tender=ebt&tipMode=%5B%22noTip%22%2C%22prompted%22%5D&type=%5B%22sale%22%2C%22preAuthorization%22%5D', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();

Payment

using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/payments?after=8516&before=2571&cardholderName=Sarah%2520Hazel%2520Hopper&dateFrom=2024-07-01T15%3A30%3A00Z&dateTo=2024-07-03T15%3A30%3A00Z&first6=453985&last4=7062&limit=25&operator=Jane&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-02&settlementState=settled&status=%5B%22accepted%22%2C%22ready%22%2C%22complete%22%5D&tender=ebt&tipMode=%5B%22noTip%22%2C%22prompted%22%5D&type=%5B%22sale%22%2C%22preAuthorization%22%5D");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);

Payment

swift

import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payments?after=8516&before=2571&cardholderName=Sarah%2520Hazel%2520Hopper&dateFrom=2024-07-01T15%3A30%3A00Z&dateTo=2024-07-03T15%3A30%3A00Z&first6=453985&last4=7062&limit=25&operator=Jane&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-02&settlementState=settled&status=%5B%22accepted%22%2C%22ready%22%2C%22complete%22%5D&tender=ebt&tipMode=%5B%22noTip%22%2C%22prompted%22%5D&type=%5B%22sale%22%2C%22preAuthorization%22%5D")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Response fields

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

Schema (`response.body`)

Response body schema for GET /payments

Example response

Response (200)

JSON

{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "paymentId": "M2MJOG6O2Y",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef6543",
        "amount": 4999,
        "currency": "USD",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Monthly Premium Club subscription"
      },
      "card": {
        "type": "Visa Credit",
        "cardNumber": "453985******7062",
        "expiryDate": "1230",
        "entryMethod": "keyed",
        "cardholderName": "Sarah Hopper",
        "secureToken": {
          "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
          "customerName": "Sarah Hopper",
          "token": "296753123456",
          "status": "notValidated",
          "link": {
            "rel": "self",
            "method": "GET",
            "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
          }
        },
        "securityChecks": {
          "cvvResult": "M",
          "avsResult": "X"
        }
      },
      "transactionResult": {
        "status": "ready",
        "responseCode": "A",
        "type": "sale",
        "approvalCode": "OK3",
        "authorizedAmount": 4999,
        "currency": "USD",
        "responseMessage": "APPROVAL"
      },
      "operator": "Automatic Payment",
      "supportedOperations": [
        "fullyReverse",
        "setAsPending"
      ]
    },
    {
      "paymentId": "E29U8OU8Q4",
      "processingTerminalId": "1234001",
      "order": {
        "orderId": "OrderRef7654",
        "amount": 4999,
        "currency": "USD",
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Monthly Premium Club subscription"
      },
      "card": {
        "type": "Visa Debit",
        "cardNumber": "453985******7062",
        "expiryDate": "1230",
        "entryMethod": "keyed",
        "cardholderName": "Sarah Hopper",
        "secureToken": {
          "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
          "customerName": "Sarah Hopper",
          "token": "296753123456",
          "status": "notValidated",
          "link": {
            "rel": "self",
            "method": "GET",
            "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
          }
        },
        "securityChecks": {
          "cvvResult": "M",
          "avsResult": "X"
        }
      },
      "transactionResult": {
        "status": "ready",
        "responseCode": "A",
        "type": "sale",
        "approvalCode": "475318",
        "authorizedAmount": 1000,
        "currency": "EUR",
        "responseMessage": "APPROVAL"
      },
      "operator": "Automatic Payment",
      "supportedOperations": [
        "fullyReverse",
        "setAsPending"
      ],
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/payments?processingTerminalId=1234001&limit=2&after=E29U8OU8Q4"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/payments?processingTerminalId=1234001&limit=2&before=M2MJOG6O2Y"
    }
  ]
}

Step 2. Reverse a payment

To reverse a card payment, send a POST request to our Reverse endpoint.

If the merchant wants to reverse only part of the transaction, send the amount that they want to reverse in the amount parameter.

Environment	URL
Test	https://api.uat.payroc.com/v1/payments/{paymentId}/reverse
Production	https://api.payroc.com/v1/payments/{paymentId}/reverse

Request parameters

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

Schema (`request.body`)

Request body schema for POST /payments/{paymentId}/reverse

Example request

Request

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

Reversal Payment

curl

curl -X POST https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "amount": 4999
}'

Reversal Payment

Python

import requests

url = "https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse"

payload = { "amount": 4999 }
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Reversal Payment

JavaScript

const url = 'https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"amount":4999}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Reversal Payment

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse"

	payload := strings.NewReader("{\n  \"amount\": 4999\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Reversal Payment

ruby

require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 4999\n}"

response = http.request(request)
puts response.read_body

Reversal Payment

Java

import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 4999\n}")
  .asString();

Reversal Payment

PHP

<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse', [
  'body' => '{
  "amount": 4999
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Reversal Payment

using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"amount\": 4999\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Reversal Payment

swift

import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["amount": 4999] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payments/M2MJOG6O2Y/reverse")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Response fields

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

Schema (`response.body`)

Response body schema for POST /payments/{paymentId}/reverse

Example response

Response (200)

JSON

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza"
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1230",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "transactionResult": {
    "status": "reversal",
    "responseCode": "A",
    "type": "sale",
    "approvalCode": "OK2",
    "authorizedAmount": 100,
    "currency": "USD",
    "responseMessage": "OK2"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "IT",
        "postalCode": "60056"
      }
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Test cases

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

Reverse a card payment

Send a POST request to the following endpoint:

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

Note: The previous payment must be in the open batch and not settled.

Example response

JSON

{
	"paymentId": "LRJ1QWEFRN",
	"processingTerminalId": "3204001",
	"operator": "notRequired",
	"order": {
		"orderId": "Test_007",
		"dateTime": "2023-05-25T10:39:10+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"
		}
	},
	"transactionResult": {
		"type": "sale",
		"status": "reversal",
		"approvalCode": "OK14866",
		"authorizedAmount": 4000,
		"currency": "USD",
		"responseCode": "A",
		"responseMessage": "OK14866",
		"cardSchemeReferenceId": "zz67WbxsEwMkvbSNcxz9"
	}
}

Integration steps

Before you begin

Step 1 (Optional) List payments

Request parameters

Schema (`request.query`)

Example request

Request

Response fields

Schema (`response.body`)

Example response

Response (200)

Step 2. Reverse a payment

Request parameters

Schema (`request.body`)

Example request

Request

Response fields

Schema (`response.body`)

Example response

Response (200)

Test cases

Reverse a card payment

Browse guides

Menu

Sign out

Talk to an engineer

Integration steps

Before you begin

Step 1 (Optional) List payments

Request parameters

Schema (request.query)

Example request

Request

Response fields

Schema (response.body)

Example response

Response (200)

Step 2. Reverse a payment

Request parameters

Schema (request.body)

Example request

Request

Response fields

Schema (response.body)

Example response

Response (200)

Test cases

Reverse a card payment

Schema (`request.query`)

Schema (`response.body`)

Schema (`request.body`)

Schema (`response.body`)