Refund

POST /transactions/refund

Process a referenced refund or void for a previously completed sale or capture transaction. If the transaction is in the current batch, the system will attempt to void it, otherwise it will be refunded resulting in a financial transaction.

Webhook Events

The following webhook events will be triggered during the refund process:

refund.completed - when a transaction void or refund for a previously completed transaction is completed.

application/json

Body object Required

The request to refund or void a previously completed transaction.

Represents the request to refund or void a previously completed transaction.

originalTransactionId string

The unique transaction ID of the original transaction to be captured or refunded. This is the 'id' value returned from a previous sale or capture transaction. Use this parameter if you prefer to rely on system-generated transaction IDs rather than managing your own reference system. Either originalTransactionId or originalReferenceId must be provided.
originalReferenceId string

The reference ID of the original transaction to be captured or refunded. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.

Maximum length is 100.
referenceId string

An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). If provided, this value must be unique per merchant. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.

Maximum length is 100.
amount number(uint32)

The requested amount to refund or void. If not specified, the full transaction amount will be refunded or voided. For partial refunds, must be less than the original transaction amount. If you have already performed partial refunds on this transaction, you must provide an explicit amount or an error will be returned.

Minimum value is 1, maximum value is 999999999.
invoiceNumber string

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

Maximum length is 100.
orderNumber string

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

Maximum length is 100.

Represents the request to refund or void a previously completed transaction.

originalTransactionId string

The unique transaction ID of the original transaction to be captured or refunded. This is the 'id' value returned from a previous sale or capture transaction. Use this parameter if you prefer to rely on system-generated transaction IDs rather than managing your own reference system. Either originalTransactionId or originalReferenceId must be provided.
originalReferenceId string

The reference ID of the original transaction to be captured or refunded. This should match the referenceId from a previous sale, authorization, or capture transaction (either a custom reference ID you provided or one that was generated automatically by the system). Use this parameter if you want to link transactions using reference IDs rather than system transaction IDs. Either originalTransactionId or originalReferenceId must be provided.

Maximum length is 100.
referenceId string

An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). If provided, this value must be unique per merchant. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.

Maximum length is 100.
amount number(uint32)

The requested amount to refund or void. If not specified, the full transaction amount will be refunded or voided. For partial refunds, must be less than the original transaction amount. If you have already performed partial refunds on this transaction, you must provide an explicit amount or an error will be returned.

Minimum value is 1, maximum value is 999999999.
invoiceNumber string

An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.

Maximum length is 100.
orderNumber string

An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.

Maximum length is 100.

Responses

200 application/json

A successful refund response
Hide response attributes Show response attributes object
- id string
  
  Unique ID for this refund transaction.
- timestamp string(date-time)
  
  Transaction timestamp in UTC
- type string
  
  Type of transaction
  
  Values are Sale, Auth, Capture, Refund, or Void.
- status string
  
  The current status of the transaction
  
  Values are Created, Completed, or Pending.
- accountHolder object
  
  Account holder information associated with the transaction
  
  Hide accountHolder attributes Show accountHolder attributes object
  
  id string Required
  
  Internal account holder ID assigned by the system
  
  externalId string Required
  
  External account holder ID assigned by the integrator.
  
  contact object
  
  Contact information for the account holder. Only returned for Card Not Present transactions.
  
  Hide contact attributes Show contact attributes object
  
  name string
  
  countryCode string
  
  zipCode string
  
  address string
  
  state string
  
  city string
