Custom forms and JS Lib

Dynamic Forms

Dynamic Forms are the simplest and most common way to support every payment method in a single integration. Dynamic Forms that collect payment data are created by Switch’s client-side JS library and included inside the checkout page without overlays or redirections, to improve UX and conversion. These forms can be styled using CSS to match the website look-and-feel. Because payment data is never available to the merchant this is also the safest integration.

Complete Integration Example

<div>Merchant Module</div>
<div id='merchant-form' style='max-width: 500px; margin: auto'>
<div style='height:200px'>Other Form Items</div>
<div id="dynamic-forms-container"></div>
<button id="custom-submit-btn">Merchant custom submit button</button>
<script src="switch.js"></script>
let styles = {
primaryButton: {'display': 'none'},
secondaryButton: {'display': 'none'},
header: {'display': 'none'},
radio: {'display': 'none'},
list: {'border-width': 0},
formHeader: {'display': 'none'},
formField: {'margin': '10px 0 10px 0'},
label: {
'font-size': '12px',
'font-family': 'sans-serif',
'margin': '0 0 5px 0'
input: {
'color': '#777',
'height': '45px',
'background-color': '#eee',
'border-width': '0',
'padding': '10px 15px',
'font-family': 'sans-serif'
let switchJs = new SwitchJs(SwitchJs.environments['SANDBOX'], 'MERCHANT_PUBLIC_KEY');
let formOptions = {
chargeTypes: ['card'],
selectedChargeType: 'card', // choose a specific method
language: 'en',
resetStyles: true, // remove default styles to make it easier to restyle
style: styles, // restyle form
let formContainer = document.getElementById('dynamic-forms-container');
let dynamicForms = switchJs.dynamicForms(formContainer, formOptions);
document.getElementById('custom-submit-btn').addEventListener('click', ()=>{
// When the customer submits the form,
// call your API method that will create the charge
// when your API returns a charge object,
// create instrument using the charge id
.then((charge) => dynamicForms.createInstrument(
// Instrument created successfully
.then((instrument) => {
if (instrument.destinationReference) {
// Display reference
alert("Please push funds to " + destinationReference);
} else {
// Synchronous

Form options

Below you can find a complete list of all the options that Dynamic Forms may receive.

let formOptions = {
merchantTransactionId: '12345',
chargesUrl: '',
chargeTypes: ['card_onetime', 'multibanco'],
selectedChargeType: 'card_onetime',
style: style,
resetStyles: true,
iframe: true,
autoRedirect: true,
showReference: true,
language: 'en'
Request ParameterTypeDescription
merchantTransactionIdStringUnique identifier to the transaction
chargesUrlStringThe URL to your endpoint, where you create the charge
chargeTypesArrayCharge types to be shown to the user
selectedChargeTypeStringCharge type selected by default
styleJSON ObjectThe styles for the dynamic forms
resetStylesBooleanRemove default styles (default: false)
iframeBooleanAdd the dynamicForms inside one iframe (default: true)
autoRedirectBooleanAuto redirect the user if needed (default: true)
showReferenceBooleanShow reference if needed (default: false)
languageStringThe dynamic forms language

Form Styling

Available styling for the Dynamic Forms

let styles = {
/** Payment Method List **/
listItem: ['color', 'background-color', 'font-family', 'font-size', 'margin', 'padding', 'border-width', 'border-color', 'border-style', 'border-radius'],
listItemHighlight: ['color', 'background-color', 'font-family', 'border-color', 'border-style', 'border-radius'],
listRadioButton: ['color', 'display'],
list: ['border-width', 'border-color', 'border-radius', 'border-style'],
listHeader: ['background-color', 'color', 'display', 'font-family', 'font-size', 'margin', 'padding', 'border-width', 'border-color', 'border-style', 'border-radius'],
/** Instrument Details Form **/
formHeader: ['display', 'margin'],
formItem: ['margin-top', 'margin-bottom'],
inputLabel: ['background-color', 'color', 'display', 'font-family', 'font-size', 'margin', 'padding', 'text-transform', 'border-width', 'border-color', 'border-style', 'border-radius'],
input: ['background-color', 'border-color', 'border-width', 'border-radius', 'border-style', 'color', 'font-family', 'font-size', 'height', 'margin', 'padding'],
inputError: ['border-color', 'border-width', 'border-radius', 'border-style', 'color', 'font-family', 'padding'],
inputErrorMessage: ['background-color', 'color', 'display', 'font-family', 'font-size', 'padding', 'margin'],
inputCardLogo: ['display', 'margin-right'],
inputHelper: ['background-color', 'color', 'display', 'font-family', 'font-size', 'padding'],
inputPlaceholder: ['color', 'display'],
formDescription: ['background-color', 'color', 'display', 'font-family', 'font-size'],
primaryButton: ['background-color', 'border', 'border-radius', 'color', 'display', 'font-family', 'font-size', 'padding'],
secondaryButton: ['background-color', 'border', 'border-radius', 'color', 'display', 'font-family', 'font-size', 'padding'],
spinner: ['display'],

Dynamic Forms Events

Available events to listen from the Dynamic Forms

Every time something happens inside the dynamic forms, you can listen to it. To do that you only have to specify a callback method for each event type you want to listen to.


let dynamicForms = switchJs.dynamicForms(formContainer, formOptions);
dynamicForms.on('instrument-success', (data) => {
Available events types
forms-loadedThe forms were loaded
form-data-changedData in the form has changed
form-data-errorThe data in the form that was submitted has errors
charge-types-loadedThe charge types were loaded
charge-type-selectedA charge type has been selected
charge-type-canceledThe charge type previously selected was canceled
submitThe form was submitted
instrument-successThe instrument has been created successfully
instrument-errorThe instrument has errors

Next Steps

Understand how your transactions are processed. Explore our Processing API for further details on Charges, Instruments, Payments, Refunds and Events.