Send a referenced refund to a bank account

Prerequisites: Authentication

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 bank account number.

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

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

Headers

To create the header of each GET 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.

Shell

curl
-H "Content-Type: application/json"
-H "Authorization: <Bearer token>"

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.

Shell

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 - Retrieve the details of the payment

1a (Optional) – Retrieve the details of the payment with a paymentId

Send a GET request with the paymentID to our Bank Transfer Payments endpoint.

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

Request parameters

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

Schema (`request.path`)

Path parameters for GET /bank-transfer-payments/{paymentId}

Example request

Request

GET https://api.payroc.com/v1/bank-transfer-payments/{paymentId}

Store Token Bank Transfer Payment

curl

curl https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y \
     -H "Authorization: Bearer <token>"

Store Token Bank Transfer Payment

Python

import requests

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

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

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

print(response.json())

Store Token Bank Transfer Payment

JavaScript

const url = 'https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y';
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);
}

Store Token Bank Transfer Payment

package main

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

func main() {

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

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

}

Store Token Bank Transfer Payment

ruby

require 'uri'
require 'net/http'

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

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

Store Token Bank Transfer Payment

Java

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

HttpResponse<String> response = Unirest.get("https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y")
  .header("Authorization", "Bearer <token>")
  .asString();

Store Token Bank Transfer Payment

PHP

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();

Store Token Bank Transfer Payment

using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);

Store Token Bank Transfer Payment

swift

import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/bank-transfer-payments/M2MJOG6O2Y")! 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, our gateway returns the details of the payment. The response contains the following fields:

Schema (`response.body`)

Response body schema for GET /bank-transfer-payments/{paymentId}

Example response

Response (200)

JSON

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "name": "Sales Tax",
          "rate": 5,
          "amount": 217
        }
      ],
      "tip": {
        "type": "percentage",
        "amount": 435,
        "percentage": 10
      }
    },
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza"
  },
  "bankAccount": {
    "type": "ach",
    "accountNumber": "****3159",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "053200983",
    "secCode": "web",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hazel 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"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "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"
    }
  ]
}

1b (Optional) – Retrieve the details of the payment without a paymentId

Send a GET request to our Bank Transfer Payments endpoint. To filter your results, use query parameters.

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

Request parameters

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

Schema (`request.query`)

Query parameters for GET /bank-transfer-payments

Example request

Request

GET https://api.payroc.com/v1/bank-transfer-payments

Bank Transfer Payment

curl

curl -G https://api.payroc.com/v1/bank-transfer-payments \
     -H "Authorization: Bearer <token>" \
     -d after=8516 \
     -d before=2571 \
     --data-urlencode dateFrom=2024-07-01T00:00:00Z \
     --data-urlencode dateTo=2024-07-31T23:59:59Z \
     -d last4=7890 \
     -d limit=25 \
     --data-urlencode nameOnAccount=Sarah%20Hazel%20Hopper \
     -d orderId=OrderRef6543 \
     -d paymentLinkId=JZURRJBUPS \
     -d processingTerminalId=1234001 \
     -d settlementDate=2024-07-15 \
     -d settlementState=settled \
     -d status=ready \
     -d type=payment

Bank Transfer Payment

Python

import requests

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

querystring = {"after":"8516","before":"2571","dateFrom":"2024-07-01T00:00:00Z","dateTo":"2024-07-31T23:59:59Z","last4":"7890","limit":"25","nameOnAccount":"Sarah%20Hazel%20Hopper","orderId":"OrderRef6543","paymentLinkId":"JZURRJBUPS","processingTerminalId":"1234001","settlementDate":"2024-07-15","settlementState":"settled","status":"[\"ready\"]","type":"[\"payment\"]"}

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

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

print(response.json())

Bank Transfer Payment

JavaScript

const url = 'https://api.payroc.com/v1/bank-transfer-payments?after=8516&before=2571&dateFrom=2024-07-01T00%3A00%3A00Z&dateTo=2024-07-31T23%3A59%3A59Z&last4=7890&limit=25&nameOnAccount=Sarah%2520Hazel%2520Hopper&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-15&settlementState=settled&status=%5B%22ready%22%5D&type=%5B%22payment%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);
}

Bank Transfer Payment

package main

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

func main() {

	url := "https://api.payroc.com/v1/bank-transfer-payments?after=8516&before=2571&dateFrom=2024-07-01T00%3A00%3A00Z&dateTo=2024-07-31T23%3A59%3A59Z&last4=7890&limit=25&nameOnAccount=Sarah%2520Hazel%2520Hopper&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-15&settlementState=settled&status=%5B%22ready%22%5D&type=%5B%22payment%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))

}

Bank Transfer Payment

ruby

require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/bank-transfer-payments?after=8516&before=2571&dateFrom=2024-07-01T00%3A00%3A00Z&dateTo=2024-07-31T23%3A59%3A59Z&last4=7890&limit=25&nameOnAccount=Sarah%2520Hazel%2520Hopper&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-15&settlementState=settled&status=%5B%22ready%22%5D&type=%5B%22payment%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

Bank Transfer Payment

Java

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

