# RoadSync JavaScript SDK

## Getting Started

### Integration

You'll need a `locationId` and `apiKey` for configuration. Once you have those, and have loaded the appropriate polyfills for
your target browsers, it's simple to add the RoadSync payment form to your page. Replace the `XXXXXXXXXX` in the example below
with your actual values for those fields.

Also, note the `amount` property. This is the value, in `USD`, for the transaction.

```html
<script type="module" src="https://unpkg.com/@roadsync/js:@1/dist/roadsync.js" />
<body>
    <roadsync-checkout location-id="XXXXXXXXXX" api-key="XXXXXXXXXX" amount="12.34"></roadsync-checkout>
</body>
```

### Using React, Angular, Vue or other frameworks

You can also use the RoadSync.js package directly in your React, Angular, Vue, or other single-page apps. Since it's built with
web components, it plays nicely with any web framework.

For example, if you're using React, you can do this:

```typescript

type Props {
    locationId: string;
    apiKey: string;
    amount: string;
}

class MyPaymentForm extends React.Component<Props> {

    render(): React.ReactElement {
        const { locationId, apiKey, amount } = this.props;
        return (
            <roadsync-payment-form location-id={locationId} api-key={apiKey} amount={amount}></roadsync-payment-form>
        )
    }
}
```

### Polyfills

RoadSync.js uses modern web techologies, and might need polyfills depending on
what browser support you target and how you plan on integrating it.

We use:

- fetch [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) [polyfill](https://github.com/github/fetch) [caniuse](https://caniuse.com/fetch)
- Web components [MDN](https://developer.mozilla.org/en-US/docs/Web/Web_Components) [polyfill](https://www.webcomponents.org/polyfills) [caniuse](https://caniuse.com/?search=web%20components)

There's a good chance you'll want to include these polyfills for widest browser support:

```html
<body>
  <!-- start polyfills -->
  <script src="https://unpkg.com/@webcomponents/webcomponentsjs@2.6.0/webcomponents-loader.js"></script>
  <script src="https://unpkg.com/lit@2.2.0/polyfill-support.js"></script>

  <!-- start RoadSync.js -->
  <script type="module" src="https://unpkg.com/@roadsync/js:@1/dist/roadsync.js" />
  <body>
    <roadsync-checkout location-id="XXXXXXXXXX" api-key="XXXXXXXXXX"></roadsync-checkout>
  </body>
```

### Using an iframe

In the near future, we'll also support an iframe integration.

## Advanced Usage

### `window` events

When a payment is complete, we'll post the transaction details via a `CustomEvent` attached to the window.

```javascript
window.addEventListener('roadsync.transaction.complete', (ev) {
    console.log('RoadSync transaction complete', ev.detail);
});
```

When a payment fails, we'll post the transaction details via a `CustomEvent` attached to the window.

```javascript
window.addEventListener('roadsync.transaction.failed', (ev) {
    console.log('RoadSync transaction failed', ev.detail);
});
```

### Verifying the transaction status

**IMPORTANT: Do not rely solely on the JavaScript events to verify transaction completion.**
You'll need to use your server to verify that the transaction is actually finished by contacting the RoadSync
API directly **before** shipping a product or considering a transaction to be complete.
