Implementation

Secure Form is a ready-to-go payment form prepared by PayLane. If you don’t want to integrate via our REST API, Secure Form is the choice for you.

You just have to redirect your customer to our page with the form, where they’ll perform a payment and will be redirected back to your website.

Get your access data

Simply log into the Merchant Panel, click account, Secure Form customization and Options. You will find your merchant_id and hash salt there. That’s the data you will need to properly redirect your customers to PayLane with a POST request.

Simple redirect example

The simplest case would involve an HTML form with specific information that would be sent via a POST request. There’s no need to require any the data from your customers, so all the fields will be hidden in most cases.
Here’s how it can look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
<form action="https://secure.paylane.com/order/cart.html" method="post">
    <input type="hidden" name="amount" value="19.99" />
    <input type="hidden" name="currency" value="EUR" />
    <input type="hidden" name="merchant_id" value="john_test" />
    <input type="hidden" name="description" value="TR001" />
    <input type="hidden" name="transaction_description" value="Product 1 transaction" />
    <input type="hidden" name="transaction_type" value="S" />
    <input type="hidden" name="back_url" value="http://johns-shop.com/purchased" />
    <input type="hidden" name="language" value="en" />
    <input type="hidden" name="hash" value="6926ed14d1ae4d8eb2350d3c15e6a420e3bb7052" />

    <button type="submit">Pay with PayLane</button>
</form>

Calculating the hash

The hash value is calculated using the following formula:

1
2
hash = SHA1(salt + "|" + description + "|" + amount + "|"
       + currency + "|" + transaction_type)
Example:
1
2
hash = SHA1("MySalt|TR001|19.99|EUR|S")
     = "6926ed14d1ae4d8eb2350d3c15e6a420e3bb7052"

You can set the salt value in the Merchant Panel.

You should never send salt or calculate the hash on the client’s side. This should always be done using a server-side script.

Request values

Below you can find the full list of parameters that may (or have to) be send with a Secure Form POST request.

POST field name Required Format Description
merchant_id Yes string (32) Your Merchant ID that gives you access to PayLane’s Secure Form. You can find your Merchant ID in the Merchant Panel (account => secure form customization => options).
description Yes string(2-20) Only letters and numbers are allowed. Transaction identifier that will be passed to PayLane systems. This will be later visible as the transaction’s description in PayLane’s Merchant Panel. Only alphanumeric chars are allowed.
transaction_description Yes string(10000) Basic HTML tags allowed. Description of the product/service/transaction.
This description will appear on the payment form.
amount Yes decimal(12,2) Use dot (.) as decimal separator. Total amount to be charged.
currency Yes string(3) ISO 4217 currency code; the specified amount will be charged in this currency (for example “EUR” or “GBP”).
transaction_type Yes string(1) Transaction type; there are two valid values:
  • S – sale,
  • A – authorization only.
In case of card payments, choose the preferred value; with other payment methods choose S.
back_url Yes string(500) Website address where a customer will be redirected after performing the payment, for example http://myeshop.com/purchased.
hash Yes string(40) Security hash.
language No string(2) ISO 639 language code. Currently Secure Form can be presented in the following languages:
  • en – English,
  • pl – Polish,
  • de – German,
  • es – Spanish,
  • fr – French,
  • nl – Dutch.
customer_name No string(50) Customer full name.
customer_email No string(80) Customer email address.
customer_address No string(46) Customer address.
customer_zip No string(9) Customer ZIP code (if applicable).
customer_city No string(40) Customer city
customer_state No string(40) Customer state/province (if applicable).
customer_country No string(2) Customer country in ISO 3166 code, for example US or GB.

Response

When a customer pays (submits the Secure Form), they’re redirected back to your website (the URL specified in the back_url parameter). A set of parameters is passed in response (using POST or GET – its your choice).

POST field name Data type Description
status string Sale status:
  • PENDING – sale is waiting to be performed (in progress or not completed);
  • PERFORMED – sale has been successfully performed;
  • CLEARED – sale has been cleared (confirmation from a bank was received);
  • ERROR – sale unsuccessful.
description string(20) Transaction identifier – it is the same value you sent in the request.
amount decimal(12,2) Transaction amount.
currency string(3) Transaction currency code – ISO 4217 standard. For example USD, GBP, EUR.
hash string(40) Security hash.
id_authorization integer(10) Sale authorization ID number in PayLane system. Empty, if:
  • the transaction type was S (sale),
  • request failed.
id_sale integer(10) Sale ID number in PayLane system. Empty, if:
  • the transaction type was A (authorization),
  • request failed.
id_error integer(10) Error ID number in PayLane system. Empty if no error occurred.
error_code integer(3) Numeric error code.
error_text string(500) Short error description.
fraud_score decimal(4,2) Fraud check result. 0.00 – low risk, 10.00 – high risk.
Empty if fraud check was not performed.
avs_result string(2) Result of AVS check. Empty if AVS check was not performed.

Calculating the response hash

PayLane uses the same salt value to generate another hash sent in response. It is calculated using the following formula:

1
2
hash = SHA1(salt + "|" + status + "|" + description + "|"
       + amount + "|" + currency + "|" + id)
The id value is either id_sale or id_authorization – depending on the response. If you receive an error, the id should be an empty string.

This way you only have to compare the received hash with the one calculated by you to learn whether the response was sent securely.