Cardinal.complete

This function returns the result of an authorization attempt back to Cardinal systems. Some payment brands like Apple Pay and Visa Checkout require you to report the authorization attempt outcome back to the payment brand before the transaction can be completed.

Cardinal.complete({
	Status: "Success"
});

This event returns back a promise that will be fulfilled when the payment sheet has been closed. You can execute any code that needs to be run after the payment sheet has been dismissed by using the .then function. Additionally you can use the .catch function to catch any errors encountered. 

Cardinal.complete({
		Status: "Success"
	})
	.then(function(){
		// Executes when the payment sheet has been dismissed
	})
	.catch(function(error){
		// Triggers if any error is thrown. This would include any errors encountered in your .then callback, if you're not properly catching errors.
	})

Cardinal.configure

This optional function allows you to setup high level configuration options for Songbird. Omitting this function from you integration will not cause any issues, it will just result in you receiving default configuration options. This function should be called prior to Songbird.setup.

Cardinal.configure(CONFIGURATION_OBJECT);

Cardinal.configure({
	logging: {
		level: 'on'
	}
});

Cardinal.continue 

CCA

This function allows you to continue a transaction that was started elsewhere. Currently the only payment brand that supports Cardinal.continue() is CCA during a CCA hybrid transaction. When called, this function will trigger and handle all CCA authentication steps when provided with the proper data. The results of the authentication attempt will be returned to the merchant via the payments.validated event.

Arguments

Cardinal.continue(PAYMENT_BRAND, CONTINUE_DATA, ORDER_OBJECT, NEW_JWT)

Order object in the below example has been shortened for brevity.

Cardinal.continue('cca',
{
    "AcsUrl":"https://testcustomer34.cardinalcommerce.com/merchantacsfrontend/pareq.jsp?vaa=b&gold=AAAAAAAA...AAAAAAA",
    "Payload":"eNpVUk1zgjAQvedXME7PJEFBVdKt1CECeDkVCk2PcfcnNjv8Kr+7tx4nlbGOcz/se6G1uMENPTPeeIz1G37WGEUth7YnpO21TfTvF3wDCBqspQ=="
},
{
    "OrderDetails":{
        "TransactionId" :"123456abc"
        // Add the rest of the Order object
    }
});

Cardinal.off

The off function will remove an event listener that was subscribed via the Cardinal.on function. This is a way to clean up any event listeners that may no longer be necessary.

Cardinal.off(EVENT_NAME_SPACE);

Cardinal.off('payments.setupComplete');

Cardinal.on

Songbird uses an event based system to handle asynchronous processing. This event system lets you subscribe to different events and execute a callback function when that event is triggered internally by Songbird. These events are used give the merchant insight into whats happening in real time, or to hand back control when Songbird has been driving something like a CCA authentication flow. Once you have subscribed to an event, you do not need to re-subscribe to the event again, you only need to subscribe once per page load. If you try to subscribe to an event more than once, your callback will trigger again on each subsequent subscription. So if you subscribe to an event twice, your callback will be triggered twice. If you subscribe 4 times your callback is triggered 4 times. This is because there can be more than 1 listener to any given event, you as the subscriber are responsible for managing your own subscriptions.

Some events will pass back arguments to your callback functions. Refer to the event's specific documentation below to determine what arguments, if any, are passed back for specific events.

You can remove an event listener by using the Songbird.js#Cardinal.off function.

Cardinal.on(EVENT_NAME_SPACE, CALLBACK_FUNCTION);

Events

The below section covers the different events you may subscribe to.

payments.setupComplete

An event that is triggered when Songbird has completed loading and is ready to run transactions. When alternative payments are being used, like PayPal, this event is only triggered when the payment buttons have finished loading.

Callback Arguments

The below table describes the arguments that are passed back into the merchants callback function. Arguments are ordered as they are passed back to the callback function, with the top row being argument[0].

Cardinal.on('payments.setupComplete', function(setupCompleteData){
    // Do something
});

payments.validated

