> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed events

Embed accepts an `onEvent` parameter that can be used to listen to certain
events emitted from the form.

```js theme={"system"}
setup({
  element: '.container',
  ...,
  onEvent: (name, data) => {
    ...
  }
})
```

Embed emits the following events:

#### `argumentError`

Returned when the initial input (`element`, `options`) are incorrectly formatted or missing.

```json theme={"system"}
{
  "code": "argumentError",
  "option": "currency",
  "message": "must be a valid number"
}
```

#### `optionsLoaded`

Returned when options are loaded. Stored options include the `id`.

```json theme={"system"}
[
  {
    "id": "...",
    "method": "card",
    "mode": "card"
  },
  {
    "method": "card",
    "mode": "card"
  }
]
```

#### `formUpdate`

Returned when the form updates. Currently this only informs the developer if the form
is valid.

```json theme={"system"}
{
  "valid": false
}
```

#### `transactionCreated`

Returns a full transaction object when we accept the transaction,
regardless of its status. Be aware that this can be a pending or declined
transaction. To track API failures please use the `transactionFailed` event.

```json theme={"system"}
{
  "type": "transaction",
  "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
  "status": "pending",
  ...
}
```

#### `transactionCancelled`

Returned when a buyer has explicitly canceled a transaction, for example closing a popup or dismissing Apple Pay. This is currently not supported for 3-D Secure transactions
and should not be conflated with transaction being declined or an error occurring.

```json theme={"system"}
{
  "type": "transactionCancelled"
}
```

#### `transactionFailed`

Returned when an API call fails to create a transaction due to a client or
server error. In other words, this event is raised when incorrect data (like an
invalid JWT) is passed to our API and a HTTP status code in the `4XX` or
`5XX` range is returned.

To catch failed or declined transactions due to
downstream issues with the payment service, please subscribe to the
`transactionCreated` event.

```json theme={"system"}
{
  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found"
}
```

#### `apiError`

Returned when the form encounters an API error.

```json theme={"system"}
{
  "type": "error",
  "code": "unauthorized",
  "status": 401,
  "message": "No valid API authentication found",
  "details": []
}
```

#### `cardDetailsChanged`

Returned when the card BIN changes in the form. It contains information on the inputted card, such as the BIN, card type and scheme.

```json theme={"system"}
{
  "bin": "42424242",
  "scheme": "visa",
  "cardType": "debit"
}
```