0.13.18 • Published 4d ago

@paycargo/js

Licence

ISC

Version

0.13.18

Deps

Size

5.8 MB

Vulns

Weekly

Summary Dependency Versions

Overview

By implementing PayCargo 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.

There are two ways to install the PayCargo Checkout component:

Load through script tag
NPM packages

Setting up the Component Using 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.

<html>
   <head>
     <script
      type="module"
      src="https://jstest.paycargo.com/checkout.paycargo.com/paycargo-checkout/paycargo-checkout.esm.js">
     </script>
    </head>
   <body>
     <paycargo-checkout></paycargo-checkout>
   </body>
 </html>

How to Pass Data to the PayCargo Checkout Component

Properties

Property Name	Values	Type	Description
options		`object`	Passing necessary options into the component
	env	`string`	Options: `local`, `dev`, `test`, `prod`
	code	`string`	PayCargo `integration` code
	originURL	`string`	Host URL where component is loaded
	brand	`string`
	size	`string`	Options: `full`, `lg`, `md` where the default size is `md`
visible	true / false	`boolean`	To make PayCargo Checkout component visible or hidden
pcTransactions		`object[]`	PayCargo transaction object
	type	`string`	Transaction type (example: `Invoice`, `Terminal Fee`, etc)
	vendorId	`number` / `null`
	number	`string`
	direction	`'Inbound'` / `'Outbound'`
	total	`number`	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'`
	bolLink	`string`
	parent	`string`
	shipperRefNumber	`string`
	customerRefNumber	`string`
	subcategory	`string`
	paymentDueDate	`date`
	notes	`string` / `null`
	transactionLines	`array`

Transaction Lines

Property Name	Values	Type	Description
transactionLines		`object`	Passing necessary options into the component. Note: these property names are case sensitive
	AMOUNT	`number`	Amount for transaction line
	DESCRIPTION	`string`
	START_DATE	`string` / `date`
	END_DATE	`string` / `date`
	QUANTITY	`number`
	UNIT_PRICE	`number`
	containerNumber	`string`	OSRA: container number
	availabilityDate	`string` / `date`	OSRA: first available date
	pod	`string`	OSRA: port of discharge
	sfd	`string`	OSRA: start free day
	lfd	`string`	OSRA: last free day
	freeTimeDays	`string`	OSRA: free time days
	ddr	`string`	OSRA: demurrage detention rule
	feeContact	`string`	OSRA: mitigation contact
	complianceStatement	`string`	OSRA: compliance statement
	commonCarrierStatement	`string`	OSRA: common carrier statement

Examples on Passing Values to PayCargo Checkout

In the element of the HTML file:

<paycargo-checkout options='{
    "env": "test",
    "code": "ecuww",
    "originURL": "http://localhost:3333/",
    "brand": "ecuww",
    "size": "full"
  }'
/>

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.

Example of How to Pass Data to the Transaction Object

  <script>

  const transactions = [
    {
      vendorId: 279602,
      type: 'AWB',
      number: 'abc98211',
      total: 150.0
    },
    {
      vendorId: 279602,
      type: 'Invoice',
      number: 'abc98212',
      total: 103.0
    },
    {
      vendorId: 280003,
      type: 'Terminal Fee',
      number: 'abc98213',
      total: 204.0
    }
  ]

  let selected = [] // sets the selected transactions
  const paycargoCheckout = document.querySelector('paycargo-checkout')
  const checkboxes = document.getElementsByName('trans-box')
  checkboxes.forEach((el) => {
    el.addEventListener('click', event => {
      const {target} = event
      const {name, value, checked} = target
      if (checked) {
        selected.push(transactions[value])
        paycargoCheckout.setAttribute('pc-transactions', JSON.stringify(selected))
      } else {
        selected = selected.filter(trans => trans.index != value)
        paycargoCheckout.setAttribute('pc-transactions', JSON.stringify(selected))
      }
    })
  })

  </script>

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

Event Listeners

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:

  const paycargoCheckout = document.querySelector('paycargo-checkout')

  paycargoCheckout.addEventListener('close', event => {
    console.log({event})
    console.log('Closed, event.details', event.detail)
    console.log('Closed, event.details.data', event.detail.data)
  })

When a user closes the PayCargo Checkout modal without taking any action, the event should return the following object detail:

data: null
result: {msg: 'Closed by user.', code: 204}

When a user has successfully made a payment, a similar event is emitted. The eventName is paymentResponse:

  const paycargoCheckout = document.querySelector('paycargo-checkout')

  paycargoCheckout.addEventListener('paymentResponse', event => {
    console.log('PayCargo Payment Response Event', event.detail)
  })