The final event from Songbird in any transaction. All interactions from Songbird terminate with this event regardless of success or failure of the transaction, and control is handed back to the merchant.  The only exception to this is with redirect payment brands. Since those payment brands require the consumer to redirect away from the merchants site, Songbird is unable to receive the final transaction result in those cases. Refer to the /wiki/spaces/STAG/pages/1048657 for more on how to handle the response for redirect flows.

Arguments passed back to the callback function you setup for this event will inform you of the outcome of the transaction attempt. Since both success and failure responses will trigger this event, so its important that you have logic within your callback that can handle success and failure cases.

Callback Arguments

The below table describes the arguments that are passed back into the merchants callback function. Arguments are ordered as they are passed back to the callback function, with the top row being argument[0].

Cardinal.on('payments.validated', function(decodedResponseData, responseJWT){
    // Do something
});

A Cardinal Cruise transaction can end in 3 main different use cases:

Response Data

At minimum the response data will include a base object as seen below. However depending on what occurred in the response additional fields may be present.

{
	"Validated": false,
    "ErrorNumber": 0,
    "ErrorDescription": "",
    "ActionCode": "",
}

Below you will find some samples of different values returned to the payments.validated event. These JSON objects would be the 1st argument and the Payload claim of the response JWT where a response JWT was returned.

Successful Response

The below sample illustrates a CCA successful response.

{
   "Validated": true,
   "ActionCode": "SUCCESS",
   "ErrorNumber": 0,
   "ErrorDescription": "Success",
   "Payment": {
       "Type": "CCA",
       "ExtendedData": {
           "CAVV": "AAABAWFlmQAAAABjRWWZEEFgFz8=",
           "ECIFlag": "05",
           "XID": "ODQwbFJWQ2tUNkczczYyR0kyZDA=",
           "ThreeDSVersion": "1.0.2",
           "Enrolled": "Y",
           "PAResStatus": "Y",
           "SignatureVerification": "Y"
       },
       "ProcessorTransactionId": "840lRVCkT6G3s62GI2d0"
   }
}

API Level Error

An API level error is an error that occurred at Centinel API causing the request to fail for one reason or another. These errors will include a response JWT to be validated.

{
    "Validated": false,
    "ErrorNumber": 4000,
    "ErrorDescription": "Validation Error A valid merchant consumer session ID is required.",
    "ActionCode": "ERROR",
    "Payment": {}
}

Service Level Error

A service level error is a hight level error that will not include a response JWT.

{
    "Validated": false,
    "ErrorNumber": 1000,
    "ErrorDescription": "Error processing request. We have encountered an unexpected error.",
    "ActionCode": "ERROR",
    "Payment": {}
}

order.update

Event to allow the merchant to pass in order data to send via the browser. This event will update the local cached order object within Songbird but it will not push anything to the Cardinal infrastructure. This event is not guaranteed to trigger for every payment method / brand, but in general this event is triggered by Songbird when a payment button has been clicked.

To update the order object, simply return the object from the callback:

Cardinal.on('order.update', function(){
	return {
		"OrderDetails":{
			"OrderDescription":"Updated order"
		}
	};
});

UI Events

UI Events are events that are triggered when Songbird is managing view state of a payment brand. As of now these events are only triggered for a CCA transactions as alternative payment brands like PayPal and Visa Checkout manage their own view state so Songbird has little to no insight when specific events are triggered.

ui.close

Event that triggers when a modal window closes. This event will trigger regardless of the modal being visible or hidden.

ui.render

Event that triggers when a visible modal window opens. This event does not trigger for hidden windows.

ui.renderHidden

Event that triggers when an invisible modal opens. For example this would happen when CCA is run in 'stealth mode' for RIBA cards.

ui.inline.setup

Event that triggers when an inline view needs to be rendered by the merchant. We provide them with the element to inject into their page, and wait for them to trigger a callback to tell us they're ready to move on.

ui.loading.close

Event that triggers when the loading screen closes. This event only triggers when loading has been displayed using the 'displayLoading' configuration option.

