> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/hosted-payment-form/javascript-callbacks.md).

# JavaScript callbacks

Receive the transaction response in your parent page via postMessage.

When `useJavaScriptCallback` is enabled, the form sends a message with this envelope:

```javascript
const message = { type: "hostedPaymentFormResult", data: result };
```

Read the result from `event.data.data`. The examples below show that inner `data` object. Validate the message origin, source window, and type before reading it. See [Best practices](/hosted-payment-form/best-practices.md#implement-proper-origin-validation).

## Two payload shapes

| Outcome                 | Inner `data` shape                                                                                          | How to detect                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------- |
| Transaction result      | Transaction fields plus `success`                                                                           | Has `transactionResponses`        |
| SDK or processing error | Legacy error fields including `success: false`, `errorCode`, `errorMessage`, `resultCode`, and `resultText` | Has `errorCode` or `errorMessage` |

Both shapes can have `success: false`. A browser error can occur after submission, so it does not prove that no charge occurred. Resolve uncertain outcomes through [transaction retrieval](/payments/transaction-retrieval.md).

For ACH, `success: true` can mean accepted for processing with `status: Processing` and `resultCode: 0`. It does not confirm settlement.

## Example payloads

{% tabs %}
{% tab title="Approved" %}

```json
{
  "success": true,
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "timestamp": "2025-06-02T23:56:18.2102020Z",
  "type": "Sale",
  "status": "Completed",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_12345678",
  "requestedAmount": 1000,
  "approvedAmount": 1000,
  "balanceAmount": 0,
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "accountHolder": {
    "id": "aho_01JRZPRGFF4J2SZC3HMDBYEN2J",
    "externalId": "ext_customer_123",
    "contact": {
      "name": "Jane Doe",
      "countryCode": "US",
      "zipCode": "30303",
      "address": "123 Peachtree St",
      "address2": "Suite 200",
      "state": "GA",
      "city": "Atlanta"
    }
  },
  "transactionResponses": [
    {
      "responseCode": 1,
      "amountApproved": 1000,
      "cardType": "VISA",
      "receipt": { "lines": [] },
      "paymentMethod": {
        "id": "pmt_tkn_01JRZPTMTBN41PC3VPQNZ5T3HF",
        "type": "Token",
        "currency": "USD"
      }
    }
  ],
  "resultCode": 0,
  "resultText": "APPROVED"
}
```

{% endtab %}

{% tab title="Declined" %}

```json
{
  "success": false,
  "id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
  "timestamp": "2025-06-02T23:56:18.2102020Z",
  "type": "Sale",
  "status": "Completed",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_12345678",
  "requestedAmount": 1000,
  "approvedAmount": 0,
  "balanceAmount": 0,
  "paymentMethod": {
    "id": "pmt_vrt_01JRZPTWS99Z7RB57Q1CVWSWDS",
    "type": "Virtual",
    "currency": "USD",
    "description": "Online Checkout Iframe"
  },
  "transactionResponses": [
    {
      "responseCode": 10,
      "amountApproved": 0,
      "cardType": "VISA",
      "receipt": { "lines": [] }
    }
  ],
  "resultCode": 6900,
  "resultText": "DECLINED"
}
```

{% endtab %}

{% tab title="SDK or processing error" %}

```json
{
  "success": false,
  "type": "Sale",
  "referenceId": "ref_s192i49i",
  "orderNumber": "order_number_1234",
  "invoiceNumber": "inv_12345678",
  "errorMessage": "Payment processing failed",
  "errorCode": 6203,
  "resultCode": 6000,
  "resultText": "Payment processing failed",
  "id": "trq_01J2F0EKHC7HY2R93C8ENBD1FG"
}
```

An error before the session loads may have empty identifiers. The `id` in this error shape can identify a transaction request (`trq_`), so use the original `referenceId` to reconcile it. The session error page sends the same error fields with `resultCode: 9999`, a string `errorCode`, and optional `token` and `traceId`, but no transaction fields. Cancellation includes transaction fields plus `errorCode: "Cancelled"` and `errorMessage: "User cancelled"`; these detection rules can overlap.
{% endtab %}
{% endtabs %}

## Related

* [Flow completion](/hosted-payment-form/hosted-payment-form.md#flow-completion) - how `useJavaScriptCallback` interacts with `returnUrl`
* [Payment SDK callback payloads](/payment-sdk/responses.md) - transaction results on `onComplete`, and standard error objects on `onError`
* [Best practices](/hosted-payment-form/best-practices.md)