# API Reference

> Complete API reference for the Bolt React Native SDK for Embeddable Checkout: exports, props, types, and error codes.

Source: https://help.boltapp.com/developers/sdks/react-native/api-reference

This SDK is for use with **[Bolt Embeddable Checkout](/products/embeddable-checkout)**. For the full backend API documentation, see the [Embeddable Checkout API Reference](https://help.boltapp.com/api-embedded/).

## Root Exports [#root-exports]

**Import from:** `@boltpay/react-native`

| Export                               | Description                                                                |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `Bolt`                               | Client class. Takes `{ publishableKey, environment?, language? }`.         |
| `BoltProvider`                       | React context provider. Wrap your app with `<BoltProvider client={bolt}>`. |
| `useBolt()`                          | Hook to access the Bolt client from any component.                         |
| `bolt.configureOnPageStyles(styles)` | Set global v3 styles applied to all elements.                              |

## Payment Exports [#payment-exports]

**Import from:** `@boltpay/react-native/payments`

| Export                               | Description                                                                |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `CreditCard.Component`               | WebView-based credit card input.                                           |
| `CreditCard.useController(options?)` | Returns a controller with `tokenize()`, `on()`, and `setStyles()`.         |
| `useThreeDSecure()`                  | Hook returning `{ Component, fetchReferenceID(), challengeWithConfig() }`. |
| `ApplePay`                           | Native `PKPaymentButton` (iOS only; renders nothing on Android).           |
| `GoogleWallet`                       | Native Google Pay `PayButton` (Android only; renders nothing on iOS).      |

## Credit Card Controller [#credit-card-controller]

| Method                | Description                                                         |
| --------------------- | ------------------------------------------------------------------- |
| `tokenize()`          | Returns `Promise<TokenResult \| Error>`. Never throws.              |
| `on(event, callback)` | Register event listener. Events: `valid`, `error`, `blur`, `focus`. |
| `setStyles(styles)`   | Update input field styles.                                          |

## 3D Secure [#3d-secure]

| Method                                    | Description                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| `fetchReferenceID(creditCardInfo)`        | Accepts `TokenResult` or `CreditCardId`. Returns `Promise<string>`. Throws `ThreeDSError`. |
| `challengeWithConfig(orderToken, config)` | Returns `Promise<ThreeDSResult>`. Never throws. Check `result.success`.                    |

## ApplePay Props [#applepay-props]

| Prop          | Type                                   | Default     | Description                                                                      |
| ------------- | -------------------------------------- | ----------- | -------------------------------------------------------------------------------- |
| `config`      | `ApplePayConfig`                       | required    | Country/currency, total amount, and optional merchant ID (`mode='native'` only). |
| `onComplete`  | `(ApplePayResult) => void`             | required    | Called with token, bin, expiration, and billing contact on success.              |
| `onError`     | `(Error) => void`                      | :           | Called on payment failure.                                                       |
| `mode`        | `'webview' \| 'native'`                | `'webview'` | `'webview'` uses the Bolt-hosted iframe. `'native'` uses PassKit.                |
| `buttonType`  | `ApplePayButtonType`                   | `'plain'`   | Button label variant. Auto-localized by Apple.                                   |
| `buttonStyle` | `'black' \| 'white' \| 'whiteOutline'` | `'black'`   | Button color theme.                                                              |
| `referrer`    | `string`                               | :           | Merchant website URL. Required for `mode='webview'`.                             |
| `style`       | `ViewStyle`                            | :           | Container style overrides.                                                       |

## GoogleWallet Props [#googlewallet-props]

| Prop           | Type                        | Default   | Description                                                                                                       |
| -------------- | --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `config`       | `GooglePayConfig`           | required  | Presentation options: currency, amount, label, billing address format. Merchant config is auto-fetched from Bolt. |
| `onComplete`   | `(GooglePayResult) => void` | required  | Called with token, bin, expiration, and billing address on success.                                               |
| `onError`      | `(Error) => void`           | :         | Called on payment failure or cancellation.                                                                        |
| `buttonType`   | `GooglePayButtonType`       | `'plain'` | Maps to `ButtonConstants.ButtonType`. Auto-localized.                                                             |
| `buttonTheme`  | `GooglePayButtonTheme`      | `'dark'`  | `'dark'` or `'light'`. Maps to `ButtonConstants.ButtonTheme`.                                                     |
| `borderRadius` | `number`                    | :         | Corner radius in dp.                                                                                              |
| `style`        | `ViewStyle`                 | :         | Container style overrides.                                                                                        |

## Types [#types]

**Import from:** `@boltpay/react-native/payments`

### Styles [#styles]

```typescript title="Signature"
type Styles = { [key: `--bolt-${string}`]: string };
```

V3 CSS custom properties. See [Styling](/developers/sdks/react-native/styling/) for usage.

### TokenResult [#tokenresult]

```typescript title="TypeScript"
{
  token?: string;
  last4?: string;
  bin?: string;
  network?: string;
  expiration?: string;
  postal_code?: string;
}
```

### CreditCardId [#creditcardid]

```typescript title="TypeScript"
{
  id: string;       // from Bolt's Add Card API
  expiration: string;
}
```

### CreditCardInfo [#creditcardinfo]

```typescript title="Signature"
type CreditCardInfo = CreditCardId | TokenResult;
```

Input for `fetchReferenceID()`.

### ThreeDSConfig [#threedsconfig]

```typescript title="TypeScript"
{
  referenceID: string;
  jwtPayload: string;
  stepUpUrl: string;
}
```

### ThreeDSResult [#threedsresult]

```typescript title="TypeScript"
{
  success: boolean;
  error?: ThreeDSError;
}
```

### ThreeDSError [#threedserror]

Error subclass with a numeric `code` property (1001–1010). See [Error Codes](#error-codes) below.

### EventType [#eventtype]

```typescript title="Signature"
type EventType = 'error' | 'valid' | 'blur' | 'focus';
```

### ApplePayResult [#applepayresult]

```typescript title="TypeScript"
{
  token: string;
  bin?: string;
  expiration?: string;
  billingContact?: object;
  boltReference?: string;
}
```

### ApplePayButtonType [#applepaybuttontype]

Apple-approved button label variants:

`'plain'` | `'buy'` | `'checkout'` | `'book'` | `'subscribe'` | `'donate'` | `'order'` | `'setUp'` | `'inStore'` | `'reload'` | `'addMoney'` | `'topUp'` | `'rent'` | `'support'` | `'contribute'` | `'tip'`

### ApplePayConfig [#applepayconfig]

Apple Pay configuration including merchant ID (for native mode), country/currency, and total amount.

### GooglePayResult [#googlepayresult]

```typescript title="TypeScript"
{
  token: string;
  bin?: string;
  expiration?: string;
  email?: string;
  billingAddress?: object;
  boltReference?: string;
}
```

### GooglePayButtonType [#googlepaybuttontype]

Google-approved button label variants:

`'plain'` | `'buy'` | `'pay'` | `'checkout'` | `'subscribe'` | `'donate'` | `'order'` | `'book'`

### GooglePayButtonTheme [#googlepaybuttontheme]

`'dark'` | `'light'`

### GooglePayConfig [#googlepayconfig]

```typescript title="TypeScript"
{
  billingAddressCollectionFormat?: string;
  currencyCode?: string;
  label?: string;
  amount?: string;
}
```

Merchant and gateway config is auto-fetched from Bolt: you only provide presentation options.

## Error Codes [#error-codes]

`ThreeDSError` includes a numeric `code` property with the following values:

| Code | Description                                      |
| ---- | ------------------------------------------------ |
| 1001 | Credit card id or token must be supplied         |
| 1002 | Credit card id and token cannot both be supplied |
| 1003 | Malformed credit card token                      |
| 1004 | Order token does not exist                       |
| 1005 | API response error during verification           |
| 1006 | Verification not required                        |
| 1007 | Setup error during verification                  |
| 1008 | Authentication failed                            |
| 1009 | Failed to create challenge or challenge failed   |
| 1010 | Failed to get device data collection jwt         |