COPYandPAY API

COPYandPAY API enables you to further customize your checkout workflows. Here you can find the reference for the wpwlOptions and you can see these in action on our workflow examples page.

Parameter

Description

Examples

locale

Sets the language/country of the payment forms. Expects ISO 639-1 for languages and ISO 3166-1 alpha-2 for countries. Default is "en-US".

Supported languages are: ar,be,bg,cn,cz,de,da,el,en,es,fi,fr,gr,hu,it,ja,ko,nl,no,pl,pt,ro,ru,sv,sk,sl,tr

Right-to-left languages are not supported by the number formatter. When using "ar", for example, set numberFormatting:false

locale: "de-AT"

locale: "de"

Check the requirements of the connector you are integrating in your shop. If the connector requires to have the language and the country provided, use the format "de-AT". If there is no requirement defined, you may use any of the two options.

style

Sets the style of the payment forms. You can choose from "card", and "plain" style. Default is "card"

style: "card"

autofocus

Sets focus to the selected input/select element on the payment page upon loading

autofocus : 'card.holder'

onReady

Triggers when all payment forms are ready

onReady: function() {/* function here */};

requireCvv

Determines whether the CVV field is presented on the payment form.

requireCvv: false

allowEmptyCvv

Determines whether the CVV field can be empty. By default it is false

allowEmptyCvv: true

useSummaryPage

If set to true, the payment is not completed, instead the form will initiate a callback to the onSaveTransactionData function, which can initiate a redirection to a summary page. This summary page can then be used to summarise the checkout before asking the user to confirm. An example can be seen on our advanced options page.

useSummaryPage: true

onSaveTransactionData

Triggered after the shopper presses Continue on the CnP form, when useSummaryPage flag is set to true. Parameter "data" is the serialized data of the payment form.

onSaveTransactionData: function(data){console.log(data);}

threeDIframeSize

Sets size of the 3D secure iframe. This iframe will only be used in case a shopper has to enter 3D secure credentials on the bank's page.

'threeDIframeSize':{'width':'100%', 'height':'580px'}

paymentTarget

We submit the form to this target. In case of additional shopper interaction, e.g. 3DSecure, we redirect the shopper within this target. This only works for card payment brands.

paymentTarget: 'my3dIframe'

shopperResultTarget

Works only in combination with "paymentTarget" option. By default, we redirect the shopper to the given "shopperResultUrl" using a self-submitting form with target="_top". If you use COPYandPAY in an iframe and want to redirect the shopper within this iframe, then the "shopperResultTarget" and the "paymentTarget" should be the name of this iframe.

paymentTarget: 'myCustomIframe', shopperResultTarget: 'myCustomIframe'

showTaxNumberField

If set to true the CPF field on the COPYandPAY form will be displayed. The CPF field is needed for payments processed in Brazil.

showTaxNumberField: true

showCVVHint

If set to true then the credit card form will display a hint on where the CVV is located when the mouse is hovering over the CVV field.

showCVVHint: true

brandDetection

If the COPYandPAY form contains more than one credit card brand (e.g. MASTER VISA AMEX) and this option is set to true(default is false) then COPYandPAY updates the brand field automatically based on the first four digits entered in the credit card number field.

brandDetection: true

displayBic

If the COPYandPAY form contains DIRECTDEBIT_SEPA brand and this option is set to true(default is false) then COPYandPAY will display the BIC field.

displayBic: true

forceCardHolderEqualsBillingName

By default the card.holder is displayed as one field in COPYandPAY's form. If this option is set to true then the form displays a field for the given name and a separate field for the surname. The values entered here will be submitted both as card.holder and as customer.givenName and customer.surname.

forceCardHolderEqualsBillingName: true

billingAddress

Option to display the billing address fields.

billingAddress: { country: "US", state: "NY", city: "New York", postcode: "12345", street1: "Suite 1234", street2: "Some Road" }

mandatoryBillingFields

Describe which billing fields cannot be empty. This option needs to be used with billingAddress option.

mandatoryBillingFields:{ country: true, state: true, city: true, postcode: true, street1: true, street2: false }

validation

Use validation. If false disables validation and the functions validate* and on*Submit* will not be called.

validation: true

validateCard

Triggers before onBeforeSubmitCard. Context (this) is the form. Overrides the internal validate card function.

validateCard: function(){ /* function here */}

validateDirectDebit

Triggers before onBeforeSubmitDirectDebit. Context (this) is the form. Overrides the internal validate direct debit function.

validateDirectDebit: function(){ /* function here */}

validateOnlineTransfer

Triggers before onBeforeSubmitOnlineTransfer. Context (this) is the form. Overrides the internal validate online transfer function.

validateOnlineTransfer: function(){ /* function here */}

validateVirtualAccount

Triggers before onBeforeSubmitVirtualAccount. Context (this) is the form. Overrides the internal validate virtual account function.

validateVirtualAccount: function(){ /* function here */}

onBlurSecurityCode

Triggers on leaving the card security code field. Context (this) is the iframe communication object.

onBlurSecurityCode: function(isValid){ /* function here */}

onBlurCardNumber

Triggers on leaving the card number field. Context (this) is the iframe communication object.

onBlurCardNumber: function(isValid){ /* function here */}

onLightboxCancel

Callback when the shopper cancels the transaction in the lightbox.

onLightboxCancel: function(){ /* function here */}

onBeforeSubmitCard

Triggers before card payment submission. Context (this) is the form. Overrides the internal submit function. Do event.preventDefault() or return false to cancel the payment submit action.

onBeforeSubmitCard: function(event){ /* function here */}

onBeforeSubmitDirectDebit

