Skip to content
payrocdevelopers

Send an unreferenced refund to a customer’s bank account

Send an unreferenced refund to a customer's bank account by posting to the Bank Transfer Refunds endpoint without a paymentId.

Prerequisites: Authentication

Note: Only certain merchant accounts can send unreferenced refunds.

A merchant can refund a payment to a customer's bank account 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 bank transfer payment, send a POST request to the Bank Transfer Refunds endpoint.

EnvironmentURL
Testhttps://api.uat.payroc.com/v1/bank-transfer-refunds
Productionhttps://api.payroc.com/v1/bank-transfer-refunds

Request parameters

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

Schema (request.body)

Request body schema for POST /bank-transfer-refunds

Example request

Request

POST https://api.payroc.com/v1/bank-transfer-refunds

Bank Transfer Unreferenced Refund

curl
curl -X POST https://api.payroc.com/v1/bank-transfer-refunds \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "refundMethod": {
    "type": "ach",
    "accountNumber": "1234567890",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "123456789",
    "accountType": "checking",
    "secCode": "web"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}'

Bank Transfer Unreferenced Refund

Python
import requests

url = "https://api.payroc.com/v1/bank-transfer-refunds"

payload = {
    "processingTerminalId": "1234001",
    "order": {
        "orderId": "OrderRef6543",
        "description": "Refund for order OrderRef6543",
        "amount": 4999,
        "currency": "USD"
    },
    "refundMethod": {
        "type": "ach",
        "accountNumber": "1234567890",
        "nameOnAccount": "Sarah Hazel Hopper",
        "routingNumber": "123456789",
        "accountType": "checking",
        "secCode": "web"
    },
    "customer": {
        "notificationLanguage": "en",
        "contactMethods": [
            {
                "type": "email",
                "value": "sarah.hopper@example.com"
            }
        ]
    },
    "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())

Bank Transfer Unreferenced Refund

JavaScript
const url = 'https://api.payroc.com/v1/bank-transfer-refunds';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","description":"Refund for order OrderRef6543","amount":4999,"currency":"USD"},"refundMethod":{"type":"ach","accountNumber":"1234567890","nameOnAccount":"Sarah Hazel Hopper","routingNumber":"123456789","accountType":"checking","secCode":"web"},"customer":{"notificationLanguage":"en","contactMethods":[{"type":"email","value":"sarah.hopper@example.com"}]},"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);
}

Bank Transfer Unreferenced Refund

go
package main

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

func main() {

	url := "https://api.payroc.com/v1/bank-transfer-refunds"

	payload := strings.NewReader("{\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\": \"ach\",\n    \"accountNumber\": \"1234567890\",\n    \"nameOnAccount\": \"Sarah Hazel Hopper\",\n    \"routingNumber\": \"123456789\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\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))

}

Bank Transfer Unreferenced Refund

ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/bank-transfer-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  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"orderId\": \"OrderRef6543\",\n    \"description\": \"Refund for order OrderRef6543\",\n    \"amount\": 4999,\n    \"currency\": \"USD\"\n  },\n  \"refundMethod\": {\n    \"type\": \"ach\",\n    \"accountNumber\": \"1234567890\",\n    \"nameOnAccount\": \"Sarah Hazel Hopper\",\n    \"routingNumber\": \"123456789\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\n      }\n    ]\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}"

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

Bank Transfer Unreferenced Refund

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

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/bank-transfer-refunds")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\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\": \"ach\",\n    \"accountNumber\": \"1234567890\",\n    \"nameOnAccount\": \"Sarah Hazel Hopper\",\n    \"routingNumber\": \"123456789\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\n      }\n    ]\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}")
  .asString();

Bank Transfer Unreferenced Refund

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/bank-transfer-refunds', [
  'body' => '{
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  },
  "refundMethod": {
    "type": "ach",
    "accountNumber": "1234567890",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "123456789",
    "accountType": "checking",
    "secCode": "web"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Bank Transfer Unreferenced Refund

C#
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/bank-transfer-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  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"orderId\": \"OrderRef6543\",\n    \"description\": \"Refund for order OrderRef6543\",\n    \"amount\": 4999,\n    \"currency\": \"USD\"\n  },\n  \"refundMethod\": {\n    \"type\": \"ach\",\n    \"accountNumber\": \"1234567890\",\n    \"nameOnAccount\": \"Sarah Hazel Hopper\",\n    \"routingNumber\": \"123456789\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\n      }\n    ]\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Bank Transfer Unreferenced Refund

swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "processingTerminalId": "1234001",
  "order": [
    "orderId": "OrderRef6543",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD"
  ],
  "refundMethod": [
    "type": "ach",
    "accountNumber": "1234567890",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "123456789",
    "accountType": "checking",
    "secCode": "web"
  ],
  "customer": [
    "notificationLanguage": "en",
    "contactMethods": [
      [
        "type": "email",
        "value": "sarah.hopper@example.com"
      ]
    ]
  ],
  "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/bank-transfer-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 send the refund to the customer's bank account and return a response. The response contains the following fields:

Schema (response.body)

Response body schema for POST /bank-transfer-refunds

Example response

Response (201)

JSON
{
  "refundId": "CD3HN88U9F",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "description": "Refund for order OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z"
  },
  "bankAccount": {
    "type": "ach",
    "accountNumber": "****7890",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "*****6789",
    "secCode": "web"
  },
  "transactionResult": {
    "type": "unreferencedRefund",
    "status": "ready",
    "responseCode": "A",
    "authorizedAmount": -4999,
    "currency": "USD",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Browse guides

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer