Integrating your website with Polskie ePłatności Online means taking one of two main ways that differ both in customers’ experience and implementation:

• Secure Form is a ready-to-go solution. All you need to do is to redirect the customer to a payment form in a proper manner. The form itself is prepared and hosted on PeP’s secure domain – you just need to send an appropriate request.

• API allows you to accept payments directly on your website – PeP stays invisible from the customer’s point of view. You can integrate with PHP, Python, Ruby or any other programming language. You’ll also be able to use some more advanced features.

Below we present the general and simplified request flow for payment processing. This gives the idea of the whole process, but please check also such flows for API and Secure Form to learn about the most significant differences.

1. A customer requests a checkout and initiates the payment.
2. The merchant sends the collected information to PeP and requests a payment to be processed.
3. Systems PeP Online communicate with appropriate institutions (depending on the payment method, e.g. banks, card associations, acquirers, issuers etc.) in order to process the payment.
4. After processing the payment, its status is returned to PeP systems.
5. Information about the payment is passed to the merchant’s website.
6. The customer is informed about the transaction status.

If you happen to use (or planning to) any eCommerce platforms or shopping carts, our plugins and extensions to those systems should interest you. They allow to connect such eCommerce applications with PeP systems. We also have a few business model descriptions that you may find useful or inspiring for your business. Take a look, especially if you’re creating your own product/service/solution.

For those of you who use popular e-commerce platforms or shopping cart systems, we offer a number of plugins and integrations. Thanks to this, implementing payments on your website will take just a few minutes.

To download the latest plugin please contact support@pep.com

Magento

PeP extension is available at Magento Connect (the installation takes about 2 minutes).

Pobierz plugin do Magento 1 | Pobierz plugin do Magento 2

Prestashop

To install the PeP plugin for PrestaShop, extract the downloaded file to a proper directory and configure it in the admin section.

Pobierz plugin do Prestashop

Wordpress

The PeP plugin for WordPress allows to place a payment button on a WordPress website.

Pobierz plugin do Wordpress

WooComerce

The PeP WooCommerce plugin allows to accept payments in online stores built with WooCommerce.

Pobierz plugin do WooComerce

WHMCS

Pobierz plugin do WHMCS

Shopify

Shoplo

Shoplo is an e-commerce platform that offers a tool for creating online stores. Additionally, it allows to sell goods via Facebook, mobile and online auction websites like eBay or Allegro. PeP payments become active after entering the Merchat ID and hash salt values in the Shoplo administration panel.

Comarch eSklep

Shoper

Ebexo

Integracja PeP Online z platformą eCommerce Ebexo jest dostępna z panelu administracyjnego sklepu Ebexo.

KQS

To oprogramowanie eCommerce mające jednorazową opłatę bez dodatkowych zobowiązań licencyjnych. Integracja z PeP Online jest dostępna z poziomu panelu admina sklepu, po pobraniu i wprowadzeniu najnowszej aktualizacji sklepu w dziale 'Formy płatności'.

Clickshop

Get our free whitepaper on REST architecture. Learn:

• what is REST,
• why you should use it,
• how to use RESTful APIs, and more, including practical examples!

Click the button below to download the free whitepaper and share the news with your friends.

Download & Share

Secure Form is a ready-to-go solution that allows quick and easy integration with PeP systems. You only have to redirect your customers to the payment form we give you. There’s also no need for you to pass any PCI scans or have an SSL certificate (though having one is always recommended), since the actual payment is submitted via our secure payment form (hence the name). From the customer’s point of view, making a purchase looks like this:

1. After choosing goods on the merchants website, a customer wishes to checkout and pay for selected products/services.
2. The customer is redirected to PeP's Secure Form, where they enter all information needed to process the payment.
3. After submitting the form, the customer is redirected back to the merchant’s website, where they learn about the payment/transaction status.

You just need to pass the needed transaction information (such as the product name, prices etc.) to our Secure Form using POST. After submitting the payment, the customer is redirected back to your website along with some response messages. It’s up to you whether the response will be sent using GET or POST. You can use the said response to inform your customer whether the transaction was successful.

So, to sum up, the whole process can be described in the following steps:

1. A customer, being on the merchants website, wishes to pay for the selected goods.
2. The website sends transaction information to PeP’s payment form and redirects the customer there.
3. After the form is filled and submitted, PeP processes the payment (sends the data to acquiring and issuing banks, card associations etc.) using the provided payment information.
4. The said institutions (they may vary depending on the payment method) respond to PeP, allowing to finish processing the payment.
5. PeP returns information about the payment status to the merchant’s website.
6. The merchant can use the received information to inform his customer whether the transaction was successful and what its status is.

Secure Form is a ready-to-go payment form prepared by PeP. 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.

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:

<form action="https://secure.pep.pl/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="pl">
    <input type="hidden" name="hash" value="6926ed14d1ae4d8eb2350d3c15e6a420e3bb7052" />
    <button type="submit">Pay with PeP</button>
</form>

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 PeP with a POST request.

The hash value is calculated using the following formula:

hash = SHA1(salt + "|" + description + "|" + amount + "|" + currency + "|" + transaction_type)

Example:

hash = SHA1("MySalt|TR001|19.99|EUR|S") = "6926ed14d1ae4d8eb2350d3c15e6a420e3bb7052"

You can set the salt value in the Merchant Panel.

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

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

Query structure

POST field name	Format	Required	Description
merchant_id	string (32)	Yes	Your Merchant ID that gives you access to PeP’s Secure Form. You can find your Merchant ID in the Merchant Panel (account => secure form customization => options).
description	string(1-255)	Yes	Only letters and numbers are allowed. Transaction identifier that will be passed to PeP systems. This will be later visible as the transaction’s description in PeP’s Merchant Panel.
transaction_description	string(2-10000)	Yes	Basic HTML tags allowed. Description of the product/service/transaction. This description will appear on the payment form.
amount	decimal(12,2)	Yes	Use dot (.) as decimal separator. Total amount to be charged.
currency	string(3)	Yes	ISO 4217 currency code; the specified amount will be charged in this currency (for example “EUR” or “GBP”).
transaction_type	string(1)	Yes	Transaction type; there are three valid values: S – sale, A – authorization only, T - tokenization (card tokenization without collecting customer funds). In case of card payments, choose the preferred value; with other payment methods choose S.
back_url	string(500)	Yes	Website address where a customer will be redirected after performing the payment, for example http://myeshop.com/purchased.
hash	string(64)	Yes	Security hash.
hash_type	string(8)	No	SHA256 for transaction_type=T
language	string(2)	No	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, it – Italian, cz – Chech, fi – Finnish, dk – Dannish, no – Norwegian, sk – Slovak, se – Swedish.
payment_methods	string	No	List of available payment methods ids, separated by a comma. The list of payment methods can be found here.
customer_id	string(12) - only numeric characters	yes - for transaction_type=T	Customer ID in the merchant system.
customer_name	string(50)	No	Customer full name.
customer_email	string(80)	No	Customer email address.
**customer_address **	string(46)	No	Customer address.
customer_zip	string(9)	No	Customer ZIP code (if applicable).
customer_city	string(40)	No	Customer city
customer_state	string(40)	No	Customer state/province (if applicable).
customer_country	string(2)	No	Customer country in ISO 3166 code, for example US or GB.

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	Format	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.
customer_id	string(12)	Customer_id parameter passed during tokenization when the transaction_type=T
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 PeP system. Empty, if: the transaction type was S (sale), T (tokenization) or request failed.
id_sale	integer(10)	Sale ID number in PeP system. Empty, if: the transaction type was A (authorization), T (tokenization) or request failed.
id_error	integer(10)	Error ID number in PeP 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.

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

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.

ID	Payment method
1	Visa Card
2	MasterCard
3	Maestro UK Card
4	American Express Card
5	Direct Debit in Germany (ELV)
6	Direct Debit in the Netherlands (ENL)
7	Direct Debit in Austria (EEV)
8	Solo Card
9	Maestro International Card
10	Diners
11	Discover Card
12	JCB Card
13	Direct Debit in France
14	Direct Debit in United Kingdom
15	Direct Debit in Belgium
16	Direct Debit in Switzerland
17	Direct Debit in Italy
18	Direct Debit in Spain
19	Direct Debit in USA
20	Direct Debit in Canada
21	Direct Debit in Australia
22	Direct Debit in Irland
23	PayPal
24	Sofortbanking
25	Inteligo
26	iPko
27	mTransfer
31	Alior Bank
32	Alior Sync
33	Millenium
35	WBK
36	Credit Agricole
37	Other
38	Poczta Polska
41	Getin Bank
42	ING Bank Śląski
44	Giropay
45	Pekao SA
46	Ideal
47	SEPA Direct Debit
48	Bank Pocztowy
50	BNP Paribas
52	Blik
53	Apple Pay
54	Citi Handlowy
55	Plus Bank
56	Noble Pay
57	Bank Spółdzielczy
58	Nest Bank
59	Podkarpacki Bank Spółdzielczy
60	SGB
61	Google Pay
62	Toyota Bank
63	BOŚ Bank
64	Visa Mobile

API is the best way to integrate with PeP if you want to have it completely your way. This also makes paying more comfortable to your customers, allowing them to reduce the whole purchase process even to a single click! You will have to meet some requirements (for example a SSL certificate), but you’ll also be able to create such payment solutions that will fit your needs and business character (see the business cases section for some examples). From the customer’s point of view, making a purchase looks like this:

1. After choosing goods on the merchants website, a customer wishes to checkout and pay for selected products/services.
2. The customer is shown a payment form on the merchant’s website.
3. After submitting the form, the customer is shown the payment/transaction status.

Since there’s no redirecting to other domains and the whole payment takes place on the same website, you can easily adjust all the look & feel, loading (for example using AJAX, if you prefer), messages etc. Besides, you can also implement many other payment models. Depending on the payment methods you use and your e-business characteristics, these may be paying with a single click, recurring payments, refunds and many more.

It’s mostly up to you. You know what you want to achieve, we just offer you the tools and our help. Check out the API Guide to learn how to use specific features in different programming languages, including PHP, Python and Ruby. You can also explore the REST function reference to learn about the available methods and use the API to its full potential.

So, to sum up, the whole process looks like this:

1. A customer, being on the merchants website, wishes to pay for the selected goods.
2. The website sends transaction information to PeP via our API, while the customer remains on the merchant’s page.
3. PeP processes the payment (sends the data to acquiring and issuing banks, card associations etc.).
4. The said institutions (they may vary depending on the payment method) respond to PeP, allowing to process the payment.
5. PeP returns information about the payment status to the merchant’s website.
6. The merchant can use the received information to inform his customer whether the transaction was successful and what its status is.

PeP Online REST Client is an API wrapper. It’s simply a layer written in a specific programming language that allows calling our RESTful API methods. All code examples on this page are based on the PeP REST Client.

JavaScript | PHP | Ruby | Python | Android

If you choose our REST API instead of the Secure Form, you’ll probably want to accept payments on your own website and improve the purchasing experience. This means you may have to collect some information from customers and pass it to PeP along with a payment request.

Most of the information required to send a payment request doesn’t have to be collected from the customer – at least not every time. For example customer information (name, email, address) can be retrieved from your database – assuming that you allow customers to create accounts on your site (e-store, web-app).

Also data such as the sale information (amount, currency, description) can be generated or retrieved automatically; however, it is a good practice to display such info on the payment screen. This way the customer will be assured that they’re paying the correct amount.

Payment methods

Depending on the selected payment method you may have to collect some information from the customer during the payment process.

In the most common situation you will present an HTML form for the customer to fill. After the form is submitted, you just send a request to PeP systems.

Examples

In most cases cards will require providing card information and direct debits will require account information. Standard payment forms for these payment methods may look like this:

  <form action="#" id="payment-form" method="post">
      <label>Numer karty:</label>
      <input type="text" id="card_number" name="card[card_number]" size="19" />

      <label>Imię i nazwisko na karcie:</label>
      <input type="text" id="name_on_card" name="card[name_on_card]" size="50" />

      <label>Data ważności:</label>
      <input type="text" id="expiration_month" name="card[expiration_month]" size="2" />
      <input type="text" id="expiration_year" name="card[expiration_year]" size="4" />

      <label>CVV/CVC:</label>
      <input type="text" id="card_code" name="card[card_code]" size="4" />

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

Cards are among the most popular payment methods in the world. Customers can use many kinds of cards to pay online, including credit cards, debit cards and pre-paid cards.

Cards are a good choice for most markets; some markets are even dominated by this payment method.

Before you start calling any API methods regarding card operations, please make sure that you have properly initiated the PeP Rest Client. It’s very easy, simply include a proper file and provide your user name and password.

PHP

  include_once ('PePRestClient.php');
  $client = new PePRestClient('your_login', 'your_password');

Ruby

  require 'pep_client'
  client = PeP::Client.new('your_login', 'your_password')

Python

  from client import PePRestClient
  client = PePRestClient("your_login", "your_password")

Android

  PePApi api = PePClientFactory.createClassicClient(context, "your_login", "your_password");

For further details on API integration (error codes, test card numbers etc.), please check the integration & testing section.

PeP REST.js API flow:

1. HTML markup is presented to the browser
2. The PeP.js client is initialized and awaits for the payment form to be submitted
3. Once the form is submitted, the PeP.js client sends all the sensitive credit card information to PeP's servers. A temporary credit card token (a 64byte long hexadecimal string) is generated, which is then injected back into the merchant’s payment form as a hidden input.
4. The usual form submission process is resumed, and the merchant’s servers receive the token along with the other information from the form (except for the sensitive card data).
5. The merchant can dispatch a sale/authorization/checkCard/checkCard3DSecure request using the secret token (this must occur within 15minutes of the token generation, as the token is temporary).

Here’s the basic HTML markup for a typical payment form:

<form id="checkout-form" action="" type="">
    <!-- merchant's input elements, as many as required -->
    <input type="text" name="first-name" value="">
    <input type="text" name="last-name" value="">
    <input type="text" name="email" value="">
    <input type="text" name="address" value="">

    <!-- card related input elements: -->
    <input type="text" value="" data-paylane="cc-number">
    <input type="text" value="" data-paylane="cc-expiry-month">
    <input type="text" value="" data-paylane="cc-expiry-year">
    <input type="text" value="" data-paylane="cc-cvv">
    <input type="text" value="" data-paylane="cc-name-on-card">

    <input type="submit" value="submit">
</form>

While the actual markup of the form can be fully altered to the merchant’s needs, the following points are crucial:

1. The card related input elements must have the appropriate data-paylane attributes.
2. The card related input elements must not have any name attributes. This is a security measure which prevents sensitive information from reaching the merchant’s servers.
3. The payment form must have a unique id attribute. This value will be referenced by the PeP.js client lib.

Next, initialize the PeP.js client:

  <script src="path/to/PeP.js"></script>
  <script>
      try
      {
          var client = new PePClient({
              publicApiKey : 'PUBLIC_API_KEY',
              paymentForm  : 'checkout-form',
          });
      }
      catch (e)
      {
          console.log(e); // exceptions are fatal
      }
  </script>

The only required values by the PeP.js client are the merchant’s public API key and a payment form selector.

• kthe API key must be the 40 character string key found in the PeP Merchant Panel (Menu => Account => Merchant account settings => API)
• the payment form selector can be one of the following:
  1. The ID attribute of your payment form
  2. A DOM node representing the form (one found by using document.forms[i], for example)
  3. A jQuery object, containing only the payment form

Optionally, the following values can also be passed to the PeP.js client (if they aren’t provided, the default values are used):

1. cardNumberInputName (default: cc-number) – an alternative data-paylane value used to reference the credit card number input element
2. cardExpiryMonthInputName (default: cc-expiry-month) – an alternative data-paylane value used to reference the credit card expiry month input element
3. cardExpiryYearInputName (default: cc-expiry-year) – an alternative data-paylane value used to reference the credit card expiry year input element
4. cardSecurityvarInputName (default: cc-cvv) – an alternative data-paylane value used to reference the credit card CVV/CVV2 input element
5. cardHolderInputName (default: cc-name-on-card) – an alternative data-paylane value used to reference the cardholder name input element
6. errorTypeInputName (default: paylane_error_type) – an alternative input name for the error type input element
7. errorCodeInputName (default: paylane_error_code) – an alternative input name for the error var input element
8. errorDescriptionInputName (default: paylane_error_description) – an alternative input name for the error description input element
9. tokenInputId (default: paylane-token) – an alternative ID attribute for the token input element
10. tokenInputName (default: paylane_token) – an alternative name attribute for the token input element
11. errorHandler (default: empty funkcja) – an error handler callback function, must take the following three arguments: type, code, description
12. callbackHandler (default: empty funkcja) – an optional form submission callback handler. This callback will be called once the AJAX request containing the temporary token is completed. The token will appear in the form as a hidden input, and will also be passed to the callback function as the only argument. If no callback is specified, the form will simply be resubmitted using the standard form submit event.

  /**
  Custom token callback handler.

  @param {string} token Temporary credit card token
  @return {void}
  */
  callbackHandler: function(token){}

