Unreferenced Refund (Card Not Present)
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.
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 is999999999. -
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-methodsendpoint. - Example format:
-
invoiceNumber
string An optional alphanumeric invoice number for this transaction. If provided, 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.
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_12345678","paymentMethodId":"pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS","useJavaScriptCallback":true}'{
"amount": 1000,
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"invoiceNumber": "inv_12345678",
"paymentMethodId": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"useJavaScriptCallback": true
}{
"id": "ifr_01J2F0EKHC7HY2R93C8ENBD1FG",
"status": "Pending",
"iframeUrl": "https://hpf.integratedcommerce.io/session/01JSFAMY0AGW27QKP30C727512",
"sessionId": "ses_01JSFAMY0AGW27QKP30C727512",
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"invoiceNumber": "inv_12345678",
"paymentMethod": {
"id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
"type": "Virtual",
"currency": "USD",
"description": "Online Checkout Iframe"
},
"requestedAmount": 1000,
"expirationTimestamp": "2025-04-17T14:19:03Z"
}{
"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"
}
]
}{
"code": 1000,
"status": "Rejected",
"message": "Invalid or missing API key",
"traceId": "1-6838be96-74c62f8e2804352739e63476",
"timestamp": "2025-05-29T20:07:50.4723483Z",
"errorDetails": []
}