Get Purchase Refunds

Description

Queries refund history for the project. Purchase refunds are merchant-initiated returns of funds to customers, typically processed for product returns, cancellations, or dispute resolution. This endpoint enables reconciliation of refund transactions with accounting systems.

Input

Path Parameter: projectId (guid, required) — Project identifier for authentication.
Body: request (PurchaseRefundQueryRequest, required) — Query filters including:
- startDate (datetime, optional) — Start date for refund date range.
- endDate (datetime, optional) — End date for refund date range.
- status (string, optional) — Refund status filter (Completed, Pending, Failed).
- limit (int, optional) — Maximum number of records to return.
- offset (int, optional) — Number of records to skip for pagination.

Output

Returns a PurchaseRefundQueryResponse containing refund entries or error information.

Example Request

POST /api/payment/{projectId}/charge-events/purchase-refund
Content-Type: application/json
X-API-Key: {your-api-key}

{
  "startDate": "2025-10-01",
  "endDate": "2025-10-31",
  "status": "Completed",
  "limit": 50,
  "offset": 0
}

Example Response

{
  "success": true,
  "code": 200,
  "errorMessage": null,
  "refunds": [
    {
      "refundId": "REF123456",
      "transactionId": "TX789012",
      "amount": 49.99,
      "status": "Completed",
      "refundDate": "2025-10-15T10:30:00Z",
      "reason": "Customer Return"
    }
  ],
  "totalCount": 1
}

Errors

400 Bad Request — Invalid date range or query parameters.
401 Unauthorized — Invalid or missing API key.
403 Forbidden — Project does not have access to refund data.

Notes

Results are paginated; use limit and offset for large datasets.
Refunds typically take 3-10 business days to appear in customer accounts.
Empty results return success with an empty refunds array.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

projectId

string<guid>

required

The project identifier for authentication and authorization.

Body

application/json

The query request containing filters such as date range, refund status, and pagination parameters.

Represents the filters supported when querying CyberSource purchase refund data. Used by the charge event controller to request paged refund activity for a project.

startDate

string<date-time>

required

Start date for the refund query window. Only purchase refunds created on or after this timestamp are returned.

Minimum string length: 1

offset

integer<int32>

required

Offset into the result set used for pagination. Combine with Limit to iterate through multi-page responses.

limit

integer<int32>

required

Maximum number of refund records to return. Guarded to prevent excessive payload sizes when exporting data.

Required range: 1 <= x <= 10000

isForAllProjectsInCompany

boolean

Indicates whether the query should span every project in the company. When false, the authenticated project scope is applied automatically.

Response

Always returned. Check the success property in the response body to determine if the operation succeeded.

Standard response structure containing operation status and error information. Standard query response containing a collection of matching entities. Wraps purchase refund query results for API responses. Inherits paging metadata from BaseQueryResponse.

success

boolean

True if the operation completed successfully; false if an error occurred.

Example:

true

code

enum<string>

Result code indicating the outcome of the operation.

Available options:

Unknown,

Success,

BadRequest,

Unauthorized,

NotFound,

Error

Example:

200

errorMessage

string | null

Human-readable error message when an error occurs.

Example:

null

entries

object[] | null

Collection of entities matching the query criteria.

Show child attributes

entries.dateCreated

string<date-time>

Timestamp when the refund entry was recorded in Chargeworx. Useful for ordering records during reconciliation.

entries.transactionId

string<guid>

Identifier of the transaction associated with the refund. Enables linking the refund back to the original authorization in the UI.

entries.companyProjectId

string<guid>

Identifier of the project that processed the refund. Supports reporting across multiple projects within the same company.

entries.requestId

string | null

CyberSource request identifier for the refund. Matches the value returned by CyberSource REST APIs for refund transactions.

entries.cybsmid

string | null

CyberSource merchant identifier configured for the project. Allows merchants operating multiple MIDs to differentiate settlement flows.

entries.processorMID

string | null

Processor merchant identification number. Provided in refund exports to align transactions with processor statements.

entries.transactionRefNumber

string | null

Processor reference number for the refund. Used when communicating with the acquirer about a specific return.

