@paycargo/js
v0.5.2
Published
Paycargo web components for micro frontends
Downloads
291
Maintainers
courtney-mq
nbhavsar21
aszewc-mq
javier_media_query
mrodiles
andrearestrepox
kamila143
darboleda
idowling
sylthedev
nicholas-palomba1
mq-eduardo
indrias
dyurov
jcdieppa
mediaqueryinc
aqaffaf
scottmatsumoto
albe070
mannysin
dianyrs
forzaturian
nalvarezpayKeywords
Readme
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 | Required | Description |
|---------------|--------------------------|----------------------------|--------------------|----------------------------------------------------------|
| options | | object | :heavy_check_mark: | Passing necessary options into the component |
| | env | string | :heavy_check_mark: | Options: local, dev, test, prod |
| | code | string | :heavy_check_mark: | PayCargo integration code |
| | originURL | string | :heavy_check_mark: | Host URL where component is loaded |
| | brand | string | | |
| | size | string | | Options: full, lg, md where the default size is md |
| visible | true / false | boolean | :heavy_check_mark: | To make PayCargo Checkout component visible or hidden |
| pcTransactions| | object[] | :heavy_check_mark: | PayCargo transaction object |
| | type | string | :heavy_check_mark: | Transaction type (example: Invoice, Terminal Fee, etc)|
| | vendorId | number / null | :heavy_check_mark: | |
| | number | string | :heavy_check_mark: | |
| | direction | 'Inbound' / 'Outbound' | :heavy_check_mark: | |
| | total | number | :heavy_check_mark: | 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' | :heavy_check_mark: | |
| | bolLink | string | | |
| | parent | string | | |
| | shipperRefNumber | string | | |
| | customerRefNumber | string | | |
| | subcategory | string | | |
| | paymentDueDate | date | | |
| | notes | string / null | | |
| | transactionLines | array | | |
Transaction Lines
| Property Name | Values | Type | Required | Description |
|---------------|--------------------------|----------------------------|--------------------|----------------------------------------------------------|
| transactionLines| | object | | Passing necessary options into the component. Note: these property names are case sensitive |
| | AMOUNT | number | :heavy_check_mark: | Amount for transaction line |
| | DESCRIPTION | string | :heavy_check_mark: | |
| | 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
testhere 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
codeandbrandfrom 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:
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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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
}
}
}