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
Name | Type | Length | Format | Mandatory | Description |
---|---|---|---|---|---|
merchantid | alphanumeric | 40 char. | 🚩 | Merchant Identification | |
amount | float numeric | 8.2 8 | 12345678.90 12345678 | 🚩 | Transaction Amount |
currency | char | 3 | ISO 4217 i.e. “EUR” or “USD” | 🚩 | ISO 4217 Standard Currency Code |
shop_url | char | 254 | https://127.0.0.1:5500 (use only this value for sandbox ) | 🚩 | Allows the Web SDK to communicate through the browser. |
signature | hex | 40 char. | SHA-1 hash value (hexadecimal) | 🚩 | Calculated SHA-1 hash Signature |
orderid | alphanumeric | max 30 char. | Order ID in the Merchant Shop System | ||
notification_url | char | 255 | https enabled url | 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 | char | 2 | ISO-639-1 alpha 2 | The language in which the error messages will be displayed. | |
external_id | alphanumeric | 255 | Merchant Unique ID |
Customer Data
Name | Type | Length | Format | Mandatory | Description |
---|---|---|---|---|---|
email | RFC 822 | max. 50 char. | 🚩 | e-mail address | |
customerip | alphanumeric | max. 39 char. | 🚩 | customer IP | |
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 | char | 3 | country (ISO 3166 alpha3) | * | ISO 3166: country |
salutation | alphanumeric | max. 10 char. | Mr., Mrs. | salutation | |
title | alphanumeric | max. 20 char. | Dr., Prof. | title | |
gender | char | 1 | M – male F – female | gender | |
firstname | alphanumeric | max. 30 char. | first name | ||
lastname | alphanumeric | max. 30 char. | last name | ||
birthday | numeric | 8 digits | ddmmyyyy | birthday | |
street | alphanumeric | max. 100 char. | street | ||
house | alphanumeric | max. 10 char. | house number | ||
postbox | alphanumeric | max. 20 char. | post office box | ||
phone | numeric | max. 20 char. | (blank, +, -, (, )) | phone number | |
fax | numeric | max. 20 char. | (blank, +, -, (, )) | fax number | |
mobile | numeric | max. 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 | ||
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 |
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
- Initial Response is a payabl. response to get a Web SDK
session_id
- Received as a response after a request Get a Unique Web SDK session_id has been sent.
Data Fields:
Field Name | Type | Length | Mandatory | Description |
---|---|---|---|---|
errorcode | alphanumeric | x | Status of request | |
errormessage | alphanumeric | x | ||
session_id | alphanumeric | 40 characters | x | |
transactionid | numeric | |||
signature | alphanumeric | 40 characters | x |
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 receivetransactionid
in the response after the payment process is completed successfully. Thetransactionid
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 atransactionid
. At this stage, the focus is on generating asession_id
to initialize the payment form. Thetransactionid
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:
Key | Value | Description |
---|---|---|
status | APPROVED | Action generated by payment gateway. *includes metadata |
status | DECLINED | Action generated by payment gateway. *includes metadata |
status | ERROR | Any action that occurs within the Web SDK module. *may not include metadata |
status | CANCELLED | Action that occurs when customer cancelled the transaction. *may not include metadata |
Metadata:
Key | Sub Key |
---|---|
metadata | errorcode |
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 Name | Type | Length | Mandatory | Description |
---|---|---|---|---|
errorcode | numeric | x | Status of final payment request | |
errormessage | alphanumeric | x | ||
security | alphanumeric | 64 characters | x | see simplified signature for notifications checksum for validation of request |
transactionid | numeric | x | ||
orderid | orderid in the merchant shop system | |||
type | char | type 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)
Updated 4 days ago