HttpResponse<String> response = Unirest.get("https://api.payroc.com/v1/bank-transfer-payments?after=8516&before=2571&dateFrom=2024-07-01T00%3A00%3A00Z&dateTo=2024-07-31T23%3A59%3A59Z&last4=7890&limit=25&nameOnAccount=Sarah%2520Hazel%2520Hopper&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-15&settlementState=settled&status=%5B%22ready%22%5D&type=%5B%22payment%22%5D")
  .header("Authorization", "Bearer <token>")
  .asString();

Bank Transfer Payment

PHP

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.payroc.com/v1/bank-transfer-payments?after=8516&before=2571&dateFrom=2024-07-01T00%3A00%3A00Z&dateTo=2024-07-31T23%3A59%3A59Z&last4=7890&limit=25&nameOnAccount=Sarah%2520Hazel%2520Hopper&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-15&settlementState=settled&status=%5B%22ready%22%5D&type=%5B%22payment%22%5D', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();

Bank Transfer Payment

using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/bank-transfer-payments?after=8516&before=2571&dateFrom=2024-07-01T00%3A00%3A00Z&dateTo=2024-07-31T23%3A59%3A59Z&last4=7890&limit=25&nameOnAccount=Sarah%2520Hazel%2520Hopper&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-15&settlementState=settled&status=%5B%22ready%22%5D&type=%5B%22payment%22%5D");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);

Bank Transfer Payment

swift

import Foundation

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/bank-transfer-payments?after=8516&before=2571&dateFrom=2024-07-01T00%3A00%3A00Z&dateTo=2024-07-31T23%3A59%3A59Z&last4=7890&limit=25&nameOnAccount=Sarah%2520Hazel%2520Hopper&orderId=OrderRef6543&paymentLinkId=JZURRJBUPS&processingTerminalId=1234001&settlementDate=2024-07-15&settlementState=settled&status=%5B%22ready%22%5D&type=%5B%22payment%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, our gateway returns a list of payments that match the query parameters. The response contains the following fields:

Schema (`response.body`)

Response body schema for GET /bank-transfer-payments

Example response

Response (200)

JSON

{
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "data": [
    {
      "paymentId": "M2MJOG6O2Y",
      "processingTerminalId": "1234001",
      "order": {
        "amount": 4999,
        "currency": "USD",
        "orderId": "OrderRef6543",
        "breakdown": {
          "subtotal": 4347,
          "taxes": [
            {
              "name": "Sales Tax",
              "rate": 5,
              "amount": 217
            }
          ],
          "tip": {
            "type": "percentage",
            "amount": 435,
            "percentage": 10
          }
        },
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "Large Pepperoni Pizza"
      },
      "bankAccount": {
        "type": "pad",
        "accountNumber": "*******3159",
        "institutionNumber": "543",
        "nameOnAccount": "Sarah Hazel Hopper",
        "transitNumber": "76543"
      },
      "transactionResult": {
        "type": "payment",
        "status": "ready",
        "responseCode": "A",
        "authorizedAmount": 4999,
        "currency": "USD"
      },
      "customer": {
        "notificationLanguage": "en",
        "contactMethods": [
          {
            "type": "email",
            "value": "sarah.hopper@example.com"
          }
        ]
      }
    },
    {
      "paymentId": "E29U8OU8Q4",
      "processingTerminalId": "1234001",
      "order": {
        "amount": 3999,
        "currency": "USD",
        "orderId": "OrderRef7654",
        "breakdown": {
          "subtotal": 3477,
          "taxes": [
            {
              "name": "Sales Tax",
              "rate": 5,
              "amount": 174
            }
          ],
          "tip": {
            "type": "percentage",
            "amount": 348,
            "percentage": 10
          }
        },
        "dateTime": "2024-07-02T15:30:00Z",
        "description": "test"
      },
      "bankAccount": {
        "type": "pad",
        "accountNumber": "*******7890",
        "institutionNumber": "543",
        "nameOnAccount": "Sarah Hazel Hopper",
        "transitNumber": "76543"
      },
      "transactionResult": {
        "type": "payment",
        "status": "ready",
        "responseCode": "A",
        "authorizedAmount": 3999,
        "currency": "USD"
      },
      "customer": {
        "notificationLanguage": "en",
        "contactMethods": [
          {
            "type": "email",
            "value": "sarah.hopper@example.com"
          }
        ]
      },
      "customFields": [
        {
          "name": "yourCustomField",
          "value": "abc123"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/bank-transfer-payments?limit=2&processingTerminalId=1234001&after=E29U8OU8Q4"
    },
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1//bank-transfer-payments?limit=2&processingTerminalId=1234001&before=M2MJOG6O2Y"
    }
  ]
}

Step 2 - Refund the payment

To refund the payment, send a POST request to our Bank Transfer Payments Refund endpoint.

Environment	URL
Test	https://api.uat.payroc.com/v1/bank-transfer-payments/{paymentId}/refund
Production	https://api.payroc.com/v1/bank-transfer-payments/{paymentId}/refund

Request parameters

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

Schema (`request.body`)

Request body schema for POST /bank-transfer-payments/{paymentId}/refund