Processing a Refund

Overview

Before proceeding to ACH refunds, make sure you are familiar with the overview of refunds in the PayConex Payment Gateway.

🚧
Note on ACH refunds
ACH transactions can only be refunded before being submitted for settlement. After settlement they cannot be refunded.

Full Refund Request

POST /api/v4/accounts/{accountId}/ach/{transactionId}/refund

{accountId} value in the path is the PayConex™ account ID number.
{transactionId} value in the path is the transaction ID to refund.

{}

*Required Scopes: pcx:payments:*, pcx:payments:ach:*, pcx:payments:ach:refund

When the previous transaction gets refunded, it assigns the transactionType to REFUND and populates the refundObject, appending a refundId to the refundObject.refundIds of the original transaction to keep track of refunds. You can see this in the Response Example below.

Body Parameters

Parameter	Type	Description	Example
`amounts`	`object`	Amounts field including `currency`, `total`. If the `amounts` is specified for an ACH refund, the full refund is applied and processed.	`{"currency": "USD", "total": "10.00"}`
`trace`	`object`	Trace data of a transaction.	See Trace.

Refund Response Example

{
  "transactionId": "000000101346",
  "status": "VOIDED",
  "timestamp": "2026-08-11T12:12:30.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "refund",
        "requestId": "2fba5ffa-bae4-4ba3-9317-7beee0a3f94f",
        "correlationId": "7e19f258-0a90-4c63-b337-390ad879973f",
        "timestamp": "2026-08-11T07:12:30-05:00"
      }
    ]
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.00"
  },
  "refundObject": {
    "refundBalance": "0.00",
    "refundIds": [
      "000000101326"
    ]
  },
  "ach": {
    "verified": false,
    "verificationPassed": false,
    "name": "Alice"
  }
}

Retrieving Transaction Metadata

For more details on retrieving transaction metadata, see Get Transaction Metadata.

If we now retrieve the transaction metadata of the refunded "000000101326" transaction, we see that the status of the transaction is now modified (according to the payment processor), with the transactionType of "REFUND", and the refund action is appended to trace.history. Particularly, the refundIds contains the ids that point to the individually refunded transactions.

📘
Note
For different transaction statuses depending on the payment processor, refer to Reversal vs Refund vs Credit | Payment Processor Overview.

GET /api/v4/accounts/{accountId}/payments/{transactionId}

*Required Scopes: pcx:payments:*, pcx:payments:read

{
  "transactionId": "000000101326",
  "status": "DECLINED",
  "timestamp": "2026-08-11T12:11:43.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "trace": {
    "source": "PCX V4",
    "history": [
      {
        "action": "transaction",
        "requestId": "3208dc95-f229-43a2-9019-10c450dfa594",
        "correlationId": "4eef5ced-28d4-4ef1-ac61-f50b2d242b20",
        "timestamp": "2026-08-11T07:11:43-05:00"
      },
      {
        "action": "refund",
        "requestId": "2fba5ffa-bae4-4ba3-9317-7beee0a3f94f",
        "correlationId": "7e19f258-0a90-4c63-b337-390ad879973f",
        "timestamp": "2026-08-11T07:12:30-05:00"
      }
    ]
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.00",
    "requested": "10.00"
  },
  "auth": {
    "code": "ACH",
    "processorMessage": "PENDING",
    "message": "PENDING"
  },
  "card": {
    "name": "Alice",
    "last4": "3412",
    "brand": "ACH"
  },
  "transactionType": "REFUND",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "0.00",
    "refundIds": [
      "000000101346"
    ]
  }
}