Below are the different configuration options that can be used to initialize Songbird through Cardinal.configure function.

Full Example

The below JSON object is an example of using all configuration options possible. This is intended as an example of what each section of configuration should look like and how it should be structured.

Not intended for production

The below example is not intended for use, only to demonstrate the configuration structure.

All Options Example

{
    timeout: 6000,
	extendedTimeout: 4000,
    maxRequestRetries: 2,
    button:{
        containerId: 'Cardinal-Payments'
    },
    logging:{
        level: 'on'
    },
    payment:{
        view: 'modal',
        framework: 'bootstrap3',
        displayLoading: false
    },
	applePay: {
		button:{
			containerId: 'MySpecificApplePayId',
			color: 'black'
		}
	},
    paypal: {
        button: {
            containerId: 'MySpecificPayPalId',
            color: 'gold',
            shape: 'rect',
            style: 'paypal',
            size: '44px'
        },
        flow: 'checkout',
        intent: 'order',
        offerCredit: false,
        enableShippingAddress: false,
        shippingAddressEditable: true
    },
    visaCheckout: {
        button: {
            containerId: 'MySpecificVisaCheckoutId'
            color: '',
            size: '',
            height: '',
            width: '',
            locale: ''
        }
    }
}

Root Level Configuration

Field	Type	Default	Description
timeout	int	6000	The time in milliseconds to wait before a request to Centinel API is considered a timeout
extendedTimeout	int		extendedTimeout is only used in the event of the first request timing out. This configuration allows the merchant to set the timeout (in milliseconds) for subsequent retry attempts to complete a specific request to CentinelAPI. (This configuration would be useful when the merchant wants to set higher timeout values on requests). If the value for the extendedTimeout is set to less than 4000 milliseconds, then the value will be automatically reset to 4000 milliseconds.
maxRequestRetries	int	1	How many times a request should be retried before giving up as a failure.
logging	object
button	object
payment	object
applePay	object
paypal	object
visaCheckout	object

Logging

Settings for Songbird to log to the browser console

Field

Type

Default

Description

level

string

off

The level of logging to the browser console. Enable this feature to help debug and implement Songbird.

Possible Values:

off - No logging to console enabled. This is the setting to use for production systems.
on - Similar to info level logging, this value will provide some information about whats occurring during a transaction. This is recommended setting for merchants implementing Songbird
verbose - All logs are output to console. This method can be thought of as debug level logging and will be very loud when implementing Songbird, but is the level needed when getting support from the Cardinal team.

Button

A generic button configuration for all payment brands. Settings in this object will change settings for all payment brand buttons you are using. This is ideal if you want to have Songbird render all payment buttons into a custom container instead of using the default 'Cardinal-Payments' container.

Field	Type	Default	Description
containerId	string	Cardinal-Payments	The HTML Id value of the container to inject all payment buttons into.

Payment

CCA

An object to describe how you want the user interactions to behave. Currently this configuration only applies to CCA.

Field	Type	Default	Description
view	string	modal	What type of UI experience to use when Songbird injects payment brand UI elements into the page. Possible Values: modal - Render as a modal window. This view type renders the payment brand over your page, making it feel separate from your page.
framework	string	cardinal	What kind of view framework should be used to render the payment brand. If your site is using a supported framework and you have custom styles applied to it, we will use that framework to make keep the consistent look and feel of your site. When using any other frameworks than 'cardinal' your site is responsible for including the framework assets including CSS, JavaScript, and any other additional files needed. Possible Values: cardinal - Use the custom Cardinal view framework built and maintained by CardinalCommerce. Songbird will handle all UI rendering and styles, no additional work is needed. inline - Render inline to the page. This view type embeds the payment brand into the page making it feel like it's a part of your website. bootstrap3 - Use bootstrap 3 modal to render the UI elements. (Note: For more information regarding choosing your framework visit View Frameworks#Inline).
displayLoading	boolean	false	A flag to enable / disable a loading screen while requests are being made to Centinel API services. This can provide feedback to the end user that processing is taking place and they should not try to reload the page, or navigate away. This feature is currently applicable to Cardinal Cruise Standard integration.
displayExitButton	false	Boolean	false - Disables the exit icon on the modal true - Enables the exit icon on the modal	Will display an X icon in the corner of the modal window to allow for end users to close the authentication modal without completing it. Clicking the close button will result in the `payments.validated` event to be triggered with a `10011`error, `Canceled by user`

