Skip to main content

Performing payments with the widget

If you do not have PCI DSS, use our payment form widget to perform payments.

Widget

Getting started

To start using our widget, do the following:

In test environment

<link href="https://widget-demo.smart-glocal.com/payment-form.css" rel="stylesheet" />
<script src="https://widget-demo.smart-glocal.com/payment-form.js" defer></script>

For real payments

<link href="https://widget.smart-glocal.com/payment-form.css" rel="stylesheet" />
<script src="https://widget.smart-glocal.com/payment-form.js" defer></script>

Add the widget container


<div id="smgl-payment-form"></div>

Once the script is linked to the page, the SmglPaymentForm class will appear in the global scope.

Now, you can make payments using our widget.

Making a payment using the widget

Below is an example of how to start any payment through the widget.

Complete the following steps:

  1. Create a new session every time a user clicks Pay. To do this, send a session/create request.

  2. Send a token request to create a token using the returned session identifier and specifying the widget name. As a result you will receive a public token.

    To create a widget with the I agree to recurring payments checkbox, pass true in the show_recurrent_checkbox parameter.

    Example
    curl -X POST \
    http://demo.smart-glocal.com/api/v1/token \
    -H 'Content-Type: application/json' \
    -H 'X-PARTNER-PROJECT: your_project_name' \
    -H 'X-PARTNER-SIGN: signature' \
    -d '{
    "acquiring_widget": {
    "session_id": "ps_34851",
    "show_recurrent_checkbox": "true",
    "locale":"en"
    }
    }'

    You can also pass the locale optional parameter to ensure the widget localization stays the same after the user is redirected by a provider for additional services (for example, 3D Secure). Currently, the following values are available: "locale":"en" and "locale":"ru". If this parameter is not passed, "locale":"en" is used.

  3. Use the returned public token to initialize the widget.

    Example

    const paymentForm = new SmglPaymentForm(publicToken);

  4. To display the payment form, call the render() method:

    Example

    paymentForm.render();

  5. Let the user interact with the widget through all the required steps.

  6. Complete the operation according to the type of payment you are making. You will either receive webhooks or, if the webhooks are deactivated, you will need to check the session status to understand your next step as well as the payment result.

    If, while using the widget, you receive an action_required webhook, send the HTTP 200 OK in response but do nothing, as the user will be redirected for 3D Secure within the widget.

Widget API

SmglPaymentForm

Payment form class constructor.


const paymentForm = new SmglPaymentForm(publicToken[, options])

ParameterMandatoryTypeDescription
publicToken+stringPublic token
options-objectAdditional settings object
  container-HTMLElementContainer into which the form will be inserted. Default value: <div id="smgl-payment-form"></div>
  isCvcMasked-boolSet this parameter to true to mask the CVV/CVC field value
  Redirect-ObjectRedirection details
    target-string3DS window open options*:
