IntegratePaymentsRefundsUnreferenced refunds

Send an unreferenced refund to a customer’s bank account

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

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.

Note: 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.

1{
2  "access_token": "eyJhbGc....adQssw5c",
3  "expires_in": 3600,
4  "scope": "service_a service_b",
5  "token_type": "Bearer"
6}

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.

Request parameters

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

Example request

POST
/v1/bank-transfer-refunds
1curl -X POST https://api.payroc.com/v1/bank-transfer-refunds \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "processingTerminalId": "1234001",
7  "order": {
8    "orderId": "OrderRef6543",
9    "description": "Refund for order OrderRef6543",
10    "amount": 4999,
11    "currency": "USD"
12  },
13  "refundMethod": {
14    "type": "ach",
15    "accountType": "checking",
16    "secCode": "web",
17    "nameOnAccount": "Sarah Hazel Hopper",
18    "accountNumber": "1234567890",
19    "routingNumber": "123456789"
20  },
21  "customFields": [
22    {
23      "name": "yourCustomField",
24      "value": "abc123"
25    }
26  ],
27  "customer": {
28    "notificationLanguage": "en",
29    "contactMethods": [
30      {
31        "type": "email",
32        "value": "[email protected]"
33      }
34    ]
35  }
36}'

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:

Example response

Response
1{
2  "refundId": "CD3HN88U9F",
3  "processingTerminalId": "1234001",
4  "order": {
5    "orderId": "OrderRef6543",
6    "description": "Refund for order OrderRef6543",
7    "amount": 4999,
8    "currency": "USD",
9    "dateTime": "2024-07-02T15:30:00Z"
10  },
11  "bankAccount": {
12    "type": "ach",
13    "secCode": "web",
14    "nameOnAccount": "Sarah Hazel Hopper",
15    "accountNumber": "****7890",
16    "routingNumber": "*****6789",
17    "accountType": "checking"
18  },
19  "transactionResult": {
20    "type": "unreferencedRefund",
21    "status": "ready",
22    "responseMessage": "NoError",
23    "authorizedAmount": -4999,
24    "currency": "USD",
25    "responseCode": "A",
26    "processorResponseCode": "0"
27  },
28  "customer": {
29    "notificationLanguage": "en",
30    "contactMethods": [
31      {
32        "type": "email",
33        "value": "[email protected]"
34      }
35    ]
36  },
37  "customFields": [
38    {
39      "name": "yourCustomField",
40      "value": "abc123"
41    }
42  ]
43}