Prerequisites: Authentication
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
Authenticate your requests before making API calls. If your request fails, see Errors.
Step 1. Refund the payment
To refund a card transfer payment, send a POST request to the Refund endpoint.
| Environment | URL |
|---|---|
| Test | https://api.uat.payroc.com/v1/refunds |
| Production | https://api.payroc.com/v1/refunds |
Request parameters
To create the body of your request, use the following parameters:
Schema (request.body)
Request body schema for POST /refunds
Example request
Request
POST https://api.payroc.com/v1/refunds
Refund
curl -X POST https://api.payroc.com/v1/refunds \
-H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"channel": "pos",
"processingTerminalId": "1234001",
"order": {
"orderId": "OrderRef6543",
"description": "Refund for order OrderRef6543",
"amount": 4999,
"currency": "USD"
},
"refundMethod": {
"type": "card",
"cardDetails": {
"entryMethod": "keyed",
"keyedData": {
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"device": {
"model": "paxA920",
"serialNumber": "1850010868"
},
"expiryDate": "1230"
}
}
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}'
Refund
import requests
url = "https://api.payroc.com/v1/refunds"
payload = {
"channel": "pos",
"processingTerminalId": "1234001",
"order": {
"orderId": "OrderRef6543",
"description": "Refund for order OrderRef6543",
"amount": 4999,
"currency": "USD"
},
"refundMethod": {
"type": "card",
"cardDetails": {
"entryMethod": "keyed",
"keyedData": {
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"device": {
"model": "paxA920",
"serialNumber": "1850010868"
},
"expiryDate": "1230"
}
}
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}
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())
Refund
const url = 'https://api.payroc.com/v1/refunds';
const options = {
method: 'POST',
headers: {
'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: '{"channel":"pos","processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","description":"Refund for order OrderRef6543","amount":4999,"currency":"USD"},"refundMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","device":{"model":"paxA920","serialNumber":"1850010868"},"expiryDate":"1230"}}},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
Refund
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.payroc.com/v1/refunds"
payload := strings.NewReader("{\n \"channel\": \"pos\",\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"description\": \"Refund for order OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"refundMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"device\": {\n \"model\": \"paxA920\",\n \"serialNumber\": \"1850010868\"\n },\n \"expiryDate\": \"1230\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\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))
}
Refund
require 'uri'
require 'net/http'
url = URI("https://api.payroc.com/v1/refunds")
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 \"channel\": \"pos\",\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"description\": \"Refund for order OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"refundMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"device\": {\n \"model\": \"paxA920\",\n \"serialNumber\": \"1850010868\"\n },\n \"expiryDate\": \"1230\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
Refund
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/refunds")
.header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"channel\": \"pos\",\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"description\": \"Refund for order OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"refundMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"device\": {\n \"model\": \"paxA920\",\n \"serialNumber\": \"1850010868\"\n },\n \"expiryDate\": \"1230\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}")
.asString();
Refund
<?php
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.payroc.com/v1/refunds', [
'body' => '{
"channel": "pos",
"processingTerminalId": "1234001",
"order": {
"orderId": "OrderRef6543",
"description": "Refund for order OrderRef6543",
"amount": 4999,
"currency": "USD"
},
"refundMethod": {
"type": "card",
"cardDetails": {
"entryMethod": "keyed",
"keyedData": {
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"device": {
"model": "paxA920",
"serialNumber": "1850010868"
},
"expiryDate": "1230"
}
}
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}',
'headers' => [
'Authorization' => 'Bearer <token>',
'Content-Type' => 'application/json',
'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
],
]);
echo $response->getBody();
Refund
using RestSharp;
var client = new RestClient("https://api.payroc.com/v1/refunds");
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 \"channel\": \"pos\",\n \"processingTerminalId\": \"1234001\",\n \"order\": {\n \"orderId\": \"OrderRef6543\",\n \"description\": \"Refund for order OrderRef6543\",\n \"amount\": 4999,\n \"currency\": \"USD\"\n },\n \"refundMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"device\": {\n \"model\": \"paxA920\",\n \"serialNumber\": \"1850010868\"\n },\n \"expiryDate\": \"1230\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Refund
import Foundation
let headers = [
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
]
let parameters = [
"channel": "pos",
"processingTerminalId": "1234001",
"order": [
"orderId": "OrderRef6543",
"description": "Refund for order OrderRef6543",
"amount": 4999,
"currency": "USD"
],
"refundMethod": [
"type": "card",
"cardDetails": [
"entryMethod": "keyed",
"keyedData": [
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"device": [
"model": "paxA920",
"serialNumber": "1850010868"
],
"expiryDate": "1230"
]
]
],
"customFields": [
[
"name": "yourCustomField",
"value": "abc123"
]
]
] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/refunds")! 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 refund the card transfer payment and return a response. The response contains the following fields:
Schema (response.body)
Response body schema for POST /refunds
Example response
Response (201)
{
"refundId": "CD3HN88U9F",
"processingTerminalId": "1234001",
"order": {
"orderId": "OrderRef6543",
"description": "Refund for order OrderRef6543",
"amount": 4999,
"currency": "USD",
"dateTime": "2024-07-02T15:30:00Z"
},
"card": {
"type": "Visa Credit",
"cardNumber": "453985******7062",
"expiryDate": "1230",
"entryMethod": "keyed"
},
"transactionResult": {
"status": "ready",
"responseCode": "A",
"type": "refund",
"approvalCode": "000000",
"authorizedAmount": -4999,
"currency": "USD",
"responseMessage": "OK5"
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}