- paymentMethod object
  
  The payment method used for this transaction.
  
  Hide paymentMethod attributes Show paymentMethod attributes object
  
  id string Required
  
  The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_* for physical terminals, pmt_vrt_* for virtual terminals, pmt_tkn_* for tokenized cards), but applications should always use the type field to determine the payment method type rather than parsing this ID.
  
  dateDeleted string(date-time)
  
  The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.
  
  This field will be present in three scenarios:
  
  As part of a successful Remove Token endpoint response
  
  In token.removed webhook notifications
  
  In List Transactions responses for transactions where the associated token was later removed
  
  When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.
  
  type string Required
  
  The type of payment method:
  
  Physical - A physical payment terminal for Card Present transactions
  
  Virtual - A hosted payment form/iframe for Card Not Present transactions
  
  Token - A tokenized card for card-on-file transactions
  
  Values are Physical, Virtual, or Token.
  
  currency string Required
  
  The currency of the payment method.
  
  Values are USD or CAD.
  
  description string
  
  A human-readable name for the payment method.
  
  billingContact object
  
  Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.
  
  Hide billingContact attributes Show billingContact attributes object
  
  name string
  
  countryCode string
  
  zipCode string
  
  address string
  
  state string
  
  city string
  
  cardType string
  
  The type of card used for this transaction:
  
  UNKNOWN - The card type is unknown
  
  DEBIT - Debit Card
  
  VISA - Visa Credit Card
  
  MASTERCARD - MasterCard Credit Card
  
  AMEX - American Express Credit Card
  
  DINERS - Diners Club Credit Card
  
  DISCOVER - Discover Credit Card
  
  JCB - JCB Credit Card
  
  UNIONPAY - UnionPay Credit Card
  
  MAESTRO - Maestro Debit Card
  
  GIFT - Gift Card
  
  CASH - All-cash Transaction
  
  EBT - Electronic Benefits Transfer Card
  
  OTHER - Other tender types
  
  Values are UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, or OTHER.
  
  maskedCardNumber string
  
  The masked card number. The format may vary (e.g. *********0011, 4*0011, etc.)
  
  cardExpDate string
  
  The expiration date of the card in MMYY format.
- invoiceNumber string
  
  An optional alphanumeric invoice number for this transaction. If provided in the request, the same value will be populated in the response.
  
  Maximum length is 100.
- orderNumber string
  
  An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.
  
  Maximum length is 100.
- referenceId string
  
  The reference ID for this transaction. This will either be the reference ID provided in the transaction request or, if no value was provided, a value generated automatically by the system. This reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions.
  
  Maximum length is 100.
