Widget Web SDK

Benefits of payabl. web SDK

Implementing the Web SDK solution

  1. Send initialization request (get_payment_widget_session).

  2. Capture the “session_id” from the “get_payment_widget_session” request’s post response.

  3. Use “session_id” in the initialize method of JavaScript Payabl object.

  4. Follow the steps to integrate the Widget web sdk.

Detailed flow description

  • In the server to server (get_payment_widget_session) payment request, the payment gateway should receive from the merchant’s server all required and optional parameters (payment data and customer’s data) for payment processing.
  • The payment gateway sends the merchant the response that includes the initial URL (session_id parameter) for using with the web SDK JavaScript. This is possible ONLY if merchant’s server received a successful response from the payment gateway after “get_payment_widget_session” payment request.
  • Once in the web SDK has been successfully created, the customer will be presented with a credit card input field.
  • Only after the fields are completely and correctly filled the customer would be able to continue to submit the payment.
  • If there is a need for the customer to authenticate through 3DSecure, the web SDK will handle that.
  • Once the transaction is completed, the web SDK will post the result of the transaction to a JavaScript callback provided by the merchant.
  • The merchant will use this message to display a success or failed message to the customer and do the necessary take control of the page.
  • The merchant should not use the result of the callback notification to update its system. Instead, there will be a notification sent to the “notification_url” provided in the server to server request.


The POST request should contain the following mandatory components:

  • Payment Data
  • Customer Data


  • Initial response to get a session token

Payment Data

Field NameTypeLengthFormatMandatory?Description
merchantid alphanumeric*40 charactersmerchant identification
orderid alphanumeric*max. 30 char.orderid in the merchant shop system
amount float
transaction amount
currency char3ISO 4217 i.e. “EUR” or “USD”ISO 4217
signature hex40 charactersSHA-1 hash value (hexadecimal)Signature Calculation
shop_url char254http:// the web sdk to communicate through the browser.
notification_url char255https enabled urlThis parameter can be used to override the account notification url setup on our system
recurring_id alphanumeric*max. 10 char.Classify the first of recurring transactions with INIT
Following recurring transactions need the transaction ID of the initial transaction
language char2ISO-639-1 alpha 2The language in which the error messages will be displayed.
external_id alphanumeric*255Merchant unique id

Customer Data

Field NameTypeLengthFormatMandatory?Description
salutation alphanumeric*max. 10 char.Mr., Mrs.salutation
title alphanumeric*max. 20 char.Dr., Prof.title
gender char1M – male
F – female
firstname alphanumeric*max. 30 char.first name
lastname alphanumeric*max. 30 char.last name
birthday numeric8 digitsddmmyyyybirthday
street alphanumeric*max. 100 char.street
house alphanumeric*max. 10 char.house number
postbox alphanumeric*max. 20 char.post office box
zip alphanumeric*max. 10 char.*postal code (USA and Canada only)
city alphanumeric*max. 40 char.*city
state alphanumeric*max. 30 char.*state/province (USA and Canada only)
country char3country (ISO 3166 alpha3)*ISO 3166: country
email RFC 822max. 50 char.e-mail address
phone numericmax. 20 char.(blank, +, -, (, ))phone number
fax numericmax. 20 char.(blank, +, -, (, ))fax number
mobile numericmax. 20 char.(blank, +, -, (, ))mobile number
company alphanumeric*max. 40 char.company
customerid alphanumeric*max. 20 char.internal customer id in the merchant’s shop system
customerip alphanumeric*max. 39 char.customer IP
custom1 alphanumeric*max. 255 char.custom field for merchant
custom2 alphanumeric*max. 255 char.custom field for merchant
custom3 alphanumeric*max. 255 char.custom field for merchant
  • These fields are recommended to be sent as they maybe needed in case of chargeback disputes


Initial response parameters.

Field NameTypeLengthFormatMandatory?Description
errorcodealphanumericStatus of request
session_idalphanumeric40 characters
signaturealphanumeric40 characters

Final response parameters.

Field NameTypeLengthFormatMandatory?Description
errorcodenumericStatus of final payment request
securityalphanumeric64 characterssee security calculation: checksum for validation of request
orderidorderid in the merchant shop system
typecharpreauthorize, capturetype of the transaction, only on merchant notification

Our Technical Support team is there to help you:
Email: [email protected]
Available Monday – Friday between 09:00 and 17:00 CET/CEST