Integration guide

Accept card payments with a Hosted Payments Page—a fast and easy way to collect your customer’s payment information, process the payment request, and handle authorization.

How it works

When your customer is ready to check out:

Send a Hosted Payment Page request and pass through all the payment information. like the amount, currency, country, and etc.
payabl. will use this information to send you the link to iFrame to which you will redirect your customer to make their payment.
Once your customer fills in the required payment details, we will process the payment and handle the authorization flow.
And after the payment has been successfully processed, you will receive a notification message.

Get started

Step 1. Send initial request

You need to send a init payment request from your server to payabl.

https://sandbox.payabl.com/pay/payment/init

In request, include:

merchantid: The merchant's identification number.
orderid: The field orderid is optional and exclusively for the merchant's convenience.
amount: The amount field contains the transaction’s total amount. This is the amount that will be transmitted to the autorizing system.
currency: The currency field contains the alphanumeric currency code for the transaction, according to ISO 4217, e.g. EUR, USD, AUD, CAD, NOK, SEK, CHF.
signature: The signature field contains a 40-figure hexadecimal value. This signature value is a checksum designed to protect the merchant account from unauthorized access.
url_return: The URL is used for redirecting the customer after the end of the transaction.
email: The customer's email address.
customerip: customer IP
notification_url : URL for receiving POST callbacks from payabl. side

Initial request example

merchantid=gateway_test&amount=543.00&currency=EUR&orderid=ORDER-00005&language=en&gender=M&
lastname=Mustermann&street=Bockenheimer+Landstr.&zip=60323&city=Frankfurt&country=DEU&
customerid=cust-123456&salutation=Herr&title=Dr.&firstname=Max&company=Siemens+AG&
birthday=01011970&house=123&postbox=&state=Hessen&[email protected]&
phone=069-777-77-0&fax=069-777-77-15&mobile=0179-777-77 77&custom1=max+255+chars&
custom2=max+255+chars&custom3=max+255+chars&signature=aa15f70f1fcce880fc532aa30a60973f3c30d5c3&
customerip=212.212.212.212&url_return=https%3A%2F%2Fwww.merchant-webshop.de%2Fpayment%2Fsuccess.php

payabl. will send you a response to your server with the following parameters:

errorcode: Error code of the initial transaction, returned by the payment gateway to the merchant's server. Equals 0 if a transaction was successful, or numeric_error_code in case an error occurred.
errormessage: Error message related to the error code.
sessionid: the session id for the customer.
transactionid: The field transactionid contains the transaction’s identification in the payment gateway. The transaction ID is generated within the payment gateway for a Preauthorize request or an Authorize request and is sent back to the merchant's system.
start_url: The URL for redirecting the customer to the payment page.

Response example

errorcode=0&errormessage=&sessionid=we3fg0wg43e8&transactionid=123456&start_url=http%3A%2F%2Fdev- netzpowercash21.local%3A14950%2Fpay%2Fc12432fadbe2436ea79f8a3de6cc2b1c06220c6b%2Fpayment%2Fstart%3Ftransactionid%3D6908099

Step 2. Redirect the customer

You should redirect the customer to start_url (payabl. payment page) after receiving response from our server. When the customer redirected, he will be presented with various pre-configured payment methods.

Our hosted payment page can be present to the customer as imbedded iframe inside you page, or can be presented as a popup.

Step 3. Submit a transaction

When the user selected payment method on the iFrame for the payment, he needs to provide payment details. Based on selected payment method, customer may indicated card details, IBAN and BIC, or wallet account credentials.

When all necessary data are provided, payment can be submitted by customer for processing to the payment gateway.
While using iFrame interface, the customer is always able to cancel the payment process, except after payment was confirmed. After clicking the “Cancel” button, the customer will be redirected to the merchant’s page with a payment transaction, and merchant will receive an internal notification message about this fact.

Step 4. Redirecting the customer to Return page and Receiving callback

The last step for a Hosted Payment Page, will be a redirection of the customer to url_return after the result of payment attempt is displayed to the customer:

payabl. will send HTML response which can be displayed on your Return URL

Response example (for decline):

orderid=Payabl-Test&transactionid=105226632&errorcode=-10001&errormessage=3DSecure+verification+failed+or+incomplete&3dProtocolVersion=2.2.0&
3dauthentication_flow=frictionless_flow&3dauthentication_status=R&3dcardholderInformation=Your+cart+requires+additional+verification+contact+your+bank&
3dtransactionStatusReason=12&3dtransactionStatusReasonMessage=Transaction+not+permitted+to+cardholder&type=order&
security=deface93c42747c7ab84e43de5353bfcd8eed4d6

📘
Additional 3DS error information on your Result page
You should include value form the field 3dcardholderInformation to your Return URL page in order to provide more details to your cardholder. This field shows a response directly from the issue on further authentication steps.
The field 3dcardholderInformation is present only in case an Issuer provides this info.

Callback to notification_url with the security parameter, which you will need to use in order to verify the authenticity of the notification. Signature Calculation.

Callback example: (for success)

errormessage=&type=capture&timestamp=1686139119&3dauthentication_status=Y&orderid=Payabl-Test&3dProtocolVersion=2.2.0&
transactionid=105226633&errorcode=0&3dauthentication_flow=challenge_flow&security=ff8cbf8212b71d918e37076d3452dcd0858f
c177def01fbf3565d8d8d19a7cb9

HTML response/Notification fields reference:

Parameter	Description
`transactionid`	payabl. internal transaction id. Please use this transaction id when referring to the transaction in communications with the payabl. team
`type`	Transaction type
`errorcode`	Transaction error code (0 for success)
`errormessage`	Brief explanation of transaction decline reason (empty on success)
`orderid`	Optional transaction identifier given by the merchant
`security`	Signature to verify the authenticity of the notification. You can find more information here
`timestamp`	Notification timestamp
`3dProtocolVersion`	3DS protocol version (will be `2.2.0` in most cases until further notice)
`3dauthentication_status`	3DS authentication status (possible values: `Y`, `A`, `N`, `U`, `R`)
`3dauthentication_flow`	3DS authentication flow (e.g. `frictionless_flow`)
`3dcardholderInformation`	Only added on declined transactions to provide additional explanations to the customer. Present if bank sends it.

You may find a full list of decline reasons in the annex.

📘
To repeat/retry the payment, the order must be submitted by the merchant again.

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