ui.loading.render

Event that triggers when the loading screen opens. This event only triggers when loading has been displayed using the 'displayLoading' configuration option.

Cardinal.start 

CCA

Manually start a transaction. This event is intended to be used with payment brands that do not have payment buttons like CCA. Refer to the specific payment brand documentation to determine if a specific payment brand requires the use of this function.

Cardinal.start('cca', {
  "OrderDetails":{
	"OrderDescription":"An updated description"
  }
});

Cardinal.setup

This function tells Songbird what type of event you are planning on completing on the page its running on, and in turn what files it needs to bootstrap itself with to facilitate that event.

Initialization Types

init 

The most common way to start Songbird. The 'init' setup handler is a generic entry point to start Songbird for transaction processing. Every transaction flow will start with a 'init' flow.

Cardinal.setup('init', {
    "jwt":"merchant_jwt_value"
});

complete

The complete message is used to inform Cardinal servers on the status of an authorization attempt the merchant has made. In some alternative payment brands, the merchant is required to report the authorization attempt status back to the alternative payment brand after attempting to secure funds for a transaction. This is most common in wallet type alternative payment brands where the merchant is responsible for the actual transfer of funds from the consumer. This initialization entry point is a way for a merchant to impart the authorization status information to Cardinal servers to be forwarded to the appropriate alternative payment brands without reinitializing Songbird for transactions. Using this flow instead of the standard 'init' flow will result in faster Songbird initialization and prevent payment brands from being loaded unnecessarily. This flow is ideal for a merchant using the following transaction flow:

1. Load a page with Cardinal.setup('init'), loading alternative payment brand buttons.
2. User clicks an alternative payment brand button and completes the flow with the payment brand.
3. 'payments.validated' is triggered with the alternative payment brand results that require a payment authorization
4. merchant posts results to back end system and completes a server to server authorization attempt
5. merchant redirects and renders a ordered completed page for the end user rendering a Cardinal.setup('complete') on the page and returning the status of the authorization attempt back to Cardinal servers.

