Refund

Return funds from a purchase transaction back to a customer.

Refund a purchase transaction

POST

/v1/transactions/{systemTransactionId}/modifications

Request examples

Use the following request to return funds from a purchase transaction back to the original payment method.

For Card, you can also perform a refund by initiating a transaction and setting the intent to Refund.

For SPEI, CVU, and Bre-B, use this modifications endpoint only. Don't create a new transaction with intent Refund.

Use the following request to refund a card purchase. Partial refunds are supported up to the original transaction amount.

{
  "fundingType": "Card",
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "TRANSACTION-2",
  "merchantTransactionDate": "2025-01-27T08:51:02.826Z",
  "amounts": {
    "transaction": 24.99
  },
  "operation": "Refund"
}

Parameter	Description
`fundingType` string (enum) required	The type of funding source used for the transaction. Possible values: `Card` `PayByBank`
`apmProvider` string (enum)	The APM provider. Required when `fundingType` is `PayByBank`. For SPEI set this to `Spei`. For CVU set this to `Cvu`. For Bre-B set this to `Breb`. If you omit `apmProvider` on a Pay by bank modification, the Gateway may route the request to a different provider.
`merchant` string (≤ 20 characters) required	Your unique merchant identifier, as assigned by PXP.
`site` string (≤ 20 characters) required	Your unique site identifier, as assigned by PXP.
`merchantTransactionId` string (≤ 50 characters) required	The unique identifier for this transaction, as chosen by you.
`merchantTransactionDate` date-time required	The current date and time, in ISO 8601 format.
`currencyCode` string (3 characters)	The currency code for the modification amount, in ISO 4217 format. Required for SPEI, CVU, and Bre-B refunds. For SPEI this must be `MXN`. For CVU this must be `ARS`. For Bre-B this must be `COP`.
`amounts` object required	Details about the transaction amount.
`amounts.transaction` string required	The value of the transaction. For `Refund` operations, this can't be more than the original transaction value. For SPEI, CVU, and Bre-B refunds, this must be the same as the original transaction amount (only full refunds are supported).
`amounts.gratuity` number	The gratuity or tip amount.
`operation` string required	The type of modification that you want to make. Set this to `Refund`. Possible values: `Capture` `FinalCapture` `Refund` `Incremental` `Void` For SPEI, CVU, and Bre-B, only `Refund` is supported.
`remark` string	Optional remark or note about the modification.
`data` object	Optional key-value pairs for additional data.
`dccData` object	Details about the Dynamic Currency Conversion (DCC).
`dccData.rateSelectedIndicator` string (enum) required	Whether a DCC rate was selected for the transaction. Possible values: `NotSelected` `Selected` `NotAvailable` `CardNotEligible` `Error`
`dccData.amounts` object required	Details about the transaction amount in the local currency and the cardholder's currency.
`dccData.amounts.local` string required	Details about the transaction amount in the local currency.
`dccData.amounts.local.transaction` number required	The transaction amount in the local currency.
`dccData.amounts.local.currencyCode` string required	The currency code in ISO 4217 format.
`dccData.amounts.cardholder` object required	Details about the transaction amount in the cardholder's currency.
`dccData.amounts.cardholder.transaction` number required	The transaction amount in the cardholder's currency.
`dccData.amounts.cardholder.currencyCode` string required	The currency code in ISO 4217 format.
`dccData.exchangeRate` number required	The exchange rate used for the DCC.
`dccData.providerData` object required	Details about the DCC provider.
`dccData.providerData.provider` string required	The name of the DCC provider.
`dccData.providerData.referenceId` string required	The reference ID provided by the DCC provider. This is required if your provider is Elavon, otherwise it's ignored.
`dccData.providerData.merchantId` string required	The merchant ID assigned by the DCC provider. This is required if your provider is Elavon, otherwise it's ignored.
`dccData.providerData.terminalId` string required	The terminal ID assigned by the DCC provider. This is required if your provider is Elavon, otherwise it's ignored.
`dccData.providerData.markupTextIndicator` integer required	The mark-up text indicator for the DCC provider.
`dccData.markupRate` number or null	The mark-up rate.
`dccData.disclaimer` string or null	The disclaimer text.

Response examples

If your request is successful, you'll receive a 200 response containing a new systemTransactionId. You'll also receive a Transaction (Authorised) webhook notification.

{
  "state": "Authorised",
  "stateData": {},
  "merchantTransactionDate": "2025-03-27T10:53:38.499Z",
  "merchantTransactionId": "ac47966d-b732-4706-8f29-c4335fd84f02",
  "systemTransactionId": "bfdf16cc-d824-4812-8ee6-a206a2c08043",
  "fundingData": {
    "cardScheme": "MasterCard",
    "maskedPrimaryAccountNumber": "526600******0075",
    "expiryMonth": "12",
    "expiryYear": "2031",
    "gatewayTokenId": "5fbd77ce-02c1-40ed-94bc-1016660b7512",
    "providerResponse": {
      "provider": "pxpfinancial",
      "code": "00",
      "emvDataResponse": {},
      "paymentAccountReference": "637607302178175469",
      "merchantAdvice": {},
      "authorisedAmount": 0
     }
  }
}

Refund

Refund a purchase transaction

Request examples

Response examples

Was this helpful?