Guides
/
Integration guides
/
Refunds
/
Send an unreferenced refund to a customer’s bank account

Send an unreferenced refund to a customer’s bank account

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

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.
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.
{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

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 bank transfer payment, send a POST request to the Bank Transfer Refunds endpoint. Test endpoint: https://api.uat.payroc.com/v1/bank-transfer-refunds
Production endpoint: https://api.payroc.com/v1/bank-transfer-refunds

Request parameters

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

Header parameters

Body parameters

Example request

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

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:

Response Schema

Status Code 201

Successful request. We sent the refund to the customer's bank account.
Response headers
Response body

Example response

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