- resultCode number
  
  Result codes:
  
  0 - Successful transaction request. (Check each transactionResponse's responseCode to determine if a transaction was approved or declined, card was tokenized, etc.)
  
  1003 - The payment terminal is busy or unavailable. (If this error persists, the user may need to close and re-open the Payment Application on the terminal or restart the terminal)
  
  1005 - The specified terminal could not be found.
  
  3000 - An unexpected error occurred. Please try again.
  
  3002 - The transaction could not be completed because the payment terminal could not find the related transaction.
  
  3005 - To resolve this error, power off your payment terminal, wait one minute and retry the transaction. If the error persists, please contact support.
  
  3006 - The transaction could not be completed because the payment terminal is low on battery.
  
  3009 - The transaction could not be completed because of network connectivity issues with the payment terminal. Please restore connectivity and try again.
  
  3010 - The transaction took too long and was cancelled by the application.
  
  3011 - Invalid transaction request. Please consult the documentation for valid transaction requests.
  
  3012 - Invalid transaction request. paymentMethodId is invalid.
  
  3013 - Invalid transaction request. The specified amount appears to be incorrect. Please retry with a smaller amount.
  
  3014 - Invalid amount. Please try your transaction again with an amount greater than $0.
  
  3020 - An unsupported transaction result was received.
  
  9998 - The system is not ready to process a transaction.
  
  9999 - An unknown error has occurred. If available, an auxiliary error code will be provided in the message.
  
  Values are 0, 1003, 1005, 3000, 3002, 3005, 3006, 3009, 3010, 3011, 3012, 3013, 3014, 3020, 9998, or 9999.
- resultText string
  
  A message describing the result code in more detail.
- requestedAmount number
  
  The amount requested for refund. If not specified in the request, this will be the full transaction amount.
- approvedAmount number
  
  The amount that was successfully refunded or voided.
- transactionResponses array[object]
  
  A list of all transaction responses received during the refund. In most cases, there will be only one response.
  
  A single Sale Transaction may result in multiple Responses.
  
  Hide transactionResponses attributes Show transactionResponses attributes object
  
  responseCode number
  
  Response codes:
  
  0 - UNKNOWN
  
  1 - APPROVED - Transaction was approved
  
  2 - PARTIAL_APPROVED - Transaction was partially approved, but not for the full requested amount.
  
  10 - DECLINED - Transaction was declined by the issuer or bank. For Card-Present, the transaction can also be declined offline by the terminal.
  
  11 - INSUFFICIENT_FUNDS - Rejected due to insufficient funds in the account.
  
  12 - CARD_EXPIRED - The card used for the transaction has expired.
  
  13 - FRAUD_SUSPECTED - The transaction was flagged for potential fraud.
  
  14 - INVALID_PAYMENT_INFO - The provided information is invalid (e.g.: card number).
  
  15 - LIMIT_EXCEEDED - Rejected due to reaching a limit (e.g.: credit limit).
  
  16 - VERIFICATION_REQUIRED - Additional customer verification is required for the transaction to proceed (e.g.: 3D Secure).
  
  17 - AUTHENTICATION_FAILED - Rejected due to incorrect PIN or authentication failure.
  
  18 - POLICY_VIOLATION - Rejected due to a violation of the payment gateway's terms of service or policies.
  
  19 - BATCH_EMPTY - Indicates that the batch for processing is empty.
  
  20 - RECORD_NOT_FOUND - Indicates that the requested record for a transaction was not found (e.g.: to VOID a reference).
  
  21 - ALREADY_VOIDED - Indicates that the transaction has already been voided and cannot be processed again.
  
  50 - NETWORK_ERROR - Rejected due to network or communication issues with the payment gateway.
  
  51 - INVALID_ECR_PARAMETER - Payment Terminal or system-specific errors.
  
  52 - NOT_SUPPORTED - Rejected because the requested operation is not supported.
  
  53 - BUSY_OR_UNAVAILABLE - The Payment Terminal, Payment App or system is busy or unavailable.
  
  54 - CANCELLED - Cancelled by the user or merchant.
  
  55 - USER_CANCELLED - Specific to scenarios where the user cancels the transaction.
  
  56 - TIMED_OUT_ON_USER_INPUT - Failed to complete the transaction in time.
  
  Values are 0, 1, 2, 10, 11, 14, 15, 16, 17, 18, 19, 20, 21, 50, 51, 52, 53, 54, 55, or 56.
  
  authCode string
  
  The authorization code provided by the card issuer, confirming transaction approval.
  
  amountApproved number
  
  The amount approved for this transaction response.
  
  approvedAmountBreakdown object
  
  A breakdown of approvedAmount, where each amounts approved on the payment terminal are returned separately. Only returned on Sale, Auth and Capture transactions.
  
  Hide approvedAmountBreakdown attributes Show approvedAmountBreakdown attributes object
  
  amountGoodsAndServices number
  
  The approved amount for goods and services.
  
  tax number
  
  The approved tax amount.
  
  cashback number
  
  The approved cashback amount.
  
  tip number
  
  The approved tip amount.
  
  paymentMethod object
  
  The payment method used for this transaction.
  
  Hide paymentMethod attributes Show paymentMethod attributes object
  
  id string Required
  
  The unique identifier of the payment method. This ID has a prefix that makes it human-readable (pmt_trm_* for physical terminals, pmt_vrt_* for virtual terminals, pmt_tkn_* for tokenized cards), but applications should always use the type field to determine the payment method type rather than parsing this ID.
  
  dateDeleted string(date-time)
  
  The date and time (UTC) when this payment method token was removed from the system using the Remove Token endpoint. This parameter will only be returned if the token was removed/deleted from the system.
  
  This field will be present in three scenarios:
  
  As part of a successful Remove Token endpoint response
  
  In token.removed webhook notifications
  
  In List Transactions responses for transactions where the associated token was later removed
  
  When this field is present, sensitive card details (maskedCardNumber, cardExpDate) will be removed for security purposes, but all other transaction data remains intact.
  
  type string Required
  
  The type of payment method:
  
  Physical - A physical payment terminal for Card Present transactions
  
  Virtual - A hosted payment form/iframe for Card Not Present transactions
  
  Token - A tokenized card for card-on-file transactions
  
  Values are Physical, Virtual, or Token.
  
  currency string Required
  
  The currency of the payment method.
  
  Values are USD or CAD.
  
  description string
  
  A human-readable name for the payment method.
  
  billingContact object
  
  Billing contact information associated with the payment method. Not returned on card present transactions or on refunds, captures, etc. of card present transactions.
  
  Hide billingContact attributes Show billingContact attributes object
  
  name string
  
  countryCode string
  
  zipCode string
  
  address string
  
  state string
  
  city string
  
  cardType string
  
  The type of card used for this transaction:
  
  UNKNOWN - The card type is unknown
  
  DEBIT - Debit Card
  
  VISA - Visa Credit Card
  
  MASTERCARD - MasterCard Credit Card
  
  AMEX - American Express Credit Card
  
  DINERS - Diners Club Credit Card
  
  DISCOVER - Discover Credit Card
  
  JCB - JCB Credit Card
  
  UNIONPAY - UnionPay Credit Card
  
  MAESTRO - Maestro Debit Card
  
  GIFT - Gift Card
  
  CASH - All-cash Transaction
  
  EBT - Electronic Benefits Transfer Card
  
  OTHER - Other tender types
  
  Values are UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, or OTHER.
  
  maskedCardNumber string
  
  The masked card number. The format may vary (e.g. *********0011, 4*0011, etc.)
  
  cardExpDate string
  
  The expiration date of the card in MMYY format.
  
  cardType string
  
  The type of card used for this transaction:
  
  UNKNOWN - The card type is unknown
  
  DEBIT - Debit Card
  
  VISA - Visa Credit Card
  
  MASTERCARD - MasterCard Credit Card
  
  AMEX - American Express Credit Card
  
  DINERS - Diners Club Credit Card
  
  DISCOVER - Discover Credit Card
  
  JCB - JCB Credit Card
  
  UNIONPAY - UnionPay Credit Card
  
  MAESTRO - Maestro Debit Card
  
  GIFT - Gift Card
  
  CASH - All-cash Transaction
  
  EBT - Electronic Benefits Transfer Card
  
  OTHER - Other tender types
  
  Values are UNKNOWN, DEBIT, VISA, MASTERCARD, AMEX, DINERS, DISCOVER, JCB, UNIONPAY, MAESTRO, GIFT, CASH, EBT, or OTHER.
  
  avsResult string
  
  The AVS (Address Verification Service) result. Typically returned on Card Not Present transactions.
  
  A - Address matches, ZIP does not. The first five numerical characters contained in the address match those stored at the VIC or issuer's center. However, the ZIP code does not match.
  
  E - Ineligible transaction.
  
  N - Neither address nor ZIP matches. Neither the first five numerical characters contained in the address match with those stored at the VIC nor issuer's center nor the ZIP code match.
  
  R - Retry (system unavailable or timed out).
  
  S - Card type not supported. The card type for this transaction is not supported by AVS. AVS can verify addresses for Visa cards, MasterCard, proprietary cards, and private label transactions.
  
  U - Address information unavailable.
  
  G - Address information unavailable, International - Visa only, The address information was not available at the VIC or issuer's center.
  
  W - Nine-digit ZIP match, address does not. The nine-digit Postal ZIP code matches that stored at the VIC or card issuer's centre. However, the first five numerical characters contained in the address do not match.
  
  X - Exact match (nine digit ZIP and address). Both the nine-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  
  Y - Address and five-digit ZIP match. Both the five-digit Postal ZIP code as well as the first five numerical characters contained in the address match.
  
  Z - Five-digit ZIP matches, address does not. The five-digit Postal ZIP code matches that stored at the VIC or card issuer's centre.
  
  NOTE: Transactions can still be authorized if the AVS responses are no match or failure. AVS responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.
  
  Values are A, E, N, R, S, U, G, W, X, Y, or Z.
  
  cvvResult string
  
  The CVV verification result. Typically returned on Card Not Present transactions.
  
  M - CVV Match
  
  N - CVV No Match
  
  P - Not Processed
  
  S - CVV should be on the card but the merchant indicates it is not.
  
  U - User is unregistered
  
  NOTE: Transactions can still be authorized if the CVV responses are no match or failure. CVV responses are for merchant information only, and usually do not influence the overall Authorization result. This can vary based on the Issuing Bank.
  
  Values are M, N, P, S, or U.
  
  accountType string
  
  The account type of the card (e.g. Credit or Debit)
  
  hostResponseText string
  
  A meaningful text explaining the response code from the host.
  
  receipt object
  
  The receipt associated with this transaction. Returned for Card Present transactions.
  
  Hide receipt attribute Show receipt attribute object
  
  lines array[string]
  
  The receipt lines.
- receipt object
  
  The receipt for the refund transaction, if available. If the original transaction was a Card Present transaction, the receipt will be included. For Card Not Present transactions, the receipt will be empty.
  
  Hide receipt attribute Show receipt attribute object
  
  lines array[string]
  
  The receipt lines.
400 application/json

Request Error
Hide response attributes Show response attributes object
- code number
  
  Numeric error code. These are grouped into ranges for easier identification and troubleshooting.
  
  1000 - AuthenticationGenericError
  
  2000 - RequestValidationGenericError
  
  3000 - UnknownServerGenericError
  
  9000 - UnhandledGenericError
  
  Values are 1000, 2000, 3000, or 9000.
- status string
  
  Execution status of the request sent to the payment gateway.
  
  Completed - The request completed successfully.
  
  Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
  
  Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
  
  Unknown
  
  Values are Completed, Rejected, Interrupted, or Unknown.
- message string
  
  Developer-facing error message.
- traceId string
  
  Unique trace identifier for tracking and debugging this request.
- timestamp string(date-time)
  
  The timestamp when the error occurred (UTC).
- errorDetails array[object]
  
  Represents a validation error that occurred during the request.
  
  Hide errorDetails attributes Show errorDetails attributes object
  
  code number
  
  Error code
  
  field string
  
  The field with the error
  
  message string
  
  Error message
  
  details string
  
  Additional details about the error
401 application/json

Unauthorized response due to an invalid or missing API key.
Hide response attributes Show response attributes object
- code number
  
  Numeric error code. These are grouped into ranges for easier identification and troubleshooting.
  
  1000 - AuthenticationGenericError
  
  2000 - RequestValidationGenericError
  
  3000 - UnknownServerGenericError
  
  9000 - UnhandledGenericError
  
  Values are 1000, 2000, 3000, or 9000.
- status string
  
  Execution status of the request sent to the payment gateway.
  
  Completed - The request completed successfully.
  
  Rejected - The request was rejected by the payment gateway. No action or side effects occurred. The transaction can safely be retried.
  
  Interrupted - The request was interrupted, and the final status is unknown. Possible side effects may have occurred (e.g., a Sale (Token) that returns Interrupted might still charge the customer, even if an error is returned). Additional checks are required before retrying the transaction.
  
  Unknown
  
  Values are Completed, Rejected, Interrupted, or Unknown.
- message string
  
  Developer-facing error message.
- traceId string
  
  Unique trace identifier for tracking and debugging this request.
- timestamp string(date-time)
  
  The timestamp when the error occurred (UTC).
- errorDetails array[object]
  
  Represents a validation error that occurred during the request.
  
  Hide errorDetails attributes Show errorDetails attributes object
  
  code number
  
  Error code
  
  field string
  
  The field with the error
  
  message string
  
  Error message
  
  details string
  
  Additional details about the error

POST /transactions/refund

curl \
 --request POST 'https://api.omni.integratedcommerce.io/v1/transactions/refund' \
 --header "x-api-key: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"amount":1000,"orderNumber":"order_number_1234","referenceId":"ref_refund_12345","invoiceNumber":"inv_1234567890123456","originalTransactionId":"trx_01J2F0EKHC7HY2R93C8ENBD1FG"}'

Request examples

{
  "amount": 1000,
  "orderNumber": "order_number_1234",
  "referenceId": "ref_refund_12345",
  "invoiceNumber": "inv_1234567890123456",
  "originalTransactionId": "trx_01J2F0EKHC7HY2R93C8ENBD1FG"
}

{
  "amount": 1000,
  "orderNumber": "order_number_1234",
  "referenceId": "ref_refund_12345",
  "invoiceNumber": "inv_1234567890123456",
  "originalReferenceId": "ref_s192i49i"
}

Response examples (200)

A successful response for a refund transaction.

{
  "id": "trx_01J2F0ZJ2JW5B63CJFPXRGAB1S",
  "type": "Refund",
  "status": "Completed",
  "timestamp": "2025-05-27T18:49:31Z",
  "resultCode": 0,
  "resultText": "APPROVED",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "usr_1234567890123"
  },
  "invoiceNumber": "inv_1234567890123456",
  "paymentMethod": {
    "id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
    "type": "Physical",
    "currency": "USD",
    "description": "Main Store Terminal"
  },
  "approvedAmount": 1000,
  "requestedAmount": 1000,
  "transactionResponses": [
    {
      "receipt": {},
      "authCode": "123456",
      "responseCode": 1,
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
        "type": "Token",
        "cardType": "VISA",
        "currency": "USD",
        "maskedCardNumber": "************0011"
      },
      "amountApproved": 1000
    }
  ]
}

Response examples (400)

{
  "code": 2000,
  "status": "Rejected",
  "message": "Refund request is invalid",
  "traceId": "1-687e7080-78cb54a51c8121ee32df9e35",
  "timestamp": "2025-06-21T16:53:20.9949208Z",
  "errorDetails": [
    {
      "code": 2000,
      "message": "Refund amount of 1000 exceeds the available balance of 0 for transaction ID trx_01J2F0EKHC7HY2R93C8ENBD1FG"
    }
  ]
}

Response examples (401)

{
  "code": 1000,
  "status": "Rejected",
  "message": "API key cannot be empty",
  "traceId": "1-6838be96-74c62f8e2804352739e63476",
  "timestamp": "2025-05-29T20:07:50.4723483Z",
  "errorDetails": []
}