PeP.js może wywoływać wyjątki i błędy.

Errors triggered by the PeP.js client are divided into two: exceptions and errors.

Exceptions are only thrown during the client initialization, for example when the necessary form or input elements cannot be found, or you pass an empty public key. These exceptions must be caught and handled using a try/catch block, though typically they will not occur if your form is set up correctly.

Errors, on the other hand, are slightly more unexpected as they can be caused by things such as network outages, malformed input data (such as a bad token or credit card number) and so on. The PeP.js client presents two methods for handling these errors; using an error callback (passed to the client constructor as errorHandler) and as hidden input fields in the payment form (which can be handled server-side).

1. Error handling: ```javascript /**

• Custom error handler which allows the merchant to
• handle errors raised by the PePClient class,
• such as connection errors or erroneous API responses.
• @param {int} type Error type from PePClient.errorTypes
• @param {int} [code] Error code from the API response
• @param {string} [description] Error description from the API response
• @return {void} */ function errorHandler(type, code, description) { console.log(type, code, description); } ```

2. Hidden input fields: The following hidden input fields will be appended to the payment form (please remember that their names can be overwritten by passing the necessary error* keys to the client constructor):

• paylane_error_type: type of the error; 1 if it’s a connection error, or 2 if it’s an error returned by the PeP REST.js API
• paylane_error_code: present only during API errors, this is the error code returned by the REST.js API
• paylane_error_description: present only during API errors, this is the error description returned by the REST.js API

Prepare all the data required to perform the transaction as follows. As you can see, in case of a card transaction there are three sets of information: sale, customer and card data.

Example code

PHP

  $card_params = array(
      'sale'     => array(
          'amount'      => 19.99,
          'currency'    => 'EUR',
          'description' => 'Product #1'
      ),
      'customer' => array(
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => array (
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'         => 'Washington',
              'state'        => 'DC',
              'zip'          => '500',
              'country_code' => 'US',
          ),
      ),
      'card' => array(
          'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4',
      ),
  );

Ruby

  card_params = {
      'sale' => {
          'amount'      => 19.99,
          'currency'    => 'EUR',
          'description' => 'Product #1',
      },
      'customer' => {
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => {
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'         => 'Washington',
              'state'        => 'DC',
              'zip'          => '500',
              'country_code' => 'US'
          }
      },
      'card' => {
          'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
      }
  }

Python

  card_params = {
    'sale' : {
      'amount'      : 19.99,
      'currency'    : 'EUR',
      'description' : 'Product #1'
    },
    'customer' : {
      'name'    : 'John Doe',
      'email'   : 'john@doe.com',
      'ip'      : '127.0.0.1',
      'address' : {
        'street_house' : '1600 Pennsylvania Avenue Northwest',
        'city'         : 'Washington',
        'state'        : 'DC',
        'zip'          : '500',
        'country_code' : 'US'
      }
    },
    'card' : {
      'token' : '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
    }
  }

Android

  Sale sale = new Sale(
      19.99, 
      "EUR", 
      "Product #1"
  );
  Card card = new Card(
      "4111111111111111", 
      "03", 
      "2017", 
      "John Doe", 
      "123"
  );
  Address address = new Address(
      "1600 Pennsylvania Avenue Northwest", 
      "Washington", 
      "DC", 
      "500", 
      "US"
  );
  Customer customer = new Customer(
      "John Doe", 
      "john@doe.com", 
      "127.0.0.1", 
      address
  );

Now simply perform the transaction using the card_sale_by_token method.

You can check whether the transaction was performed successfully by calling the 'is_success' method.

Retrieving the transaction ID number (or error details, if anything goes wrong) is also very simple and can be done as presented below.

Example code

