Take paymentsPaymentsRefundsUnreferenced refunds

Run an unreferenced refund for a card payment

View as Markdown

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.

Request parameters

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

Request

channelenumRequired
Channel that the merchant used to request the refund.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the refund.
refundMethodobjectRequired
Polymorphic object that contains information about the payment method that the merchant uses to refund the customer. The value of the type parameter determines which variant you should use: - `card` - Payment card details - `secureToken` - Secure token details
operatorstringOptional0-50 characters
Operator who initiated the request.
customerobjectOptional
Object that contains the customer's contact details and address information. Contains parameters required for [Level 2, Level 3, and CEDP transactions](https://docs.payroc.com/knowledge/card-payments/enhanced-data).
ipAddressobjectOptional
Object that contains the IP address of the device that sent the request.
customFieldslist of objectsOptional
Array of customField objects.

Example request

POST
/v1/refunds
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"
    }
  ]
}'
Try it

Response fields

If your request is successful, we refund the card transfer payment and return a response. The response contains the following fields:

Response

refundIdstringRequired=10 characters
Unique identifier that our gateway assigned to the refund.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
orderobjectRequired
Object that contains information about the refund.
cardobjectRequired
Object that contains the details of the payment card.
transactionResultobjectRequired
Object that contains information about the transaction response details.
operatorstringOptional0-50 characters
Operator who requested the refund.
customerobjectOptional
Object that contains the customer's contact details and address information.
paymentobjectOptional
Object that contains information about the payment that the refund is linked to. **Note:** We don't return this object for unreferenced refunds.
supportedOperationslist of enumsOptional
Array of operations that you can perform on the transaction. Our gateway can return any of the following values: - `capture` - [Capture the payment](https://docs.payroc.com/api/schema/card-payments/payments/capture). - `refund` - [Refund the payment](https://docs.payroc.com/api/schema/card-payments/refunds/create-referenced-refund). - `fullyReverse` - [Fully reverse the transaction](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `partiallyReverse` - [Partially reverse the payment](https://docs.payroc.com/api/schema/card-payments/refunds/reverse). - `incrementAuthorization` - [Increase the amount of the authorization](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `adjustTip` - [Adjust the tip post-payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `addSignature` - [Add a signature to the payment](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsReady` - [Set the transaction’s status to `ready`](https://docs.payroc.com/api/schema/card-payments/payments/adjust). - `setAsPending` - [Set the transaction’s status to `pending`](https://docs.payroc.com/api/schema/card-payments/payments/adjust).
customFieldslist of objectsOptional
Array of customField objects.

Example response

Response
{
  "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"
    }
  ]
}