> For the complete documentation index, see [llms.txt](https://support.paycargo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.paycargo.com/product-docs/paycargo-products/express-checkout-documentation.md).

# Express Checkout Documentation

A seamless experience within the framework of your choice

***

## Overview

By implementing PayCargo Express Checkout, a seamless experience is afforded to its users who may work within the framework of their choice. In effect, users will not be redirected to different pages and may, instead, remain within the host portal.

{% hint style="info" %}
You may install the PayCargo Checkout component by loading it through script tag, as detailed below.
{% endhint %}

## Setting up the Component Using Different Frameworks

### JavaScript

Integrating a component can be done via script tag within the `head` of an HTML page, and then calling the component within the `body`.

#### How to Pass Data to the PayCargo Checkout Component

<mark style="color:$primary;">**Properties**</mark>

| Property Name      | Values            | Type                       | Required                                                           | Description                                                                                                                        |
| ------------------ | ----------------- | -------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| **options**        |                   | `object`                   | <i class="fa-check-circle" style="color:green;">:check-circle:</i> | Passing necessary options into the component.                                                                                      |
|                    | env               | `string`                   | <i class="fa-check-circle" style="color:green;">:check-circle:</i> | Options: `local`, `dev`, `test`, `prod`                                                                                            |
|                    | code              | `string`                   | <i class="fa-check-circle" style="color:green;">:check-circle:</i> | PayCargo `integration` code                                                                                                        |
|                    | originURL         | `string`                   | <i class="fa-check-circle" style="color:green;">:check-circle:</i> | Host URL where component is loaded                                                                                                 |
|                    | brand             | `string`                   |                                                                    |                                                                                                                                    |
|                    | size              | `string`                   |                                                                    | Options: `full`, `lg`, `md` where the default size is `lg`                                                                         |
| **pcTransactions** |                   | `object[]`                 | <i class="fa-check-circle" style="color:green;">:check-circle:</i> | PayCargo transaction object                                                                                                        |
|                    | type              | `string`                   | <i class="fa-check-circle" style="color:green;">:check-circle:</i> | Transaction type (example: `Invoice`, `Terminal Fee`, etc)                                                                         |
|                    | vendorId          | `number` / `null`          | <i class="fa-check-circle" style="color:green;">:check-circle:</i> |                                                                                                                                    |
|                    | number            | `string`                   | <i class="fa-check-circle" style="color:green;">:check-circle:</i> |                                                                                                                                    |
|                    | direction         | `'Inbound'` / `'Outbound'` | <i class="fa-check-circle" style="color:green;">:check-circle:</i> |                                                                                                                                    |
|                    | total             | `number`                   | <i class="fa-check-circle" style="color:green;">:check-circle:</i> | Amount of total transaction. If transaction lines are present, then the total should equal the sum of all transaction line amounts |
|                    | arrivalDate       | `string` / `date`          |                                                                    |                                                                                                                                    |
|                    | hasArrived        | `'Y'` / `'N'`              | <i class="fa-check-circle" style="color:green;">:check-circle:</i> |                                                                                                                                    |
|                    | bolLink           | `string`                   |                                                                    |                                                                                                                                    |
|                    | parent            | `string`                   |                                                                    |                                                                                                                                    |
|                    | shipperRefNumber  | `string`                   |                                                                    |                                                                                                                                    |
|                    | customerRefNumber | `string`                   |                                                                    |                                                                                                                                    |
|                    | subcategory       | `string`                   |                                                                    |                                                                                                                                    |
|                    | paymentDueDate    | `date`                     |                                                                    |                                                                                                                                    |
|                    | notes             | `string` / `null`          |                                                                    |                                                                                                                                    |
|                    | transactionLines  | `array`                    |                                                                    |                                                                                                                                    |

<mark style="color:$primary;">**Transaction Lines**</mark>

<table data-header-hidden><thead><tr><th></th><th></th><th width="149"></th><th></th><th></th></tr></thead><tbody><tr><td>Property Name</td><td>Values</td><td>Type</td><td>Required</td><td>Description</td></tr><tr><td><strong>transactionLines</strong></td><td></td><td><code>object</code></td><td></td><td>Passing necessary options into the component. Note: these property names are case sensitive</td></tr><tr><td></td><td>AMOUNT</td><td><code>number</code></td><td><i class="fa-check-circle" style="color:green;">:check-circle:</i></td><td>Amount for transaction line</td></tr><tr><td></td><td>DESCRIPTION</td><td><code>string</code></td><td><i class="fa-check-circle" style="color:green;">:check-circle:</i></td><td></td></tr><tr><td></td><td>START_DATE</td><td><code>string</code> / <code>date</code></td><td></td><td></td></tr><tr><td></td><td>END_DATE</td><td><code>string</code> / <code>date</code></td><td></td><td></td></tr><tr><td></td><td>QUANTITY</td><td><code>number</code></td><td></td><td></td></tr><tr><td></td><td>UNIT_PRICE</td><td><code>number</code></td><td></td><td></td></tr><tr><td></td><td>containerNumber</td><td><code>string</code></td><td></td><td>OSRA: container number</td></tr><tr><td></td><td>billOfLading</td><td><code>string</code></td><td></td><td>OSRA: BOL number</td></tr><tr><td></td><td>availabilityDate</td><td><code>string</code> / <code>date</code></td><td></td><td>OSRA: first available date</td></tr><tr><td></td><td>pod</td><td><code>string</code></td><td></td><td>OSRA: port of discharge</td></tr><tr><td></td><td>sfd</td><td><code>string</code></td><td></td><td>OSRA: start free day</td></tr><tr><td></td><td>lfd</td><td><code>string</code></td><td></td><td>OSRA: last free day</td></tr><tr><td></td><td>freeTimeDays</td><td><code>string</code></td><td></td><td>OSRA: free time days</td></tr><tr><td></td><td>erd</td><td><code>string</code></td><td></td><td>OSRA: earliest return date</td></tr><tr><td></td><td>invoiceDate</td><td><code>string</code></td><td></td><td>OSRA: invoice date</td></tr><tr><td></td><td>invoiceDueDate</td><td><code>string</code></td><td></td><td>OSRA: invoice due date</td></tr><tr><td></td><td>dateChargesOccurred</td><td><code>string</code>/<code>string[]</code></td><td></td><td>OSRA: date charges occurred</td></tr><tr><td></td><td>ddr</td><td><code>string</code></td><td></td><td>OSRA: demurrage detention rule</td></tr><tr><td></td><td>feeContact</td><td><code>string</code></td><td></td><td>OSRA: mitigation contact</td></tr><tr><td></td><td>feeMitigation</td><td><code>string</code></td><td></td><td>OSRA: fee mitigation</td></tr><tr><td></td><td>complianceStatement</td><td><code>string</code></td><td></td><td>OSRA: compliance statement</td></tr><tr><td></td><td>commonCarrierStatement</td><td><code>string</code></td><td></td><td>OSRA: common carrier statement</td></tr><tr><td></td><td>refund</td><td><code>string</code></td><td></td><td>OSRA: refund statement</td></tr><tr><td></td><td>dispute</td><td><code>string</code></td><td></td><td>OSRA: dispute statement</td></tr><tr><td></td><td>waiver</td><td><code>string</code></td><td></td><td>OSRA: waiver statement</td></tr><tr><td></td><td>billedPartyJustification</td><td><code>string</code></td><td></td><td>OSRA: billed party justification statement</td></tr></tbody></table>

<mark style="color:$primary;">**Examples on Passing Values to PayCargo Checkout**</mark>

In the `element` of the `HTML` file:

<figure><img src="https://3099532018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EqxRfGgzDHtXYK82e2L%2Fuploads%2FFHcb6ViIEGOnLMZRFEcc%2Fimage.png?alt=media&amp;token=8b76ea0a-d0a3-4a1a-adf4-ad885f500e5f" alt=""><figcaption></figcaption></figure>

Please note the following:

* We have indicated `test` here as the environment for your testing purposes.
* Your URL must be provided to PayCargo’s Development Team so it may be whitelisted.
* You must request `code` and `brand` from PayCargo’s Development Team as it must be supplied for your particular integration.
* You may choose how to display the modal, i.e. how much space the modal will take up within your portal.
* The Console will show 404 errors if the Options property is not being passed.

<figure><img src="https://3099532018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EqxRfGgzDHtXYK82e2L%2Fuploads%2F2xyEXPF2JsPnkl9ysb8y%2Fimage.png?alt=media&amp;token=69fcc4d7-7baa-457b-b244-1cc09da738f3" alt=""><figcaption></figcaption></figure>

<mark style="color:$primary;">**Example of How to Pass Data to the Transaction Object**</mark>

If you successfully passed transaction object(s) to the `pc-transactions` property and clicked the “PayCargo Checkout” button, then it should display as such:

<figure><img src="https://3099532018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EqxRfGgzDHtXYK82e2L%2Fuploads%2FFuH36clD8INKWsznTK45%2Fimage.png?alt=media&amp;token=98262413-1c3d-46d8-871e-4cf157372433" alt=""><figcaption></figcaption></figure>

<mark style="color:$primary;">**Event Listeners**</mark>

There are two different event listeners that may be implemented: (1) when a user approves a transaction and (2) when a user closes the modal for any reason. We strongly advise listening to both of these events so action may be taken in accordance with the response given. As such, the possibilities of misalignment or discrepancies are minimized.

To access these events, select the component through the `HTML` `querySelector` and add an event listener for the ‘close’ event:

When a user closes the PayCargo Checkout modal without taking any action, the event should return the following object `detail`:When a user has successfully made a payment, a similar event is emitted. The `eventName` is `paymentResponse`:The `event.detail` structure for a successful payment is as follows:

<figure><img src="https://3099532018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EqxRfGgzDHtXYK82e2L%2Fuploads%2FyfJAAh3mT3O7F4Mu5Piw%2Fimage.png?alt=media&amp;token=46080c2b-f89a-4b00-ab02-f5d9e0b27b52" alt=""><figcaption></figcaption></figure>

The properties that may be of most use are:

> **data.error**
>
> * create – any transaction that encountered an error during **creation**
> * approve – any transaction that encountered an error when **approving**
>
> **data.success**
>
> * create – this contains all transactions that have been successfully **created**
> * approve – this contains all transactions that have been successfully **approved**

This is an example of a JSON object of the response:

### React TypeScript

Please declare the following to avoid typescript errors:

To be able to load the PayCargo Checkout widget, utilize `useEffect` to create and load the JS module script.

src URLs for different environments:

* `DEV / local development`: <https://jsdev.paycargo.com/paycargo-checkout/paycargo-checkout.esm.js>
* `UAT`: <https://jstest.paycargo.com/paycargo-checkout/paycargo-checkout.esm.js>
* `PROD`: <https://js.paycargo.com/paycargo-checkout/paycargo-checkout.esm.js>

<mark style="color:$primary;">**Example of How to Pass Data to the Transaction Object**</mark>

Now, import React into the file, set up the `useState`, and define `handleOnClick`. We have included some dummy transaction information to fully illustrate what this implementation would look like.

<mark style="color:$primary;">**Event Listeners**</mark>

We want to listen to two types of events: (1) when the transaction is being closed to see if any action was taken, and (2) when a payment has been attempted or successfully approved. To do this, we need to implement `useEffect` and add event listeners to the PayCargo Checkout component.

### Angular

To be able to load the `PayCargo Express Checkout` widget we need to `OnInit` & `OnDestroy` from angular/core

src URLs for different environments:

* `DEV / local development`: <https://jsdev.paycargo.com/paycargo-checkout/paycargo-checkout.esm.js>
* `UAT`: <https://jstest.paycargo.com/paycargo-checkout/paycargo-checkout.esm.js>
* `PROD`: <https://js.paycargo.com/paycargo-checkout/paycargo-checkout.esm.js>

Next, pass `options` into the component within the `app.component.ts` file.

Note: denoting the `size` is not required. It will default to `large` if omitted. The available options are ‘md’ (medium), ‘lg’ (large), and ‘full’.

In `app.component.html`, declare the Element to load the Component onto the page.

An example of a list of transactions would look like the following:

<figure><img src="https://3099532018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EqxRfGgzDHtXYK82e2L%2Fuploads%2FG3vL6bst4OpZJpBMNtmJ%2Fimage.png?alt=media&amp;token=66119935-2e34-4466-bd97-c5c07b09fd71" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3099532018-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4EqxRfGgzDHtXYK82e2L%2Fuploads%2F2pKAuHhpYcCdQC7jmd8n%2Fimage.png?alt=media&amp;token=72b551b8-6c9f-4ce6-92bf-8bd4718f9a49" alt=""><figcaption></figcaption></figure>

<mark style="color:$primary;">**Event Listeners​**</mark>

We want to listen to two types of events: (1) when the transaction is being closed to see if any action was taken, and (2) when a payment has been attempted or successfully approved. To do this, we need to implement Host Listeners to the PayCargo Checkout component.

`onClose` will run every time the user closes the modal — whether that happens before payment is made or afterwards. `onPcPayment` will run whenever the user attempts payment — whether the response succeeds or fails.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://support.paycargo.com/product-docs/paycargo-products/express-checkout-documentation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.