Triggers before direct debit payment submission. Context (this) is the form. Overrides the internal submit function. Do event.preventDefault() or return false to cancel the payment submit action.

onBeforeSubmitDirectDebit: function(event){ /* function here */}

onBeforeSubmitOnlineTransfer

Triggers before online transfer payment submission. Context (this) is the form. Overrides the internal submit function. Do event.preventDefault() or return false to cancel the payment submit action.

onBeforeSubmitOnlineTransfer: function(event){ /* function here */}

onBeforeSubmitVirtualAccount

Triggers before virtual account payment submission. Context (this) is the form. Overrides the internal submit function. Do event.preventDefault() or return false to cancel the payment submit action.

onBeforeSubmitVirtualAccount: function(event){ /* function here */}

onAfterSubmit

Triggers after the payment submission. Context (this) is the form.

onAfterSubmit: function(){ /* function here */}

onLoadThreeDIframe

Triggers when the 3D secure targetIframe has loaded, Context (this) is the iframe.

onLoadTarget: function(){ /* function here */}

spinner

Sets the style of the loading spinner. We use the spin.js library to display the spinner. The full list of settings can be found on internet if you search for spin.js.

spinner: { color: "red" }

sofortCountries

Sets available countries for SOFORT Uberweisung.

sofortCountries: { DE: "Deutschland", NL: "Nederland", AT: "Osterreich", BE: "Belgique", CH: "Schweiz", GB: "United Kingdom" }

onReadyIframeCommunication

Triggers when the communication between the PCI iframe and the payment form is established. Context (this) is the iframe communication object.

onReadyIframeCommunication: function(){ this.$iframe.height(200) }

onFocusIframeCommunication

Triggers when the shopper focuses the input element in the PCI iframe. Context (this) is the iframe communication object.

onFocusIframeCommunication: function(){ this.$iframe.height(200) }

onBlurIframeCommunication

Triggers when the shopper leaves the input element in the PCI iframe. Context (this) is the iframe communication object.

onBlurIframeCommunication: function(){ this.$iframe.height(200) }

showLabels

Shows or hides input labels. Default is true

showLabels: false

showPlaceholders

Shows or hides input showPlaceholders. Default is true

showPlaceholders: false

labels

Overrides labels from the list of available labels.

labels: {cardHolder: "Name on card", cvv: "Security code"}

errorMessages

Overrides error messages from the list of available error messages.

errorMessages: {cardHolderError: "Invalid name on card", cvvError: "Invalid security code"}

onError

Callback that triggers if an error occurs during checkout. The error.name should be read for details. Possible errors:

  • InvalidCheckoutIdError: Shopper waits for 30 minutes and pays then. The checkoutId is already expired. See error.message for details

  • PciIframeSubmitError: Error submitting card number or/and card cvv, e.g. the request run into a timeout. See error.message for details

  • PciIframeCommunicationError: Merchant page is not able to communicate with PCI iframes. See error.message for details

wpwlOptions.onError = function(error){ // check if shopper payed after 30 minutes aka checkoutid is invalid if (error.name === "InvalidCheckoutIdError") { //doSomething(); } // read the error message console.log(error.message); }

‚Äč

Brand-Specific Parameters

Some brands also use very specific parameters in order to provide an appropriate user experience during checkout. The COPYandPAY API also allows you to customize these brand-specific parameters. Here you can find the reference on brand-specific parameters for wpwlOptions.

Parameter

Description

Example

KLARNA_INVOICE.fee

Sets the fee to be used for the "Billing agreement" link during a Klarna Invoice checkout. Default is 0.

KLARNA_INVOICE = {fee: 3.8}

KLARNA_INSTALLMENTS.fee

Sets the fee to be used for the "Read more" link during a Klarna Installments checkout. Default is 0.

KLARNA_INSTALLMENTS = {fee: 3.8}

Labels

Key

Value

accountBank

Bank code

accountBankBic

BIC or bank code

accountBic

BIC

accountHolder

Account holder

accountId

Id

accountNumber

Account number

accountNumberIban

IBAN or account number

accountIban

IBAN

bankName

Name of bank

brand

Brand

cancel

Back

cardHolder

Card holder

cardNumber

Card Number

cvv

CVV

cvvHint

The 3 digits on the back of your card

cvvHintAmex

The 4 digits on the front of your card

cvvHintMaestro

The 3 digits on the back of your card if specified

country

Country

expiryDate

Expiry Date

taxNumber

Tax Identification Number

submit

Pay now

nextStep

Continue

billingAgreement

Invoice terms and conditions

emailOrAccountId

Email or Account Id

secureId

Secure Id

learnMore

Learn more

mmyy

MM / YY

customerMobile

Mobile phone number (+78000001774)

register

Register now

showOtherPaymentMethods

Show other payment methods

olpId

OLP ID

birthDate

Date of birth

Error Messages

Key

Value

accountBankError

Invalid bank code

accountBankBicError

Invalid BIC or bank code

accountBicError

Invalid BIC

accountHolderError

Invalid account holder

accountNumberError

Invalid account number

accountNumberIbanError

Invalid IBAN or account number

accountIbanError

Invalid IBAN

cardHolderError

Invalid card holder

surNameError

Invalid surname

givenNameError

Invalid given name

cardNumberError

Invalid card number or brand

cvvError

Invalid CVV

expiryMonthError

Invalid expiry date

expiryYearError

Invalid expiry date

taxNumberError

Invalid Tax Identification Number

generalTermsAndConditionsError

Please accept the consent for data transmission

billingCountryError

Invalid country

billingStateError

Invalid state

billingCityError

Invalid city

billingStreetError

Invalid street

billingPostCodeError

Invalid postcode