Cardinal.setup('complete', {"Status":"Success"}

confirm 

REDIRECT TYPE

This initialization type is used only with redirect type payment brands like PayPal Express Checkout.  Confirm allows you to take a server to server response from Centinel API and feed it into Songbird to process like the response was routed through Songbird. This allows you to use existing payments.validate event handling you may have written to support other feature like CCA to consume a response JWT that is received on your ConfirmUrl.

Cardinal.setup('confirm', {
    "jwt":"merchant_jwt_value",
	"cardinalResponseJwt": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJNaWRhc05vRHYiLCJpYXQiOjE0OTY2ODU0MTUsImV4cCI6MTQ5NjY5MjYxNSwianRpIjoiOTRhMmJmNGEtZjFkNS00Y2M2LTlmYmYtODZlYjUzZmJhYWE5IiwiQ29uc3VtZXJTZXNzaW9uSWQiOiI2ZDI4YTgzNS01YzViLTQwY2YtOTQ5Yy03NDU0YzA3YmU3ZTEiLCJSZWZlcmVuY2VJZCI6IjZkMjhhODM1LTVjNWItNDBjZi05NDljLTc0NTRjMDdiZTdlMSIsIlBheWxvYWQiOnsiVmFsaWRhdGVkIjp0cnVlLCJQYXltZW50Ijp7IlR5cGUiOiJDQ0EiLCJQcm9jZXNzb3JUcmFuc2FjdGlvbklkIjoiZjZsbWVuNTAxdXdUSmY2OWVVMTAiLCJFeHRlbmRlZERhdGEiOnsiQ0FWViI6IkFBQUJBV0ZsbVFBQUFBQmpSV1daRUVGZ0Z6K1x1MDAzZCIsIkVDSUZsYWciOiIwNSIsIlhJRCI6IlpqWnNiV1Z1TlRBeGRYZFVTbVkyT1dWVk1UQVx1MDAzZCIsIkVucm9sbGVkIjoiWSIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkF1dGhvcml6YXRpb25Qcm9jZXNzb3IiOnsiUHJvY2Vzc29yT3JkZXJJZCI6IjgwMDA1NzU1OTg4NjExMDYiLCJQcm9jZXNzb3JUcmFuc2FjdGlvbklkIjoiTTBtTEY4Q2Q0WThsSTM1czVmbDAiLCJSZWFzb25Db2RlIjoiMCIsIlJlYXNvbkRlc2NyaXB0aW9uIjoiIn0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.OIa9HvZjKo0tzSqpavu4nNI_QZWRkQTrIcYMzejaYy8"
});

Cardinal.trigger

This function triggers an event within Songbird. This is a way to actively send Songbird data instead of waiting passively for events to occur.

Cardinal.trigger(EVENT_NAME_SPACE, DATA);

Cardinal.trigger('jwt.update', 'my_new_jwt_value');

Events

accountNumber.update

This event will update the local cached account number within Songbird and trigger a bin profiling call into Cardinal systems if the bin has not been seen within the current browser session. Bin profiling will complete any device detection requirements the card issuer may have behind the scenes and as early as possible to help reduce the length of time authentication process takes when the user attempts to make a purchase. 

Cardinal.trigger('accountNumber.update', '4753000096321458');

bin.process

An event to profile a bin (e.g. first 9 of card number) up to the full card number of the consumer (e.g. max of 19 digits). This event will run the issuer’s Method URL (if one exists as it’s optional for issuers) and resolve upon completion. The implementor should wait for this event to complete before moving forward with a transaction. This bin.process is a way to specifically run the EMV 3DS Method URL, we will receive the bin, check to see if there is a corresponding EMV 3DS Method URL, and open up the Method URL per EMV 3DS specification if one was returned.  If no Method URL was provided, we will not perform additional device data collection at this time.

The bin.process event will return a promise that will be fulfilled when the EMV 3DS Method URL has been completed. The promise result will include a single object containing the result of the 3DS Method URL attempt. In the event of a MethodURL failure the Status field will be set to false. This allows you to execute any code that needs to be run after the promise has been returned by using the .then function.  Additionally, you can use the .catch function to catch any errors encountered during processing, excluding the MethodURL failure.

Implementation Example:   In the below example we demonstrate how to call bin profiling, how to handle the result (boolean value) or an exception, and then how to move on with CCA in a Cruise Standard implementation. The below example will move forward with CCA regardless of the success or failure of bin profiling, but this may not fit in every merchants business logic.

Cardinal.trigger("bin.process", '1234567894561237')
  .then(function(results){
    if(results.Status) {
        // Bin profiling was successful. Some merchants may want to only move forward with CCA if profiling was successful
    } else {
        // Bin profiling failed
    }
 
    // Bin profiling, if this is the card the end user is paying with you may start the CCA flow at this point
    Cardinal.start('cca', myOrderObject);
  })
  .catch(function(error){
    // An error occurred during profiling
  })

Merchants using Cardinal Cruise Hybrid implementation will need to run the Lookup Request upon receiving the bin.process result.

Cardinal.trigger("bin.process", '1234567894561237')
  .then(function(results){
    if(results.Status) {
        // Bin profiling was successful. Some merchants may want to only move forward with CCA if profiling was successful
    } else {
        // Bin profiling failed
    }
  })
  .catch(function(error){
    // An error occurred during profiling
  })

jwt.update

An event to allow the merchant to change the jwt at any point.  This event will update the local cached order object within Songbird but it will not push anything to the Cardinal infrastructure. This removed the need to pass in a new jwt into an event such as Cardinal.start or Cardinal.continue.

Cardinal.trigger('jwt.update', 'my_new_jwt_value');

order.update

An event to allow the merchant to pass in order data to send via the browser. This event will update the local cached order object within Songbird but it will not push anything to the Cardinal infrastructure. This means triggering this event after a completed start message will not update the order within Cardinal.

Cardinal.trigger('order.update', {OrderDetails: {Amount: 1500}});