Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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.

Note
titleNot intended for production

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


Code Block
languagejs
titleAll Options Example
linenumberstrue
{
    timeout: 6000,
	extendedtimeoutextendedTimeout: 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: ''
        }
    }
}


Table of Contents

Root Level Configuration

FieldTypeDefaultDescription
timeout
int6000The 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
int1How many times a request should be retried before giving up as a failure.
loggingobject

buttonobject

payment
object

applePay
object

paypalobject

visaCheckout
object

Logging

Settings for Songbird to log to the browser console

FieldTypeDefaultDescription
levelstringoff

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.

FieldTypeDefaultDescription
containerIdstringCardinal-PaymentsThe HTML Id value of the container to inject all payment buttons into.

Payment

Status
colourGreen
titlecca

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

FieldTypeDefaultDescription
viewstringmodal

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.

frameworkstringcardinal

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.

Note

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).


displayLoadingbooleanfalse

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.

Info

This feature is currently applicable to Cardinal Cruise Standard integration.



displayExitButton
falseBoolean
  • 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 10011error, Canceled by user

ApplePay

Status
colourGreen
titleapple pay

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

Code Block
languagejs
titleConfiguration object with just Apple Pay
linenumberstrue
{
  applePay: {
	button: {
		containerId: 'MySpecificApplePayId',
		color: 'black'
	}
  }
}


FieldTypeDescription
buttonobject

button

Configuration options for the Apple Pay payment button

FieldTypeDefaultDescription
containerIdstring
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.
colorstringwhite

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

Possible Values:

  • white
  • white-bordered
  • black

PayPal

Status
colourGreen
titlePayPal Express Checkout
 
Status
colourGreen
titleV.Zero

FieldTypeDefaultPayment Brand SupportDescription
buttonobject


flowstringcheckout

Status
colourGreen
titleV.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
intentstringauthorize

Status
colourGreen
titleV.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.
offerCreditbooleanfalse

Status
colourGreen
titleV.Zero

Offers the customer PayPal Credit if they qualify. Checkout flows only.
enableShippingAddressbooleantrue

Status
colourGreen
titleV.Zero

Returns a shipping address object
shippingAddressEditablebooleantrue

Status
colourGreen
titleV.Zero

Set to false to disable user editing of the shipping address.
useractionstring

Status
colourGreen
titleV.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.
displayNamestring

Status
colourGreen
titleV.Zero

The merchant name displayed inside of the PayPal lightbox; defaults to the company name on your Braintree account
localestringen_US

Status
colourGreen
titleV.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.

billingAgreementDescriptionstring

Status
colourGreen
titleV.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

FieldTypeDefaultDescription
colorstringblue

Possible Values:

  • gold
  • silver
  • blue
shapestringpill

Possible Values:

  • pill
  • rect
sizestring26px

Possible Values:

  • 26px
  • 34px
  • 44px
  • 60px
stylestringpaypal

Possible Values:

  • paypal
  • paypalcheckout


Visa Checkout

Status
colourGreen
titlevisa checkout

FieldTypeDefaultDescription
buttonobject

button

FieldTypeDefaultDescription
colorstringstandard

Possible Values:

  • standard
  • neutral
localestring

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.

heightstring

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
widthstring

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.

sizestring

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