- _blank - in a new tab
- _self- in the same frame
- _parent - in the next level up of the frame if they are nested in one another
- _top - outside of all the frames as the top window
Default: _top
  texts-objectUI element parameters
    failedPaymentScreen-objectFailed payment screen
      title-stringFailed payment message. Default value: Error
    paymentForm-objectPayment form
      buttonPayLabel-stringPayment button name. Default value: Pay
      cardholderLabel-stringCardholder name text. Default value: Cardholder
      cardholderNote-stringCardholder name prompt text. Default value: none
      cardholderPlaceholder-stringCardholder name placeholder. Default value: Full name
      cardNumberLabel-stringCard number. Default value: Card number
      cardNumberNote-stringCard number prompt text. Default value: none
      cardNumberPlaceholder-stringCard number placeholder. Default value: 0000 0000 0000 0000
      cvvLabel-stringCVV/CVC number. Default value: CVC
      cvvNote-stringCVV/CVC number prompt text. Default value: none
      cvvPlaceholder-stringCVV/CVC number placeholder. Default value: CVC
      expireDateLabel-stringCard expiration date. Default value: Expiration date
      expireDateNote-stringCard expiration date prompt text. Default value: As stated on the card
      expireDatePlaceholder-stringCard expiration date placeholder. Default value: MM/YY
      recurrentLabel-stringRecurring payment checkbox. Default value: I agree to recurrent payments
      termsAgreement-stringTerms of agreement. The text within the mandatory {{#link}}{{/link}} tags is used as a link to the terms of agreement source. Default value: By pressing Pay, you accept the terms of our {{#link}}user agreement{{/link}}
    validationErrors-objectField validation error messages
      INVALID_CARD_NUMBER-stringInvalid card number. Default value: Invalid card number
      INVALID_CVV-stringInvalid CVV/CVC. Default value: CVV/CVC has 3 digits
      INVALID_EXPIRY_DATE-stringInvalid card expiration date. Default value: Invalid date
      IS_REQUIRED-stringRequired field value is missing. Default value: Required field
    paymentProcessScreen-objectPayment process page
      description-stringPayment processing page text. Default value: Just a moment
      title-stringPayment process screen heading. Default value: Payment processing...
    redirectionScreen-objectRedirecting page (3D Secure)
      followTheLink-stringInvitation message to proceed with redirection in case of automatic redirection failure. The text within the mandatory {{#link}}{{/link}} tags is used as a link. Default value: If you haven't been redirected automatically, use {{#link}}this link{{/link}}.
      title-stringPayment processing page header. Default value: Payment processing...
      waitForRedirectToBanksPage-stringAutomatic redirection warning, includes 3 seconds countdown timer. The {{countdown}} value is mandatory and will be replaced with the timer. Use the {{#strong}}{{/strong}} tags to emphasize the timer in bold. Default value: You will be redirected to the issuer bank's page in {{#strong}}{{countdown}}seconds.{{/strong}}\
    successPaymentScreen-objectSuccessful payment page
      title-stringSuccessful payment page header. Default value: Payment success
    transactionData-objectTransaction data
      amountLabel-stringTransaction amount label. Default value: Amount
      creditCardLabel-stringPayment type data (card type and masked card number) label. Default value: Card
      transactionIdLabel-stringTransaction ID label. Default value: Transaction ID
    unknownError-stringUnknown error message. Default value: Something went wrong...

* Note that:

  • We do not recommend using the _self option for security reasons.
  • If you use the _blank option, the user will need to allow pop-ups in the browser or follow the redirection link from the payment widget.

Method: paymentForm.render()

The method displays the form on the page in the container defined by the options.container parameter.

    paymentForm.render([options])
ParameterMandatoryTypeDescription
options-ObjectAdditional settings object
options.container-HTMLElementContainer into which the form will be inserted. Default value: <div id="smgl-payment-form"></div>

Event handlers

paymentForm.onReady

Handles the event of the form getting ready for work.

paymentForm.onReady = function () {
/* handler */
}

paymentForm.onPaymentStart

Handles the event occurring at the start of the payment process.

paymentForm.onPaymentStart = function () {
/* handler */
}

paymentForm.onPaymentSuccess

Handles the event occurring when the payment process finishes successfully.

paymentForm.onPaymentSuccess = function () {
/* handler */
}

paymentForm.onPaymentFail

Handles the event occurring when the payment process finishes unsuccessfully.

paymentForm.onPaymentFail = function (error) {
/* handler */
}

Customizing the widget appearance

You can link your own styles at the end of the default ones and override them.

<link href="https://widget.smart-glocal.com/payment-form.css" rel="stylesheet" />
<link href="custom-styles.css" rel="stylesheet" />

You cannot yet change the appearance of the values entered inside the iframe. This functionality will be added later.

Also, you can modify texts of the widget UI elements. Here are what you can change:

  • labels
  • placeholders
  • error messages
  • prompt texts
  • button names
  • footer texts

To do that, pass the Options object with UI element parameters within the SmglPaymentForm widget constructor.

Example of how to add a Spanish localization

Click here to expand

const paymentForm = new SmglPaymentForm('<public token>', {
isCvcMasked: true,

texts: {
failedPaymentScreen: {
title: 'Error',
},

paymentForm: {
buttonPayLabel: 'Pagar',

cardholderLabel: 'Titular de la tarjeta',
cardholderNote: '',
cardholderPlaceholder: 'Nombre completo',

cardNumberLabel: 'Número de tarjeta',
cardNumberNote: '',
cardNumberPlaceholder: '0000 0000 0000 0000',

cvvLabel: 'CVC',
cvvNote: '',
cvvPlaceholder: 'CVC',

expireDateLabel: 'Fecha de vencimiento',
expireDateNote: '',
expireDatePlaceholder: 'Como se indica en la tarjeta',

recurrentLabel: 'Autorizo pagos recurrentes',

termsAgreement:
'Al presionar Pagar, Ud. acepta los términos de nuestro {{#link}}acuerdo de usuario{{/link}}',

validationErrors: {
INVALID_CARD_NUMBER: 'Número de tarjeta inválido',
INVALID_CVV: 'CVV/CVC tiene 3 dígitos',
INVALID_EXPIRY_DATE: 'Fecha inválida',
IS_REQUIRED: 'Campo requerido',
},
},

paymentProcessScreen: {
tion: 'Espere un momento',
title: 'Procesando el pago...',
},

redirectionScreen: {
followTheLink:
'Si Ud. no es redirigido automáticamente, use {{#link}}este enlace{{/link}}.',
title: 'Procesando el pago...',
waitForRedirectToBanksPage:
'Será redirigido a la página web del banco emisor en {{#strong}}{{count}} segundos{{/strong}}.',
},

successPaymentScreen: {
title: 'Éxito',
},

transactionData: {
amountLabel: 'Cantidad',
creditCardLabel: 'Tarjeta',
transactionIdLabel: 'ID de transacción',
},

unknownError: 'Algo salió mal...',
},
});

End user errors

While interacting with our widget, end users may receive the errors stated below.

If you choose to translate the widget texts into other languages, for example, Spanish, note that for now end users will receive error descriptions still in English.

Error codeError description
3DS_errorTo complete the transaction successfully, 3DS authentication is required
activity_count_exceededThe activity/amount limit for the card is exceeded
bank_card_expiredThe bank card is past its expiration date
declined_by_issuer_bankThe operation was declined by the emitting bank
insufficient_fundsThe card does not have enough funds