Parameters

Essential POST Request Parameters for Integrating payabl. Web SDK

Request Parameters

The POST request via Web SDK must contain the following mandatory components:

  • Payment Data
  • Customer Data

Payment Data

NameTypeLengthFormatMandatoryDescription
merchantidalphanumeric40 char.🚩Merchant Identification
amountfloat numeric8.2
8
12345678.90
12345678
🚩Transaction Amount
currencychar3ISO 4217 i.e. “EUR” or “USD”🚩ISO 4217 Standard Currency Code
shop_urlchar254https://127.0.0.1:5500 (use only this value for sandbox)🚩Allows the Web SDK to communicate through the browser.
signaturehex40 char.SHA-1 hash value (hexadecimal)🚩Calculated SHA-1 hash Signature
orderidalphanumericmax 30 char.Order ID in the Merchant Shop System
notification_urlchar255https enabled urlCan be used to override the account Notification URL setup on our system.
recurring_idalphanumericmax. 10 char.Classify the first of recurring transactions with INIT. Following recurring transactions need the transaction ID of the initial transaction
languagechar2ISO-639-1 alpha 2The language in which the error messages will be displayed.
external_idalphanumeric255Merchant Unique ID

Customer Data

NameTypeLengthFormatMandatoryDescription
emailRFC 822max. 50 char.🚩e-mail address
customeripalphanumericmax. 39 char.🚩customer IP
zipalphanumericmax. 10 char.*postal code (USA and Canada only)
cityalphanumericmax. 40 char.*city
statealphanumericmax. 30 char.*state/province (USA and Canada only)
countrychar3country (ISO 3166 alpha3)*ISO 3166: country
salutationalphanumericmax. 10 char.Mr., Mrs.salutation
titlealphanumericmax. 20 char.Dr., Prof.title
genderchar1M – male
F – female
gender
firstnamealphanumericmax. 30 char.first name
lastnamealphanumericmax. 30 char.last name
birthdaynumeric8 digitsddmmyyyybirthday
streetalphanumericmax. 100 char.street
housealphanumericmax. 10 char.house number
postboxalphanumericmax. 20 char.post office box
phonenumericmax. 20 char.(blank, +, -, (, ))phone number
faxnumericmax. 20 char.(blank, +, -, (, ))fax number
mobilenumericmax. 20 char.(blank, +, -, (, ))mobile number
companyalphanumericmax. 40 char.company
customeridalphanumericmax. 20 char.internal customer id in the merchant’s shop system
custom1alphanumericmax. 255 char.custom field for merchant
custom2alphanumericmax. 255 char.custom field for merchant
custom3alphanumericmax. 255 char.custom field for merchant

📘

Info

*These fields are recommended to be sent as they may be needed in case of chargeback disputes.


Response Parameters

Web SDK Responses

Initial Response Parameters

Data Fields:

Field NameTypeLengthMandatoryDescription
errorcodealphanumericxStatus of request
errormessagealphanumericx
session_idalphanumeric40 charactersx
transactionidnumeric
signaturealphanumeric40 charactersx

Here, the transactionid is a unique payabl. identifier assigned to each transaction processed through the payabl. Web SDK. It is used to track and reference specific transactions within the payabl. system.

In the initial response parameters, the transactionid is not mandatory as it si generated only after a successful payment transaction. The initial response primarily includes parameters necessary to set up the payment session, such as session_id, which is used to initialize the SDK payment form.

  • When We Get transactionid: you receive transactionid in the response after the payment process is completed successfully. The transactionid is included in the callback response to indicate that the transaction has been processed and recorded.
  • When We Don't Get transactionid: during initial setup and session creation phase, you do not receive a transactionid. At this stage, the focus is on generating a session_id to initialize the payment form. The transactionid is only provided after the actual payment transaction is attempted and processed.

Response Callback Notifications

  • Callback Notifications provide updates on transactions' outcome using a Notification URL. Notification URL can be provided in each request separately or can be set as a default value for your account.
  • payabl. sends Callback Notifications with statuses to Notification URL immediately after receiving a status from payment system.

Example:

{
   "status":"APPROVED",
   "metadata":{
      "errorcode":"0",
      "type":"capture",
      "errormessage":"",
      "orderid":"payabl-Test",
      "transactionid":"213548331"
   }
}

Statuses:

KeyValueDescription
statusAPPROVEDAction generated by payment gateway. *includes metadata
statusDECLINEDAction generated by payment gateway. *includes metadata
statusERRORAny action that occurs within the Web SDK module. *may not include metadata
statusCANCELLEDAction that occurs when customer cancelled the transaction. *may not include metadata

Metadata:

KeySub Key
metadataerrorcode
type
errormessage
ordered
transactionid

Final Response Parameters

  • Final Response Parameters are the detailed information returned by the payabl. API after a payment transaction
  • Received upon completion of the payment transaction

Data Fields:

Field NameTypeLengthMandatoryDescription
errorcodenumericxStatus of final payment request
errormessagealphanumericx
securityalphanumeric64 charactersxsee simplified signature for notifications checksum for validation of request
transactionidnumericx
orderidorderid in the merchant shop system
typechartype of the transaction, only on merchant notification

For the further inquiries, please contact payabl. Technical Support Team Email: [email protected] (available Monday to Friday from 09:00 to 17:00 CET/CEST)