The event.detail structure for a successful payment is as follows:

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:

{
    "result": {
        "msg": "Successfully created and approved batch transactions",
        "code": 200
    },
    "data": {
        "success": {
            "approve": [
                {
                    "transactionId": 591842,
                    "vendorId": 281283,
                    "payerId": 283270,
                    "userEmail": "amorejon+mafia@paycargo.com",
                    "totalAmount": 22880,
                    "approvalDate": "2023-10-02T18:02:53-04:00",
                    "approvalDateUTC": "2023-10-02T22:02:53Z",
                    "number": "SEGU2028243",
                    "type": "Demurrage",
                    "transactionFee": 12.5,
                    "financeFee": 0,
                    "processingFee": 0,
                    "annualFee": 0,
                    "currency": "USD",
                    "payerName": "The Capone Mafia",
                    "vendorName": "YUSEN TERMINAL INC (LA) BERTH 214",
                    "payerRefNumber": null,
                    "customerRefNumber": "6018998010",
                    "parent": "unique id from post",
                    "subcategory": "STORAGE CHARGES",
                    "shipperRefNumber": "89",
                    "bolLink": "HAB",
                    "notes": "pc-checkout",
                    "arrivalDate": null,
                    "departureDate": null,
                    "payerInternalNumber": "",
                    "payerFileNumber": "",
                    "payerVoucherNumber": "",
                    "payerInvoiceNumber": "",
                    "msg": "Transaction paid",
                    "result": {
                        "msg": "Transaction paid",
                        "code": "200"
                    }
                }
            ],
            "create": [
                {
                    "result": {
                        "msg": "Transaction created",
                        "code": 201
                    },
                    "data": {
                        "transactionId": 591842,
                        "vendorId": 281283,
                        "payerId": 283270,
                        "userEmail": "amorejon+mafia@paycargo.com",
                        "totalAmount": 22880,
                        "approvalDate": null,
                        "approvalDateUTC": null,
                        "number": "SEGU2028243",
                        "type": "Demurrage",
                        "currency": "USD",
                        "payerName": "The Capone Mafia",
                        "payerRefNumber": null,
                        "customerRefNumber": "6018998010",
                        "parent": "unique id from post",
                        "subcategory": "STORAGE CHARGES",
                        "shipperRefNumber": "89",
                        "bolLink": "HAB",
                        "notes": "pc-checkout",
                        "arrivalDate": null,
                        "departureDate": null,
                        "payerInternalNumber": "",
                        "payerFileNumber": "",
                        "payerVoucherNumber": "",
                        "payerInvoiceNumber": "",
                        "transactionLines": {
                            "error": [],
                            "success": [
                                {
                                    "msg": "Successfully created transaction line",
                                    "transactionLineId": 78262
                                }
                            ]
                        }
                    }
                }
            ]
        },
        "error": {
            "approve": [],
            "create": []
        },
        "transactions": [
            {
                "transactionId": 591842,
                "vendorId": 281283,
                "payerId": 283270,
                "userEmail": "amorejon+mafia@paycargo.com",
                "totalAmount": 22880,
                "approvalDate": "2023-10-02T18:02:53-04:00",
                "approvalDateUTC": "2023-10-02T22:02:53Z",
                "number": "SEGU2028243",
                "type": "Demurrage",
                "transactionFee": 12.5,
                "financeFee": 0,
                "processingFee": 0,
                "annualFee": 0,
                "currency": "USD",
                "payerName": "The Capone Mafia",
                "vendorName": "YUSEN TERMINAL INC (LA) BERTH 214",
                "payerRefNumber": null,
                "customerRefNumber": "6018998010",
                "parent": "unique id from post",
                "subcategory": "STORAGE CHARGES",
                "shipperRefNumber": "89",
                "bolLink": "HAB",
                "notes": "pc-checkout",
                "arrivalDate": null,
                "departureDate": null,
                "payerInternalNumber": "",
                "payerFileNumber": "",
                "payerVoucherNumber": "",
                "payerInvoiceNumber": "",
                "msg": "Transaction paid",
                "result": {
                    "msg": "Transaction paid",
                    "code": "200"
                }
            }
        ],
        "fundsAvailable": [ ],
        "batchHeader": {
            "dateCreated": "2023-10-02T22:02:50.605Z",
            "currency": "USD",
            "payerId": 283270,
            "asOf": "2023-10-02T22:02:50.605Z",
            "batchId": 285415
        }
    }
}