PHP

  try {
      $status = $client->cardSaleByToken($card_params);
  } catch (Exception $e) {
      // handle exceptions here
  }   

  // checking transaction status example (optional):
  if ($client->isSuccess()) {
      echo "Success, id_sale: {$status['id_sale']} \n"; 
  } else {
      die("Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  begin
      status = client.card_sale_by_token(card_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  # checking transaction status example (optional):
  if client.success?
      puts "Success, id_sale: #{status["id_sale"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
      exit
  end

Python

  try:
      status = client.card_sale_by_token(card_params)
  except Exception, e:
      # handle exceptions here

  # checking transaction status example (optional):
  if client.is_success():
      print 'Success, id_sale: %s' % status['id_sale']
  else:
      sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
              'Error number: ' + str(status["error"]["error_number"]) + '\n' \
              'Error description: ' + str(status["error"]["error_description"]))

Android

  api.cardSale(sale, customer, card, new Callback<CardSaleResult>() {

        @Override
        public void onFinish(CardSaleResult result) {
            // success
        }

        @HandleException
        public void onProtocolError(ProtocolException e) {
            // invoke if not success
            // e.getCode() - error code
            // e.getMessage() - error message
        }

        @Override
        public void onError(Exception e) {
            // connection error etc.
        }

You can find all the structures’ descriptions in the REST Function Reference manual.

You may wish not to charge a customer, but only to authorize their card. This is quite useful in various scenarios, for example:

• getting the card number when a customer signs up for a free trial (you can charge them later automatically),
• checking the credit card (for example whether online transactions are not blocked),
• confirming the card when a customer creates an account in your e-store.

Authorizing a card means blocking a specific amount for some time on the customer’s card. You can either block the whole amount (and capture the funds later) or you can block just $1 (or €1, or £1, or…) just to verify the card.

Start with preparing data required to perform the authorization. Note that the data comes in exactly the same format as when performing a regular transaction. You can choose whether to authorize for just one euro, dollar, pound (or any other currency), or for the whole amount (if you’re planning to capture the funds later).

Example code

PHP

  $card_params = array(
      'sale' => array(
          'amount'      => 1.00,
          'currency'    => 'EUR',
          'description' => 'Product #1'
      ),
      'customer' => array(
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => array (
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'          => 'Washington',
              'state'         => 'DC',
              'zip'           => '500',
              'country_code'  => 'US',
          ),
      ),
      'card' => array(
          'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
      ),
  );

Ruby

  card_params = {
      'sale' => {
          'amount'      => 19.99,
          'currency'    => 'EUR',
          'description' => 'Product #1',
      },
      'customer' => {
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => {
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'         => 'Washington',
              'state'        => 'DC',
              'zip'          => '500',
              'country_code' => 'US'
          }
      },
      'card' => {
          'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
      }
  }

Python

  card_params = {
    'sale' : {
      'amount'      : 19.99,
      'currency'    : 'EUR',
      'description' : 'Product #1'
    },
    'customer' : {
      'name'    : 'John Doe',
      'email'   : 'john@doe.com',
      'ip'      : '127.0.0.1',
      'address' : {
        'street_house' : '1600 Pennsylvania Avenue Northwest',
        'city'         : 'Washington',
        'state'        : 'DC',
        'zip'          : '500',
        'country_code' : 'US'
      }
    },
    'card' : {
      'token' : '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
    }
  }

Android

  Sale sale = new Sale(19.99, "EUR", "Product #1");
  Address address = new Address("1600 Pennsylvania Avenue Northwest", "Washington", "DC", "500", "US");
  Customer customer = new Customer("John Doe", "john@doe.com", "127.0.0.1", address);
  Card card = new Card("4111111111111111", "03", "2017", "John Doe", "123");

Having the data prepared, simply call the card_authorization_by_token method (just like you would do with the card_sale method).

You can also easily check whether the authorization was successful and retrieve the ID number (as presented below) – you can use it later to perform resales within the recurring payments.

Example code

PHP

  try {
      $status = $client->cardAuthorizationByToken($card_params);
  } catch (Exception $e) {
      // handle exceptions here
  }

  // checking authorization status example (optional):
  if ($client->isSuccess()) {
      echo "Success, id_authorization: {$status['id_authorization']} \n"; 
  } else {
      die("Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  begin
      status = client.card_authorization_by_token(card_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  # checking authorization status example (optional):
  if client.success?
      puts "Success, id_authorization: #{status["id_authorization"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
      exit
  end

Python

  try:
      status = client.card_authorization_by_token(card_params)
  except Exception, e:
      # handle exceptions here

  # checking authorization status example (optional):
  if client.is_success():
      print 'Success, id_authorization: %s' % status['id_authorization']
  else:
      sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
              'Error number: ' + str(status["error"]["error_number"]) + '\n' \
              'Error description: ' + str(status["error"]["error_description"]))

Android

  api.cardAuthorization(sale, customer, card, new Callback<AuthorizationResult>() {

      @Override
      public void onFinish(AuthorizationResult result) {
          // success
      }

      @HandleException
      public void onProtocolError(ProtocolException e) {
          // invoke if not success
          // e.getCode() - error code
          // e.getMessage() - error message
      }

      @Override
      public void onError(Exception e) {
          // connection error etc.
      }
  });

Recurring payments are simply resales performed in specific time periods. You can perform them based on any conditions defined by your business model.

Resales do not require all the credit/debit card and customer information. That is why they have to use either a single transaction (usually the first transaction which initiated the whole recurring procedure) or a card authorization.

This means we can define two types of recurring payments:

• based on transactions,
• based on card authorization

Important: Your first sale/authorization should always check 3D – Secure. For recuring payment based on transaction use 3DSecure-authSale and for based on card authorization use 3DSecure-auth

Start with preparing the necessary information to perform a resale. In order to do that you must first retrieve the ID number of a previous transaction. This ID number identifies the transaction in PeP's systems. You can easily retrieve this number while performing the transaction, for example:

Example code

PHP

  $status = $client->cardSale($card_params);
  $id_first_sale = $status['id_sale'];

Ruby

  status = client.card_sale(card_params)
  id_first_sale = status['id_sale']

Python

  status = client.card_sale(card_params)
  id_first_sale = status['id_sale']

Android

  api.cardSale(sale, customer, card, new Callback<CardSaleResult>() {
      @Override
      public void onFinish(CardSaleResult result) {
          long idFirstSale = result.getIdSale();
      }
  });

See the Single transaction page for more details on performing a single sale.

Although you can refer to any previous transaction ID to perform a resale, we highly recommend to refer to the most recent transaction. This approach has several advantages, for example it allows to easily track the transaction flow.

Usually merchants store such ID numbers in their database. This way they do not have to store any sensitive data, yet they are still able to refer to a specific transaction.

Now, having retrieved the ID number (i.e. from your database), prepare the required information and call the resale_by_sale function.

You can also check whether the transaction was performed successfully by calling the is_success method. Retrieving the transaction ID number (or error details, if anything goes wrong) is also very simple and can be done as follows.

Example code

PHP

  $resale_params = array(
      'id_sale'     => $id_first_sale,
      'amount'      => 99.99,
      'currency'    => 'EUR',
      'description' => 'Recurring billing product #1',
  );

  // perform the resale:
  try {
      $status = $client->resaleBySale($resale_params);
  } catch (Exception $e) {
      // handle exceptions here
  }

  // checking transaction status example (optional):
  if ($client->isSuccess()) {
      echo "Success, second id_sale: {$status['id_sale']} \n";
  } else {
      die("Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  resale_params = {
      'id_sale'     => id_first_sale,
      'amount'      => 99.99,
      'currency'    => 'EUR',
      'description' => 'Recurring billing product #1'
  }

  # perform the resale:
  begin
      status = client.resale_by_sale(resale_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  # checking transaction status example (optional):
  if client.success?
      puts "Success, id_second_sale: #{status["id_sale"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
      exit
  end

Python

  resale_params = {
    'id_sale'     : id_first_sale,
    'amount'      : 99.99,
    'currency'    : 'EUR',
    'description' : 'Recurring billing product #1'
  }

  # perform the resale:
  try:
      status = client.resale_by_sale(resale_params)
  except Exception, e:
      # handle exceptions here

  # checking transaction status example (optional):
  if client.is_success():
      print 'Success, second id_sale: %s' % status['id_sale']
  else:
      sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
              'Error number: ' + str(status["error"]["error_number"]) + '\n' \
              'Error description: ' + str(status["error"]["error_description"]))

Android

  api.resaleSale(
      idFirstSale, 
      99.99, 
      "EUR", 
      "Recurring billing product #1", 
      new Callback<FraudSaleResult>() {
          @Override
          public void onFinish(FraudSaleResult result) {
              // success
          }

          @HandleException
          public void onProtocolError(ProtocolException e) {
              // invoke if not success
              // e.getCode() - error code
              // e.getMessage() - error message
          }

          @Override
          public void onError(Exception e) {
              // connection error etc.
          }
      }
  );

Recurring payments are just resales performed periodically. It’s your choice whether you want to do this weekly, monthly or annually; it is also possible to perform a resale e.g. when a customer reaches a certain amount that should be paid.

If a customer did not buy anything yet (no transaction was performed), you can still begin with recurring payments. The customer just has to provide you the necessary card data.

You can collect such data in various situations, for example:

• when the customer signs up for an account in your e-store,
• when a customer signs up for a free trial. When you collect the data, perform a card authorization and save its ID number.

Now let’s get back to recurring payments. Assuming that you have already retrieved the customer’s card authorization ID number, you can prepare the required data and perform a resale (call the resale_by_authorization method).

Just like in the case of the resale based on the first sale, you can check whether the transaction was performed successfully by calling the is_success method; you can also retrieve the transaction ID number (or error details, if anything goes wrong).

Example code

PHP

  $resale_params = array(
      'id_authorization' => $id_authorization,
      'amount'           => 99.99,
      'currency'         => 'EUR',
      'description'      => 'Recurring billing product #1',
  );  

  // perform the resale:
  try {
      $status = $client->resaleByAuthorization($resale_params);
  } catch (Exception $e) {
      // handle exceptions here
  }

  // checking transaction status example (optional):
  if ($client->isSuccess()) {
      echo "Success, second id_sale: {$status['id_sale']} \n";
  } else {
      die("Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  resale_params = {
      'id_authorization' => id_authorization,
      'amount'           => 99.99,
      'currency'         => 'EUR',
      'description'      => 'Recurring billing product #1'
  }

  # perform the resale:
  begin
      status = client.resale_by_authorization(resale_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  # checking transaction status example (optional):
  if client.success?
      puts "Success, id_second_sale: #{status["id_sale"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
      exit
  end

Python

  resale_params = {
    'id_authorization' : id_authorization,
    'amount'           : 99.99,
    'currency'         : 'EUR',
    'description'      : 'Recurring billing product #1'
  }

  # perform the resale:
  try:
      status = client.resale_by_authorization(resale_params)
  except Exception, e:
      # handle exceptions here

  # checking transaction status example (optional):
  if client.is_success():
      print 'Success, second id_sale: %s' % status['id_sale']
  else:
      sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
              'Error number: ' + str(status["error"]["error_number"]) + '\n' \
              'Error description: ' + str(status["error"]["error_description"]))

Android

  api.resaleAuthorization(idAuthorization, 99.99, "EUR", "Recurring billing product #1", new Callback<FraudSaleResult>() {

      @Override
      public void onFinish(FraudSaleResult result) {
          // success
      }

      @HandleException
      public void onProtocolError(ProtocolException e) {
          // invoke if not success
          // e.getCode() - error code
          // e.getMessage() - error message
      }

      @Override
      public void onError(Exception e) {
          // connection error etc.
      }
  });

There are cases when you want to return customer’s money – either the whole amount or just a part of it. This is exactly what a refund is for – it allows you to return funds in reference to a specific transaction.

In order to perform a refund, you must know the transaction ID number. This ID number identifies the transaction in PeP's systems. You can easily retrieve this number while performing the transaction, for example:

Example code

PHP

  $status = $client->cardSale($card_params);
  $id_sale = $status['id_sale'];

Ruby

  status = client.card_sale(card_params)
  id_sale = status['id_sale']

Python

  status = client.card_sale(card_params)
  id_sale = status['id_sale']

Android

  api.cardSale(sale, customer, card, new Callback<CardSaleResult>() {
      @Override
      public void onFinish(CardSaleResult result) {
          long idFirstSale = result.getIdSale();
      }
  });

See the Single transaction page for more details on performing a single sale.

Usually merchants store such ID numbers in their database. This way they do not have to store any sensitive data, yet they are still able to refer to a specific transaction.

Now prepare the required data and perform the refund. Note that you can provide the amount of the transaction or less; if you enter a greater value than the transaction amount, you will receive an error message. You can also specify the refund’s reason and currency.

Just like with any other transaction, you can also check whether the refund was performed successfully by calling the is_success method. Retrieving the refund ID number (or error details, if anything goes wrong) is also very simple and can be done as presented below.

Example code

PHP

  $refund_params = array(
      'id_sale' => $id_sale,
      'amount'  => 9.99,
      'reason'  => 'Partial refund',
  );

  // perform the refund:
  try {
      $status = $client->refund($refund_params);
  } catch (Exception $e) {
      // handle exceptions here
  }

  // checking refund status example (optional):
  if ($client->isSuccess()) {
      echo "Success, id_refund: {$status['id_refund']} \n";
  } else {
      die("Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  refund_params = {
      'id_sale' => id_sale,
      'amount'  => 9.99,
      'reason'  => 'Partial refund.'
  }

  # perform the refund:
  begin
      status = client.refund(refund_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  # checking refund status example (optional):
  if client.success?
      puts "Success, id_refund: #{status["id_refund"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
      exit
  end

Python

  refund_params = {
    'id_sale' : id_sale,
    'amount'  : 9.99,
    'reason'  : 'Partial refund'
  }

  # perform the refund:
  try:
      status = client.refund(refund_params)
  except Exception, e:
      # handle exceptions here

  # checking refund status example (optional):
  if client.is_success():
      print 'Success, id_refund: %s' % status['id_refund']
  else:
      sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
              'Error number: ' + str(status["error"]["error_number"]) + '\n' \
              'Error description: ' + str(status["error"]["error_description"]))

Android

  api.refund(idSale, 9.99, "EUR", "Partial refund", new Callback<FraudSaleResult>() {

      @Override
      public void onFinish(FraudSaleResult result) {
          // success
      }

      @HandleException
      public void onProtocolError(ProtocolException e) {
          // invoke if not success
          // e.getCode() - error code
          // e.getMessage() - error message
      }

      @Override
      public void onError(Exception e) {
          // connection error etc.
      }
  });

Prepare all the data required to perform the transaction as follows. As you can see, in case of a card transaction there are three sets of information: sale, customer and card data.

Example code

PHP

  $card_params = array(
      'sale' => array(
          'amount'      => 100.00,
          'currency'    => 'EUR',
          'description' => 'Product #1'
      ),
      'customer' => array(
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => array (
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'         => 'Washington',
              'state'        => 'DC',
              'zip'          => '500',
              'country_code' => 'US',
          ),
      ),
      'card' => array(
          'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
      ),
      'back_url' => 'http://example.com/3dsecure', // 3d secure back redirect url
  );

Ruby

  card_params = {
      'sale' => {
          'amount'      => 19.99,
          'currency'    => 'EUR',
          'description' => 'Product #1',
      },
      'customer' => {
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => {
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'         => 'Washington',
              'state'        => 'DC',
              'zip'          => '500',
              'country_code' => 'US'
          }
      },
      'card' => {
          'token' => '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
      },
      'back_url' => 'http://example-url.com'
  }

Python

  card_params = {
    'sale' : {
      'amount'      : 19.99,
      'currency'    : 'EUR',
      'description' : 'Product #1'
    },
    'customer' : {
      'name'    : 'John Doe',
      'email'   : 'john@doe.com',
      'ip'      : '127.0.0.1',
      'address' : {
        'street_house' : '1600 Pennsylvania Avenue Northwest',
        'city'         : 'Washington',
        'state'        : 'DC',
        'zip'          : '500',
        'country_code' : 'US'
      }
    },
    'card' : {
      'token' : '12a34b45c67d89e00f1aa2bb3cc4dd5ee6ff12a34b45c67d89e00f1aa2bb3cc4'
    },
    'back_url' : 'http://example.com/3dsecure'
  }

Android

  Sale sale = new Sale(19.99, "EUR", "Product #1");
  Address address = new Address("1600 Pennsylvania Avenue Northwest", "Washington", "DC", "500", "US");
  Customer customer = new Customer("John Doe", "john@doe.com", "127.0.0.1", address);
  Card card = new Card("4111111111111111", "03", "2017", "John Doe", "123")

To check whether a card is enrolled in the 3-D Secure program, simply call the check_card_3d_secure_by_token method. If the card is enrolled, you will also get an id_3dsecure_auth number.

Example code

PHP

  try {
      $status = $client->checkCard3DSecureByToken($card_params);
  }
  catch (Exception $e) {
      // Handle exception here, for example show an error page, stop action
  }

  if ($client->isSuccess()) {
      echo "Success, id_3dsecure_auth: {$status['id_3dsecure_auth']} \n"; 
  } else {
      echo "Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}";
  }

  if (true == $status['is_card_enrolled'])
  {
      // redirect to 3-D Secure provider
      header('Location: ' . $status['redirect_url']);
      die;
  }

Ruby

  begin
      status = client.check_card_3d_secure_by_token(card_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  if client.success?
      puts "Success, id_3dsecure_auth: #{status["id_3dsecure_auth"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
  end

  if status['is_card_enrolled']
      # redirect to url in status['redirect_url']
      exit
  end

Python

  try:
      status = client.check_card_3d_secure_by_token(card_params)
  except Exception, e:
      # handle exceptions here

  if client.is_success():
      print 'Success, id_3dsecure_auth: %s' % status['id_3dsecure_auth']
  else:
      print 'Error (%s), %s - %s' % (status['error'].get('id_error'),
                                    status['error'].get('error_number'),
                                    status['error'].get('error_description'))

  if status['is_card_enrolled']:
      # redirect to url in status['redirect_url']
      sys.exit()

Android

  api.secure3DCheckCard(sale, customer, card, "http:// example.com/3dsecure", new Callback<Secure3DSaleResult>() {

  @Override
  public void onFinish(Secure3DSaleResult result) {

      if (result.isEnrolled()) {
          WebView webview =...;
          webview.loadUrl(result.getRedirectUrl());
      }
  }

      @HandleException
      public void onProtocolError(ProtocolException e) {
          // invoke if not success
          // e.getCode() - error code
          // e.getMessage() - error message
      }

      @Override
      public void onError(Exception e) {
          // connection error etc.
      }
  });

If the 3-D Secure request was performed successfully, you may now proceed with the actual transaction and redirect the customer to the 3-D Secure provider’s website (use the received redirect_url).

If the transaction was rejected and you received an error, process with a regular single card payment. You should also save the received error information in your system.

After providing the required information, the customer will be redirected back to your website (back_url). You should now verify the returned information to avoid any fraud attempts and check the transaction’s status.

Example code

PHP

  $salt        = 'YOUR_HASH_SALT';
  $status      = $_GET['status'];
  $description = $_GET['description'];
  $amount      = $_GET['amount'];
  $currency    = $_GET['currency'];
  $hash        = $_GET['hash'];

  $id = '';
  if ($status !== 'ERROR') // success, get id_3dsecure_auth
      $id = $_GET['id_3dsecure_auth'];
      
  $calc_hash = sha1("{$salt}|{$status}|{$description}|{$amount}|{$currency}|{$id}");

  // check hash salt
  if ( $calc_hash !== $hash ) {
      die ("Error, wrong hash");
  }

  // check transaction status
  if ($status === 'ERROR') {
      die("Error, 3-D auth transaction declined");
  } else {
      // 3-D Secure authorization completed, perform sale
  }

Ruby

  # Simple controller action code in Rails
  # it's just an example - most of the logic should be moved to model

  salt        = 'YOUR_HASH_SALT'
  status      = params['status']
  description = params['description']
  amount      = params['amount']
  currency    = params['currency']
  hash        = params['hash']

  id = ''
  unless status == 'ERROR'
      id = params['id_3dsecure_auth']
  else
  # redirect to an index action to correct the payment + simple notice
  # for Rails: redirect_to :index, :notice => "Error, 3-D auth transaction declined"
  end

  calc_hash = Digest::SHA1.hexdigest("#{salt}|#{status}|#{description}|#{amount}|#{currency}|#{id}")

  unless calc_hash == hash
  # redirect to an index action to correct the payment
  # for Rails: redirect_to :index, :notice => "Wrong hash"
  end


  # check transaction status

  if status == 'ERROR'
  # redirect to an index action to correct the payment + simple notice
  # for Rails: redirect_to :index, :notice => "Error, 3-D auth transaction declined"
  else
  # 3-D Secure authorization completed, perform sale
  end

Python

  salt             = 'YOUR_HASH_SALT'
  status           = get_request_param('status')
  description      = get_request_param('description')
  amount           = get_request_param('amount')
  currency         = get_request_param('currency')
  hash             = get_request_param('hash')
  id_3dsecure_auth = None

  # success, get id_3dsecure_auth
  if status != 'ERROR':
      id_3dsecure_auth = get_request_param('id_3dsecure_auth')

  calc_hash = hashlib.sha1(
      '|'.join([salt, status, description, amount, currency, id_3dsecure_auth])).hexdigest()

  # check hash salt
  if calc_hash != hash:
      sys.exit('Error, wrong hash')

  # check transaction status
  if status == 'ERROR':
      sys.exit('Error, 3-D auth transaction declined')
  else:
      # '3-D Secure authorization completed, perform sale'

Android

  webview.setWebViewClient(new WebViewClient() {
      @Override
      public boolean shouldOverrideUrlLoading(WebView view, String url) {

          if (url.contains(redirectUrl)) {
              try {
                  Map<String, String> map = getQueryMap(new URL(url).getQuery());
                  String salt = "YOUR_HASH_SALT";
                  String status = map.get("status");
                  String description = map.get("description");
                  String amount = map.get("amount");
                  String currency = map.get("currency");
                  String hash = map.get("hash");
                  String id = map.get("id_3dsecure_auth");

                  String calcHash = sha1(String.format("%1$s|%2$s|%3$s|%4$s|%5$s|%6$s", salt, status, description, amount, currency, id));

                  //  check hash salt
                  if (!calcHash.equals(hash)) {
                      // Error, wrong hash
                  }

                  if (status.equals("ERROR")) {
                      String errorDescription=map.get("error_description");
                      // Error, transaction declined

                  } else {
                      String idSale=map.get("id_sale");
                      // Success, transaction completed
                  }

              } catch (MalformedURLException e) {
                  e.printStackTrace();
              } catch (NoSuchAlgorithmException e) {
                  e.printStackTrace();
              } catch (UnsupportedEncodingException e) {
                  e.printStackTrace();
              }
          } else {
              view.loadUrl(url);
          }
          return true;
      }
  });

  public static Map<String, String> getQueryMap(String query) {
      String[] params = query.split("&");
      Map<String, String> map = new HashMap<String, String>();
      for (String param : params) {
          String name = param.split("=")[0];
          String value = param.split("=")[1];
          map.put(name, value);
      }
      return map;
  }

  private static String convertToHex(byte[] data) {
      StringBuilder buf = new StringBuilder();
      for (byte b : data) {
          int halfbyte = (b >>> 4) & 0x0F;
          int two_halfs = 0;
          do {
              buf.append((0 <= halfbyte) && (halfbyte <= 9) ? (char) ('0' + halfbyte) : (char) ('a' + (halfbyte - 10)));
              halfbyte = b & 0x0F;
          } while (two_halfs++ < 1);
      }
      return buf.toString();
  }

  public static String sha1(String text) throws NoSuchAlgorithmException, UnsupportedEncodingException {
      MessageDigest md = MessageDigest.getInstance("SHA-1");
      md.update(text.getBytes("utf-8"), 0, text.length());
      byte[] sha1hash = md.digest();
      return convertToHex(sha1hash);
  }

If everything went fine, you may now perform the actual payment based on the 3-D Secure authorization.

You can check whether the transaction was performed successfully by calling the is_success method. Retrieving the transaction ID number (or error details, if anything goes wrong) is also very simple and can be done as shown below.

Example code

PHP

  try {
      $status = $client->saleBy3DSecureAuthorization(array ('id_3dsecure_auth' => $id));
  } catch (Exception $e) {
      // Handle exception here, for example show an error page, stop action
  }

  if ($client->isSuccess())
  {
      echo "Success, id_sale: {$status['id_sale']} \n";
  } else {
      echo "Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  begin
      status = client.sale_by_3d_secure_authorization({"id_3dsecure_auth" => id})
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  if client.success?
      puts "Success, id_sale: #{status["id_sale"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
  end

Python

  try:
      status = client.sale_by_3d_secure_authorization(
          {'id_3dsecure_auth': id_3dsecure_auth})
  except Exception, e:
      # handle exceptions here

  if client.is_success():
      print 'Success, id_sale: %s' % status['id_sale']
  else:
      print 'Error (%s), %s - %s' % (status['error'].get('id_error'),
                                    status['error'].get('error_number'),
                                    status['error'].get('error_description'))

Android

  Secure3DSaleResult result =...;
  long id3dSecureAuth = result.getId3dSecureAuth();
  api.secure3DAuthSale(id3dSecureAuth, new Callback<CardSaleResult>() {

      @Override
      public void onFinish(CardSaleResult result) {
          // success
      }
  });

The situation presented above is an ideal flow. But it may happen that a card is not enrolled in the 3-D Secure program. Here’s how to deal with that.

After the 3-D authorization was performed, make sure that the card is enrolled and simply call the sale_by_3d_secure_authorization method like you would normally. It is important that you do this (instead of performing a regular sale) for security reasons – this way the whole 3-D Secure attempt will be recorded.

You can check whether the transaction was performed successfully by calling the is_success method. Retrieving the transaction ID number (or error details, if anything goes wrong) is also very simple and can be done as shown below.

Example code

PHP

  $id_3dsecure_auth = $status['id_3dsecure_auth'];

  if (true != $status['is_card_enrolled'])
  {
      try {
          $status = $client->saleBy3DSecureAuthorization(array ('id_3dsecure_auth' => $id_3dsecure_auth));
      } catch (Exception $e) {
          // Handle exception here, for example show an error page, stop action
      }
  }

  if ($client->isSuccess()) {
      echo "Success, id_sale: {$status['id_sale']} \n";
  } else {
      echo "Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  id_3dsecure_auth = status['id_3dsecure_auth']

  unless status['is_card_enrolled']
      begin
          status = client.sale_by_3d_secure_authorization({"id_3dsecure_auth" => id_3dsecure_auth})
      rescue PeP::ClientError => e
          # Handle exception here, for example show an error page, stop action
      end 
  end

  if client.success?
      puts "Success, id_sale: #{status["id_sale"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
  end

Python

  if not is_card_enrolled:
      try:
          status = client.sale_by_3d_secure_authorization(
              {'id_3dsecure_auth': id_3dsecure_auth})
      except Exception, e:
          # Handle exception here, for example show an error page, stop action

  if client.is_success():
      print 'Success, id_sale: %s' % status['id_sale']
  else:
      print 'Error (%s), %s - %s' % (status['error'].get('id_error'),
                                    status['error'].get('error_number'),
                                    status['error'].get('error_description'))

Android

  Secure3DSaleResult result =...;
  if (!result.isEnrolled()) {
      api.secure3DAuthSale(result.getId3dSecureAuth(), new Callback<CardSaleResult>() {

          @Override
          public void onFinish(CardSaleResult result) {
              // success
          }
      });
  }

Google Pay™ lets your customers pay with the press of a button — using payment methods saved to their Google Account.

Customer payment data is end-to-end encrypted from Google’s servers to your payment processor.

Google Pay works with your existing payments processing stack and can be implemented with a few lines of code.

Please review following documentations before continuing:

• Google Pay for Web overview
• Brand guidelines
• Integration checklist

Create production account Google Pay:

• Google Pay production access

Load required libraries:

  "https://pay.google.com/gp/p/js/pay.js"
  "https://js.pep.pl/v1"

  // set up PeP JS client
  PeP.setPublicApiKey('MY_PUBLIC_API_KEY');

  // set up Google Pay with production Account
  PeP.googlePay.init({ 
  environment: 'PRODUCTION',  
  googleMerchantId: 'ID UZYSKAZANE PO ZAŁOŻENIU KONTA PRODUKCYJNEGO W GOOGLE'
  });

  // prepare basic transaction data
  const TRANSACTION = {
    currencyCode: "USD",
    totalPrice: "1.00"
  };

  // check whether Google pay is available
  PeP.googlePay
    .isReadyToPay()
    .then(function(response) {
      if (response.result) {
        // proceed
        showGooglePayBtn();
      } else {
        console.warn("Google Pay is not available");
      }
    })
    .catch(function(err) {
      // handle errors here
      console.error(err);
    });

  const showGooglePayBtn = function() {
    // create Google Pay button
    const button = PeP.googlePay.createButton({
      onClick: onGooglePaymentButtonClicked
    });

    // append button
    document.getElementById('container').appendChild(button);
  };

  const onGooglePaymentButtonClicked = function() {
    PeP.googlePay
      .loadPayment(TRANSACTION)
      .then(function(paymentData) {
        // extract and encode payment token
        const token = btoa(paymentData.paymentMethodData.tokenizationData.token);

        // pass required transaction data along with the `token` to your backend
        // application and perform transaction
      })
      .catch(function(err) {
        // handle errors here
        console.error(err);
      });
  };

Before you start calling any API methods regarding card operations, please make sure that you have properly initiated the PeP Rest Client. It’s very easy, simply include a proper file and provide your user name and password.

PHP

  include_once ('PePRestClient.php');
  $client = new PePRestClient('your_API_login', 'your_API_password');

For further details on API integration (error codes, test card numbers etc.), please check the integration & testing section.

Prepare all the data required to perform the transaction as follows. As you can see, in case of a Google Pay transaction there are three sets of information: sale, customer and card data.

Sample Request

  {
      "sale": {
          "amount": 1.00,
          "currency": "USD",
          "description": "TR001"
      },
      "customer": {
          "name": "John Doe",
          "email": "john.doe@example.com",
          "country_code": "US",
          "ip": "127.0.0.1"
      },
      "card": {
          "token": "eyJzaWduYXR1cmUiOiJNRVlDSVFDcUE1T0Vpd1ptR29GNlVqUEI3MktBNWtOa2lyUE5WMGN0T1A4Uytwam1qd0loQUo1QjVXa3Vnd1JhNWk3enRUWjE4eHBEWjJXK0hNTjh3a0M2SFFCZ3ZyUWkiLCJwcm90b2NvbFZlcnNpb24iOiJFQ3YxIiwic2lnbmVkTWVzc2FnZSI6IntcImVuY3J5cHRlZE1lc3NhZ2VcIjpcIlJnSGV1UVA4OVFpa1FDZmtLemRia1g3dU4wUE8zSmFDcE5hRHRhQ1ZkQ0ErZFkvL0VyRzZvQ1NZZ3Yyc3dONkdaRmZwd09zL1ZiVTNjcVFLRC81YXRNQVV5STNidnZpOGRxcXlOb0J4aTVkUi9tbS9OZmRJdHpSdEE3YXovSndMTEpreGNOMzRLZHNQV3VhVHhRZ2MyWFBCUkN2TVpLeUQ1VWNuY1U4cktKSEhnSWlNZEMwUnhNU0Uxc1RVWEwxVDk0eURJck9jdlNlcmRYdnpLZGhUOUQxcUl0azA2VW5uc2dhRHFWdGg0SHMyY1hTUFVJYlNIc25ydlRsZGg2dGlkOTF2WWZRYldYeElqQUF1ZFRQME8xR25oTnJjYXo5WjBxeUVWUEVQQnVzc29kWU1pL1JQa3VNREh6TU1sUUV2Mms3SXBtdDZJZGVnd0t5L21VYlFNeld1NDdzc2Jmb2xWbW1vOGRrTlJhYmo5Z0dtQWwrL1ErelY1MUNPeG5CSWhBUHU2NUMwZ3RuTi8yZWJMNnZNdWQxbE5xRXV0WVd4alpGRWY4Q2ZkZ3lQM3M5WXdYWXdoenRTTi9ycGhCV1hpWmNOT29Ea2xxWWEvSVphT2o0TnVnNVdLU3hka2pVazhmSTJiNlV2ZEIwbHMrakpuenZRdStzUndlWHZoNmRRa2JuazhGS3VKeVdkZGl2c3NJcjlJZW1Jc3JFOUE5T3FlSnpWOVRjSThRb01ZWmNiQUZkcUlBRjhWTUJLSjMwU28yYyt4SnU5b21FUy9QbFVXU1hJdXltL1hXMldhd1xcdTAwM2RcXHUwMDNkXCIsXCJlcGhlbWVyYWxQdWJsaWNLZXlcIjpcIkJGZzZoNWZkQ0RIbWFNODlNN0VKOVdyWHVkZWh3bzFrci8rWmdNZDJiUE5NNmhHVVZRZVp2VHRZSm5ua1dGY2JVODZteXU0WmduM2VyL05pMUNwVFk1RVxcdTAwM2RcIixcInRhZ1wiOlwiY3NzcXNmcnJpSDRwSzlUQmJPRWpSMDc2Slc2YWNKL3JEQ3JHTUpaLzFaa1xcdTAwM2RcIn0ifQ=="
      }
      "back_url"  :   "http://example-url.com"
  }

Now simply perform the transaction using the googlePaySale or googlePayAuthorization method.

Retrieving the transaction ID number (or error details, if anything goes wrong) is also very simple and can be done as presented below.

PHP

  try {
      $status = $client->googlePaySale($google_pay_params);
  } catch (Exception $e) {
      // handle exceptions here
  }

  // checking transaction status example (optional):
  if ($client->isSuccess()) {
      echo "Success, id_sale: {$status['id_sale']} \n";
  } else {
      die("Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

Ruby

  begin
      status = client.google_pay_sale(google_pay_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end

  # checking transaction status example (optional):
  if client.success?
      puts "Success, id_sale: #{status["id_sale"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
      exit
  end

Python

  try:
      status = client.google_pay_sale(google_pay_params)
  except Exception, e:
      # handle exceptions here

  # checking transaction status example (optional):
  if client.is_success():
      print 'Success, id_sale: %s' % status['id_sale']
  else:
      sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
              'Error number: ' + str(status["error"]["error_number"]) + '\n' \
              'Error description: ' + str(status["error"]["error_description"]))

You can find all the structures’ descriptions in the REST Function Reference manual.

Bank transfers are one of the most common payment methods (along with credit cards). What is more, customers in some countries highly prefer this way of paying for goods purchased online – whole payment systems or mechanisms based on bank transfers emerge from such local trends.

Before using the API and calling any methods regarding bank transfers, remember to ensure that the PeP Rest Client was initiated. Remember to provide the correct user name and password.

Example code

PHP

  include_once ('PePRestClient.php');
  $client = new PePRestClient('your_login', 'your_password');

Ruby

  require 'pep_client'
  client = PeP::Client.new('your_login', 'your_password')

Python

  from client import PePRestClient
  client = PePRestClient("your_login", "your_password")

Android

  PePApi api = PePClientFactory.createClassicClient(context, "your_login", "your_password");

Start with preparing information required to perform a bank transfer. Provide sale and customer data, specify the payment type to choose a bank and define a back url – customers will be redirected to this website after submitting the payment.

Example code

PHP

  $bt_params = array(
      'sale' => array(
          'amount'      => 19.99,
          'currency'    => 'PLN',
          'description' => 'Product #1'
      ),
      'customer' => array(
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => array (
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'         => 'Washington',
              'state'        => 'DC',
              'zip'          => '500',
              'country_code' => 'US',
          ),
      ),
      'payment_type' => 'MT',
      'back_url'     => 'http://example-page.com',
  );

Ruby

  bt_params = {
      'sale' =>   {
          'amount'      => 19.99,
          'currency'    => 'PLN',
          'description' => 'Product #1'
      },
      'customer' =>   {
          'name'    => 'John Doe',
          'email'   => 'john@doe.com',
          'ip'      => '127.0.0.1',
          'address' => {
              'street_house' => '1600 Pennsylvania Avenue Northwest',
              'city'         => 'Washington',
              'state'        => 'DC',
              'zip'          => '500',
              'country_code' => 'US'
          },
      },
      'payment_type' => 'MT',
      'back_url'     => 'http://example-page.com'
  }

Python

  bt_params = {
    'sale' : {
      'amount'      : 19.99,
      'currency'    : 'PLN',
      'description' : 'Product #1'
    },
    'customer' : {
      'name'    : 'John Doe'
      'email'   : 'john@doe.com',
      'ip'      : '127.0.0.1',
      'address' : {
        'street_house' : '1600 Pennsylvania Avenue Northwest',
        'city'         : 'Washington',
        'state'        : 'DC',
        'zip'          : '500'
        'country_code' : 'US'
      },
    },
    'payment_type' : 'MT',
    'back_url'     : 'http://example.com'
  }

Android

  Sale sale = new Sale(19.99, "EUR", "Product #1");
  Address address = new Address("1600 Pennsylvania Avenue Northwest", "Washington", "DC", "500", "US");
  Customer customer = new Customer("John Doe", "john@doe.com", "127.0.0.1", address);

Simply call the bankTransferSale method. You can also check whether the sale was performed successfully, retrieve the transaction ID or error details, if anything goes wrong.

If the bankTransferSale method was performed successfully, you can redirect the customer to the bank’s website, where they’ll perform the payment. Use the URL returned by the bankTransferSale.

Example

PHP

  try {
      $status = $client->bankTransferSale($bt_params);
  }
  catch (Exception $e) {
      // handle exceptions here
  }

  if ($client->isSuccess()) {
      echo "Success, transaction initiated, id_sale: {$status['id_sale']}, \n
            redirect_url: {$status['redirect_url']} \n";
  } else {
      die("Error ID: {$status['error']['id_error']}, \n".
          "Error number: {$status['error']['error_number']}, \n".
          "Error description: {$status['error']['error_description']}");
  }

  header('Location: ' . $status['redirect_url']);
  die;

Ruby

  begin
      status = client.bank_transfer_sale(bt_params)
  rescue PeP::ClientError => e
      # handle exceptions here
  end 

  if client.success?
      puts "Success, transaction initiated, id_sale: #{status["id_sale"]}, "\
          "redirect_url: #{status["redirect_url"]}"
  else
      puts "Error ID: #{status["error"]["id_error"]}, \n"\
          "Error number: #{status["error"]["error_number"]}, \n"\
          "Error description: #{status["error"]["error_description"]}"
      exit
  end

  # redirect to url in status['redirect_url']
  exit

Python

  try:
      status = client.bank_transfer_sale(bt_params)
  except Exception, e:
      # handle exceptions here

  if client.is_success():
      print 'Success, transaction initiated, id_sale: %s, redirect_url: %s' % \
          (status['id_sale'], status['redirect_url'])
  else:
      sys.exit('Error ID: ' + str(status["error"]["id_error"]) + '\n' \
              'Error number: ' + str(status["error"]["error_number"]) + '\n' \
              'Error description: ' + str(status["error"]["error_description"])) 

  # redirect to url in status['redirect_url']
  sys.exit()

Android

  api.bankTransferSale(sale, customer, "http://example-page.com", PaymentType.MT, new Callback<PayPalAuthorizationResult>() {

      @Override
      public void onFinish(PayPalAuthorizationResult result) {
          WebView webview =...;
          webview.loadUrl(result.getRedirectUrl());
      }

      @HandleException
      public void onProtocolError(ProtocolException e) {
          // invoke if not success
          // e.getCode() - error code
          // e.getMessage() - error message
      }

      @Override
      public void onError(Exception e) {
          // connection error etc.
      }
  });

After submitting the payment on the bank’s website, the customer will be redirected back to your site (the back_url, to be precise). You should now verify the returned information to avoid any fraud attempts and check the transaction’s status.

Example code

PHP

  $salt        = 'YOUR_HASH_SALT';
  $status      = $_GET['status'];
  $description = $_GET['description'];
  $amount      = $_GET['amount'];
  $currency    = $_GET['currency'];
  $hash        = $_GET['hash'];

  $id = '';
  if ($status !== 'ERROR') // success, get id_sale
      $id = $_GET['id_sale'];

  $calc_hash = sha1("{$salt}|{$status}|{$description}|{$amount}|{$currency}|{$id}");

  // check hash salt
  if ( $calc_hash !== $hash ) {
      die ("Error, wrong hash");
  }

  // check transaction status
  switch ($status) {
      case 'ERROR':
          die("Error, transaction declined, {$_GET['error_text']}");
          break;

      case 'CLEARED':
          echo "Success, transaction completed, id_sale: {$_GET['id_sale']}";
          break;

      default:
          /* transaction pending: 
          * check status regularly using the saleStatus method 
          * or wait for notification */
          echo "Transaction pending";
          break;
  }

Ruby

  # Simple controller action code in Rails
  # it's just an example - most of the logic should be moved to model

  salt        = 'YOUR_HASH_SALT'
  status      = params['status']
  description = params['description']
  amount      = params['amount']
  currency    = params['currency']
  hash        = params['hash']

  id = ''
  unless status == 'ERROR'
      id = params['id_sale']
  else
      # redirect to an index action to correct the payment + simple notice
      # for rails: redirect_to :index, :notice => "Error, transaction declined, #{description}"
  end

  calc_hash = Digest::SHA1.hexdigest("#{salt}|#{status}|#{description}|#{amount}|#{currency}|#{id}")

  unless calc_hash == hash
      # redirect to an index action to correct the payment
      # for rails: redirect_to :index
  end

  # check transaction status

  case status
      when 'ERROR'
          # redirect to an index action to correct the payment + simple notice
          # for rails: redirect_to :index, :notice => "Error, transaction declined, #{response["error"]["error_text"]}"
      when 'CLEARED'
          # redirect to an index action to correct the payment + simple notice
          # for rails: redirect_to :index, :notice => "Success, transaction completed, id_sale: #{id}"
      else
          # redirect to an index action to correct the payment + simple notice
          # for rails: redirect_to :index, :notice => "Transaction pending"
  end

Python

  salt        = 'YOUR_HASH_SALT'
  status      = get_request_param('status')
  description = get_request_param('description')
  amount      = get_request_param('amount')
  currency    = get_request_param('currency')
  hash        = get_request_param('hash')
  id_sale     = None

  # success, get id_sale
  if status != 'ERROR':
      id_sale = get_request_param('id_sale')

  calc_hash = hashlib.sha1(
      '|'.join([salt, status, description, amount, currency, id_sale])).hexdigest()

  # check hash salt
  if calc_hash != hash:
      sys.exit('Error, wrong hash')

  # check transaction status
  if status == 'ERROR':
      sys.exit('Error, transaction declined, %s' % \
          get_request_param('error_text'))
  elif status == 'CLEARED':
      print 'Success, transaction completed, id_sale: %s' % id_sale
  else:
      # transaction pending: check status regularly using the saleStatus
      # method or wait for notification
      print 'Transaction pending'

Android

  webview.setWebViewClient(new WebViewClient() {
      @Override
      public boolean shouldOverrideUrlLoading(WebView view, String url) {

          if (url.contains(redirectUrl)) {
              try {
                  Map<String, String> map = getQueryMap(new URL(url).getQuery());
                  String salt = "YOUR_HASH_SALT";
                  String status = map.get("status");
                  String description = map.get("description");
                  String amount = map.get("amount");
                  String currency = map.get("currency");
                  String id = map.get("id_sale");

                  String calcHash = sha1(String.format("%1$s|%2$s|%3$s|%4$s|%5$s|%6$s", salt, status, description, amount, currency, id));

                  // check hash salt
                  if (!calcHash.equals(hash)) {
                      // Error, wrong hash
                  }

                  if (status.equals("ERROR")) {
                      String errorDescription=map.get("error_text");
                      // Error, transaction declined

                  } else if (status.equals("CLEARED")) {
                      String idSale=map.get("id_sale");
                      // Success, transaction completed

                  } else {
                          /* transaction pending:
                          * check status regularly using the saleStatus method
                          * or wait for notification */
                  }

              } catch (MalformedURLException e) {
                  e.printStackTrace();
              } catch (NoSuchAlgorithmException e) {
                  e.printStackTrace();
              } catch (UnsupportedEncodingException e) {
                  e.printStackTrace();
              }
          } else {
              view.loadUrl(url);
          }
          return true;
      }
  });

  public static Map<String, String> getQueryMap(String query) {
      String[] params = query.split("&");
      Map<String, String> map = new HashMap<String, String>();
      for (String param : params) {
          String name = param.split("=")[0];
          String value = param.split("=")[1];
          map.put(name, value);
      }
      return map;
  }

  private static String convertToHex(byte[] data) {
      StringBuilder buf = new StringBuilder();
      for (byte b : data) {
          int halfbyte = (b >>> 4) & 0x0F;
          int two_halfs = 0;
          do {
              buf.append((0 <= halfbyte) && (halfbyte <= 9) ? (char) ('0' + halfbyte) : (char) ('a' + (halfbyte - 10)));
              halfbyte = b & 0x0F;
          } while (two_halfs++ < 1);
      }
      return buf.toString();
  }

  public static String sha1(String text) throws NoSuchAlgorithmException, UnsupportedEncodingException {
      MessageDigest md = MessageDigest.getInstance("SHA-1");
      md.update(text.getBytes("utf-8"), 0, text.length());
      byte[] sha1hash = md.digest();
      return convertToHex(sha1hash);
  }