Widget Web SDK
Benefits of payabl. web SDK
-
Feature is a SAQ-A compliant.
-
Handles full payment process with 3DSecure in one call.
-
Support for customization.
POST URL: https://sandbox.payabl.com/pay/payment/get_payment_widget_session
Implementing the Web SDK solution
-
Send initialization request (get_payment_widget_session).
-
Capture the “session_id” from the “get_payment_widget_session” request’s post response.
-
Use “session_id” in the initialize method of JavaScript Payabl object.
-
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.
REQUEST PARAMETERS
The POST request should contain the following mandatory components:
- Payment Data
- Customer Data
RESPONSE & SAMPLE CODES
- Initial response to get a session token
Payment Data
| Field Name | Type | Length | Format | Mandatory? | Description |
|---|---|---|---|---|---|
| merchantid | alphanumeric* | 40 characters | ✔ | merchant identification | |
| orderid | alphanumeric* | max. 30 char. | orderid in the merchant shop system | ||
| amount | float numeric | 8.2 8 | 12345678.90 12345678 | ✔ | transaction amount |
| currency | char | 3 | ISO 4217 i.e. “EUR” or “USD” | ✔ | ISO 4217 |
| signature | hex | 40 characters | SHA-1 hash value (hexadecimal) | ✔ | Signature Calculation |
| shop_url | char | 254 | https://shop.com | ✔ | Allows the web sdk to communicate through the browser. |
| notification_url | char | 255 | https enabled url | This 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 | 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
| Field Name | Type | Length | Format | Mandatory? | Description |
|---|---|---|---|---|---|
| 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 | ||
| 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 |
| RFC 822 | max. 50 char. | ✔ | e-mail address | ||
| 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 | ||
| 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
RESPONSE PARAMETERS
Initial response parameters.
| Field Name | Type | Length | Format | Mandatory? | Description |
|---|---|---|---|---|---|
| errorcode | alphanumeric | ✔ | Status of request | ||
| errormessage | alphanumeric | ✔ | |||
| session_id | alphanumeric | 40 characters | ✔ | ||
| transactionid | numeric | ||||
| signature | alphanumeric | 40 characters | ✔ |
Final response parameters.
| Field Name | Type | Length | Format | Mandatory? | Description |
|---|---|---|---|---|---|
| errorcode | numeric | ✔ | Status of final payment request | ||
| errormessage | alphanumeric | ✔ | |||
| security | alphanumeric | 64 characters | ✔ | see security calculation: checksum for validation of request | |
| transactionid | numeric | ✔ | |||
| orderid | orderid in the merchant shop system | ||||
| type | char | preauthorize, capture | type 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
Updated 2 months ago