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
errorcode alphanumericStatus of request
errormessage alphanumeric
session_id alphanumeric40 characters
transactionid numeric
signature alphanumeric40 characters

Final response parameters.

Field NameTypeLengthFormatMandatory?Description
errorcode numericStatus of final payment request
errormessage alphanumeric
security alphanumeric64 characterssee security calculation: checksum for validation of request
transactionid numeric
orderid orderid in the merchant shop system
type charpreauthorize, 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