DocumentationAPI Reference

Integration guide

Accept payments with a single implementation.

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:

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

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.

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 payabl. payment page after receive 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.
If the cards selected, when the customer needs to enter the following data:

  • Card number
  • CVV2
  • Expiry date
  • Name

Some payments methods like Sofort or Trustly requires IBAN and BIC, and PayPal 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 your page

The last step for a Hosted Payment Page, will be to redirect the customer back to your website after the result of payment attempt is displayed to the customer:

  • The transaction was processed successfully.
    In this case, the end-customer will see on the screen the notification about the successful result and will be redirected to the merchant’s website via the url_return.
  • The transaction failed.
    The error cannot be fixed by the customer (i.e. error from the bank “Authorisation declined” or error from payment gateway “card temporary blocked for 20. min”, etc.). In this case, the customer will be redirected to the merchant’s website by the url_return.
  • While in Hosted Payment Page for any reason if the cancel button is clicked then the customer will be redirected back to the merchant’s website via the url_return.

Step 5. Receive callback

After transaction is completed in a parallel with customer redirection you will receive a Callback from our server with transaction information and status to your Notification URL.

📘

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