entries.merchantReferenceNumber

string | null

Merchant reference number supplied during the original transaction. Enables idempotent behaviour and manual reconciliation by merchant reference.

entries.transactionType

string | null

Type of transaction reported in the refund export. Typically indicates CREDIT or CHARGEBACK depending on processor semantics.

entries.purchaseRefundSubmissionDate

string | null

Submission timestamp for the purchase refund. Returned as a string by CyberSource and displayed verbatim in exports.

entries.amount

string | null

Monetary amount of the refund. Provided as a string to preserve the format returned by CyberSource.

entries.transactionAmountCurrency

string | null

Currency for the refunded amount. Stored as the ISO currency code emitted by the processor.

entries.paymentMethod

string | null

Payment method associated with the refund. Reflects whether the return was processed via credit card, PayPal, or another method.

entries.paymentType

string | null

Payment type categorization returned by the processor. Often mirrors CyberSource terminology for charge, refund, or reversal.

entries.accountSuffix

string | null

Masked card number suffix involved in the refund. Retained for merchant reference while preserving PCI compliance.

entries.authTransReferenceNumber

string | null

Reference number for the original authorization. Used to verify that the refund is tied to the correct authorization event.

entries.authDate

string | null

Date the original authorization occurred. Stored as the raw string returned by CyberSource.

entries.authRequestID

string | null

CyberSource request identifier for the authorization. Provided to link the refund back to the authorization API call.

entries.authAmount

string | null

Authorized amount for the original purchase. Stored as a string to reflect the raw export data.

entries.authCurrencyCode

string | null

Currency code associated with the authorization amount. Typically matches TransactionAmountCurrency.

entries.authCode

string | null

Authorization code returned by the issuing bank. Useful for customer service interactions when confirming the original purchase.

entries.authResponseCode

string | null

Response code from the authorization attempt. Helps identify whether the original sale required additional review.

entries.cybsBatchDateTime

string | null

Timestamp for the CyberSource batch that included the refund. Stored as a string to mirror the settlement report formatting.

entries.cybsBatchID

string | null

Identifier of the CyberSource batch that processed the refund. Enables finance teams to match settlement batches with processor statements.

entries.cardType

string | null

Card brand involved in the refund. Used in analytics to monitor card-specific refund trends.

entries.interchangeDescription

string | null

Interchange description provided in the export. Indicates the interchange program or fee category applied to the refund.

entries.interchangePercentage

string | null

Interchange percentage associated with the refund. Returned as a string to support the processor's formatting.

entries.discountPercentage

string | null

Discount percentage applied to the refund transaction. Helps merchants understand effective rates across refunds.

entries.totalFee

string | null

Total fees deducted for the refund. Expressed as a string to preserve formatting from CyberSource reports.

entries.feeCurrency

string | null

Currency associated with the total fee amount. Typically matches the refund currency.

entries.fundingAmount

string | null

Net funding amount after processor fees. Provided as a string for consistency with the raw export data.

entries.fundingCurrency

string | null

Currency associated with the funding amount. Matches the settlement currency used by the processor.

entries.firstName

string | null

Customer first name captured during the transaction. Used for customer support and dispute investigations.

entries.lastName

string | null

Customer last name captured during the transaction. Combined with FirstName for display in reports.

entries.walletType

string | null

Digital wallet type used for the transaction, when applicable. Populated for transactions processed through wallets such as Apple Pay or Google Pay.

Example:

[]

Overview

Architecture

Getting started

Security

API reference

Admin UI

Data

Observability

Deployment

CI/CD

Runbooks

Contributing

Get Purchase Refunds

Description

Input

Output

Example Request

Example Response

Errors

Notes

Authorizations

Path Parameters

Body

Response

Overview

Architecture

Getting started

Security

API reference

Admin UI

Data

Observability

Deployment

CI/CD

Runbooks

Contributing

​Description

​Input

​Output

​Example Request

​Example Response

​Errors

​Notes

Authorizations

Path Parameters

Body

Response

Description

Input

Output

Example Request

Example Response

Errors

Notes