ApplePay

APPLE PAY

Configure the Apple Pay payment brand if being used. If Apple Pay is not being used, this configuration option is ignored.

Configuration object with just Apple Pay

{
  applePay: {
	button: {
		containerId: 'MySpecificApplePayId',
		color: 'black'
	}
  }
}

Field	Type	Description
button	object

button

Configuration options for the Apple Pay payment button

Field

Type

Default

Description

containerId

string

The HTML Id value of the container to inject the Apple Pay payment button into. Using this value you can override any generic configurations for button placement.

color

string

white

The color that the Apple Pay button should be rendered in.

Possible Values:

white
white-bordered
black

PayPal

PAYPAL EXPRESS CHECKOUT V.ZERO

Field	Type	Default	Payment Brand Support	Description
button	object
flow	string	checkout	V.ZERO	Set to 'checkout' for one-time payment flow, or 'vault' for Vault flow. If 'vault' is used with a client token generated with a customer id, the PayPal account will be added to that customer as a saved payment method. Possible Values: checkout vault
intent	string	authorize	V.ZERO	Checkout flows only. This will setup the transaction to allow or limit the amount of authorization and captures that can ben sent to paypal per order. Possible Values: authorize - Create an order in an authorized state. This will allow you to do a single authorize and capture. This option is not recommended if split shipment is a possibility. sale - Authorize and capture the funds immediately. This is ideal for digital goods that do not require shipment. order - Create a generic order container. This allows you to do multiple authorization and captures against a single order. Preferred method if split shipments is a possibility.
offerCredit	boolean	false	V.ZERO	Offers the customer PayPal Credit if they qualify. Checkout flows only.
enableShippingAddress	boolean	true	V.ZERO	Returns a shipping address object
shippingAddressEditable	boolean	true	V.ZERO	Set to false to disable user editing of the shipping address.
useraction	string		V.ZERO	This option only applies to the "checkout" flow and will have no effect on the "vault" flow. Changes the call-to-action in the PayPal flow. By default the final button will show the localized word for "Continue" and implies that the final amount billed is not yet known. Setting this option to commit changes the button text to "Pay Now" and page text will convey to the user that billing will take place immediately.
displayName	string		V.ZERO	The merchant name displayed inside of the PayPal lightbox; defaults to the company name on your Braintree account
locale	string	en_US	V.ZERO	Use this option to change the language, links, and terminology used in the PayPal flow. This locale will be used unless the buyer has set a preferred locale for their account. If an unsupported locale is supplied, a fallback locale (determined by buyer preference or browser data) will be used and no error will be thrown. For more info on this field please review the braintree docs.
billingAgreementDescription	string		V.ZERO	Use this option to set the description of the preapproved payment agreement visible to customers in their PayPal profile during Vault flows. Max 255 characters.

button

Field	Type	Default	Description
color	string	blue	Possible Values: gold silver blue
shape	string	pill	Possible Values: pill rect
size	string	26px	Possible Values: 26px 34px 44px 60px
style	string	paypal	Possible Values: paypal paypalcheckout

Visa Checkout

VISA CHECKOUT

Field	Type	Default	Description
button	object

button

Field	Type	Default	Description
color	string	standard	Possible Values: standard neutral
locale	string		The locale, which controls how text displays in a Visa Checkout button and the Visa Checkout lightbox. Refer to Visa Checkout documentation button generation for a list of supported locales.
height	string		Height of the button, in pixels, for custom button sizes. You must specify the height if you specify a value for width. The value you choose determines the range of allowable values for `width`. Possible Values: 34 47 94
width	string		Width of the button, in pixels, for custom button sizes. You must specify the width if you specify a value for height. Format: It is one of the following values: less than 477 if height is 34; default value is 154 greater than 212 and less than 659 if height is 47; default value is 213 greater than 424 and less than 1317 if height is 94; default value is 425 The default value is used if the value for width is invalid for the specified height.
size	string		Width of button in pixels. You can either specify size to display a standard predefined sized button, or you can specify the height and width to create a custom size. If you do not specify both height and width, the button will default to 213px. If height and width are specified, this configuration is ignored. Possible Values: 154 213 425