Unreferenced Refund (Card Not Present)

POST /transactions/unreferenced-virtual-refund

Process an unreferenced refund without a matching completed sale or capture transaction using a hosted payment form / iframe where the card is not physically present. This POST request initiates a refund session and returns a short-lived iframe URL to embed in your refund page, rather than using a static iframe URL.

When the customer submits their card information, they will be redirected to the returnUrl (if provided) or a postMessage event will be sent to the parent window. The complete refund result will be delivered via the Refund Completed webhook.

Note regarding Unreferenced Refunds - Unreferenced refunds are refunds that do not require a previously completed payment transaction to be referenced. They are only available on certain accounts by request to support@integratedcommerce.io.

Webhook Events

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

refund.completed - when an unreferenced refund is completed.
token.created - when a card is tokenized and stored as a payment method.

application/json

Body Required

The request to process an unreferenced refund using a hosted payment form / iframe.

amount number(uint32) Required

The requested amount to refund.

Minimum value is 1, maximum value is 999999999.
paymentMethodId string
The ID of the hosted payment form / iframe that will collect card information for this Card Not Present unreferenced refund.
- Example format: pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS
- OPTIONAL ONLY if you have a single hosted payment form configured
- REQUIRED if you have multiple hosted payment forms configured
You can retrieve all available hosted payment form IDs for your account using the GET /payment-methods endpoint.
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

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.
returnUrl string

Will be used to redirect user back to merchant's site after iframe completed or canceled if provided. The URL will include various parameters that are detailed in "Transaction Result Parameters" section of the Hosted Payment Form section. If you do not provide a returnUrl, the customer will see either a "Payment Processed Successfully" or "Payment Processing Issue" screen.
useJavaScriptCallback boolean

At the end of the transaction flow, the user is always redirected to either the returnUrl (if provided), or a default success or issue page. In addition, if useJavaScriptCallback is set to true, the iframe will use JavaScript to post a message to the parent window to notify the merchant's site when the iframe completed. This allows for more control over the user experience on the merchant's site.

Responses

200 application/json

A successful Card Not Present unreferenced refund response
Hide response attributes Show response attributes object
- id string
  
  Unique ID for this transaction.
- paymentMethod object
  
  The payment method used for this Card Not Present 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.
  
  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.
- requestedAmount number
  
  The amount sent in the transaction request. The amount is always a non-null positive integer in the smallest denomination of the currency (e.g. cents for USD or CAD).
- sessionId string
  
  Session ID for the iframe transaction.
- iframeUrl string
  
  URL for the iframe to collect payment information, or null if iframe could not be created due to invalid credentials, etc.
- expirationTimestamp string(date-time)
  
  When the iframe session will expire (UTC).
- status string
  
  Status of the iframe session. When created, this will always be pending. The status values will be updated as the customer goes through the iframe process.
  
  Values are Pending, Completed, Expired, or Error.
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/unreferenced-virtual-refund

curl \
 --request POST 'https://api.omni.integratedcommerce.io/v1/transactions/unreferenced-virtual-refund' \
 --header "x-api-key: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"amount":1000,"orderNumber":"order_number_1234","referenceId":"ref_s192i49i","invoiceNumber":"inv_1234567890123456789012354678901","paymentMethodId":"pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS","useJavaScriptCallback":true}'

Request example

{
  "amount": 1000,
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "invoiceNumber": "inv_1234567890123456789012354678901",
  "paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
  "useJavaScriptCallback": true
}

Response examples (200)

{
  "id": "ifr_01J2F0EKHC7HY2R93C8ENBD1FG",
  "status": "Pending",
  "iframeUrl": "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512",
  "sessionId": "ses_01JSFAMY0AGW27QKP30C727512",
  "orderNumber": "order_number_1234",
  "referenceId": "ref_s192i49i",
  "invoiceNumber": "inv_1234567890123456789012354678901",
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "requestedAmount": 1000,
  "expirationTimestamp": "2025-04-17T14:19:03Z"
}

Response examples (400)

{
  "code": 2000,
  "status": "Rejected",
  "message": "One or more validation errors occurred.",
  "traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
  "timestamp": "2025-05-29T20:00:15.5752808Z",
  "errorDetails": [
    {
      "code": 2000,
      "field": "Amount",
      "details": "The Amount field must be a positive number between 1 and 999999999.",
      "message": "Request validation failed"
    }
  ]
}

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": []
}