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”, “logos”, 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 |
| disableCardExpiryDateValidation | Determines whether the card expiry date field should be validated. By default it is validated (false). | disableCardExpiryDateValidation: true |
| enableSAQACompliance | Use to make the credit card form SAQA compliant. Enabling this will render the card holder and expiry date fields in separate iFrames. By default it is false | enableSAQACompliance: 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. Important: This only works for card payment brands. The target should not be the same as the page frame name, otherwise the redirect will not work. | 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. Important: This only works for card payment brands. The target should not be the same as the page frame name, otherwise the redirect will not work. | paymentTarget: ‘myCustomIframe’, shopperResultTarget: ‘myCustomIframe’ |
| inlineFlow | Indicates the alternative payment brand which should get rendered inline. No browser redirect will happen, all information which are required to process the transaction will be collected by an inline integration. The consumer will not leave the context of the merchant checkout page. | inlineFlow: [‘KLARNA_PAYMENTS_PAYNOW’, ‘KLARNA_PAYMENTS_PAYLATER’, ‘KLARNA_PAYMENTS_SLICEIT’] |
| disableSubmitOnEnter | Disables the submit of payment form when Enter key is pressed. By default it is false | disableSubmitOnEnter: true |
| 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 |
| brandDetectionPriority | Must be used together with brandDetection:true. This list changes the default priority of brand detection. It can be useful in case of two brands that share the same BINs. If a brand is omitted in the list, it will take the default priority. | brandDetectionPriority: [“ALIA”, “IK_PRIVATE_LABEL”, “MAESTRO”, “VISA”] |
| brandDetectionType | Available options are: “regex” and “binlist”. By default, regular expressions (“regex”) are used for the brand detection. The option “binlist” instructs COPYandPAY to search for brands from its internal BIN database. Usually, “binlist” produces better results than “regex” | brandDetectionType: “binlist” |
| overridePaymentType | If one of the brands, or more, included in the form needs a paymentType different than the one defined in the checkout creation, use overridePaymentType[BRAND_NAME]=PAYMENT_TYPE to override the default type for this brand. You can override it to as many brands as you need. | overridePaymentType[BOLETO]=PA |
| 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.This option has no effect when enableSAQACompliance is enabled. | 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 */} |
| onDetectBrand | Triggered every time a brand is detected and provides a list of possible brands. | onDetectBrand: function(brands){ /*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 */} |
| onBlurCardHolder | Triggers on leaving the card holderfield. Context (this) is the iframe communication object. Only available when enableSAQACompliance is true. | onBlurCardHolder: function(isValid){ /* function here */} |
| onBlurExpiryDate | Triggers on leaving the expiry date field. Context (this) is the iframe communication object. Only available when enableSAQACompliance is true. | onBlurExpiryDate: function(isValid){ /* function here */} |
| onLightboxCancel | Callback when the shopper cancels the transaction in the lightbox. | onLightboxCancel: function(){ /* function here */} |
| executePayment | Calling executePayment(/*class name of the form container*/) triggers the payment form submission for a defined payment container. | wpwl.executePayment(“wpwl-container-card”) |
| 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. | onLoadThreeDIframe: 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:
|
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} |
| styling.layout | Sets a layout of Paypal Smart Payment Buttons during a Paypal checkout when multiple buttons are available. Default is “vertical”. Supported options are: “vertical”, “horizontal”. | styling: {layout: “vertical”} |
| styling.color | Sets a color of Paypal Smart Payment Buttons during a Paypal checkout. Default is “gold”. Supported options are: “gold”, “blue”, “silver”, “white”, “black”. | styling: {color: “gold”} |
| styling.shape | Sets a shape of Paypal Smart Payment Buttons during a Paypal checkout. Default is “rect”. Supported options are: “rect”, “pill”. | styling: {shape: “rect”} |
| styling.height | Sets a height of Paypal Smart Payment Buttons during a Paypal checkout. To customize button width alter width of the container element. Supported values are from 25 to 55. | styling: {height: 25} |
| styling.label | Sets a label of Paypal Smart Payment Buttons during a Paypal checkout. Default is “paypal”. Supported options are: “paypal”, “checkout”, “buynow”, “pay”. | styling: {label: “paypal”} |
| styling.tagline | Displays a tagline of Paypal Smart Payment Buttons during a Paypal checkout. Default is true. Supported options are: true, false |
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 |
Payment containers
| Key | Description | Example |
|---|---|---|
| wpwl-container-card | All card payment options are provided within that container. | – |
| wpwl-container-directDebit | All direct debit options are provided within that container. | – |
| wpwl-container-prepayment-{brand_name} | The specific prepayment option is provided within that container. | wpwl-container-prepayment-BITCOIN |
| wpwl-container-onlineTransfer-{brand_name} | The specific online transfer option is provided within that container. | wpwl-container-prepayment-GIROPAY |
| wpwl-container-virtualAccount{brand_name} | The specific virtual account payment option is provided within that container. | wpwl-container-virtualAccount-PAYPAL |