WebPay Form integration manual


Version 1.2.5.

Content

Requirements

Integration must be done within our test environment first. When this process is finished and approved by our staff, you may go live and start processing with real money.

To start integrating with WebPay Form service you will need the following:

If you don't have a test merchant account, please contact us at [email protected] and we will open one for you. Then you can login into your account at https://ipg.pikpay.ba/hr/login with login and password provided.

Payment form

WebPay Form is a simple web service; merchant should collect data consisted of buyer's profile and order info at his site and submit that data to https://ipg.pikpay.ba/form using HTTP POST method.

important Parametrize https://ipg.pikpay.ba URL, in production mode the subdomain will be different.

After a valid request is made to WebPay service, a payment form is presented to the buyer. Buyer now fills in the card details and submits the form. Service issues a request for authorization to acquirer bank and redisplay the form if authorization is declined. If authorization is approved, a redirect is made back to a merchant site.

notice Buyer stays at our side if transaction is declined, form is redisplayed with appropriate message and buyer can retry the authorization process. There is no means to comunicate the failure of transaction to merchant at this point. To control the whole process we recommend a WebPay Direct method for integration. Merchant can then capture a failed transaction also if using WebPay Direct.

Optionally, a email messages are sent to merchant and/or buyer to notify both sides of successful purchase. This setting is available under merchant account together with custom email templates for outgoing email messages.

Transactions types

Authorization

Authorization is preferred transaction type for e-commerce. Merchant must capture these transactions within 28 days, in order to transfer the money from buyer's account to his own. This transaction can also be voided if a buyer cancels the order. Refund can be done after original authorization is captured.

Purchase

Purchase doesn't need to be approved; funds are transfered in next settlement between issuer and acquirer banks, usually within one business day. These transactions can be refunded within 180 days.

Capture

Approved authorization must be captured for the funds to be transfered form buyer's card to merchant account. This action can be done through merchant account interface or programatically through an API call. A lesser amount than an original authorization amount can be captured as well, ie. a merchant can make partial delivery of goods and/or services. Capture must be done within 28 days or it will be automatically voided.

Refund

Approved purchases and captures can be refunded within 180 days. This action can be done through merchant account interface or programatically through an API call. This is required if a merchant cancels the order after transaction is settled, or a buyer is not satisfied with delivered goods and/or services. Refunds can be done with a lesser amount than an original authorization amount.

Void

Approved authorization must be voided within 28 days if merchant cancels the order. This action can be done through merchant account interface or programatically through an API call.

API settings

API settings can be found under your merchant account. These information is necessary for service to work properly. API settings values reflect a configuration at the merchant site:

important Parametrize this values for API settings, we strongly advice a merchant to have both, testing and production environments.

Return values

Redirect to success URL is made after transaction is approved and if redirect flag is set in API settings. Data for this transaction is returned back to merchant site in this step. Following variables are set in redirect GET request to success URL:

In case transaction amount is changed due to rebate applicaton following additional variables are set:

This request may look like this:

http://merchant.com/success_url?approval_code=24498&cc_type=amex&digest=53ccc93b43b5b4bd0f5a27878f0572e1493d757a&language=en&order_number=15113&response_code=000&currency=USD
    

Returned digest is calculated as SHA1(key + order_number). You must check for this value at merchant application before updating status of transaction because malicious user can forge this URL.

Any custom variables sent in custom_params are also returned appended to that success URL.

important Success URL should expire after some sensible amount of time or protected using session.

Pretty URLs

If you would like to use returned values as URL tokens, the following syntax for success and cancel URLs will interpolate those values into URL itself:

http://merchant.com/:language/success

where :language will be replaced with apropriate value.

Email notifications

Service can notify merchant and buyer upon successful purchase. Merchant can use this message to track pending transactions and buyer can keep them as reference. Both can be customized under your merchant account.

The following variables are interpolated into body of each email template:

Email template to notify the buyer may look like this:

Thank you for your business!

Credit Card Owner:
------------------
name: FULL_NAME
address: ADDRESS, CITY, ZIP, COUNTRY
phone: PHONE
email: EMAIL

Order Details:
------------------
order amount: AMOUNT
order number: ORDER_NUMBER
order description: ORDER_INFO
payment type: CC_TYPE
date: DATE
order url: SUCCESS_URL

Please come again!
Store adress: DOMAIN
    

notice SUCCESS_URL has the same value as URL generated for redirect to success URL after transaction is approved. It should expire after some sensible amount of time or protected using session.

Variables - names, lenghts and formats

Here are the definitions of variables which are submitted to WebPay form:

Buyer's profile

namelenghtformatadditional info
ch_full_name3-30alphanumericbuyer's full name
ch_address3-100alphanumericbuyer's address
ch_city3-30alphanumericbuyer's city
ch_zip3-9alphanumericbuyer's zip
ch_country3-30alphanumericbuyer's country
ch_phone3-30alphanumericbuyer's phone
ch_email3-100alphanumericbuyer's email

Order details

namelenghtformatadditional info
order_info3-100alphanumericshort description of order being processed
order_number1-40alphanumericunique identifier
amount3-11integeramount is in minor units, ie. 10.24 USD is send as 1024
currencypredefinedalphapossible values are USD, EUR, BAM or HRK
original_amount3-11integeramount is in minor units, ie. 10.24 USD is send as 1024

Processing data

namelenghtformatadditional info
languagepredefinedalphaused for form localization, possible values are en, es, ba or hr
transaction_typepredefinedalphapossible values are authorize or purchase
authenticity_token40alphanumericautogenerated value for merchant account, can be found under merchant settings
digest40alphanumericSHA1 hash generated from concatenation of key, order_number, amount and currency as strings; key can be found under merchant settings
number_of_installments1-2integersome card BINs can have installments enabled, depending on your bank account and country; range 2-12
cc_type_for_installmentspredefinedalphaused with installments - this card type will be preselected on payment form; possible values are master, visa, amex or diners
force_cc_typepredefinedalphathis card type will be preselected on payment form; possible values are master, maestro, visa, amex or diners
motopredefinedalphapossible value is true or false; missing variable is equivalent to false
rebate_digest40alphanumericSHA1 hash generated from concatenation of key, order_number, original_amount, amount and currency as strings; key can be found under merchant settings

Custom variables

Merchant can also send custom variables if needed. They will be passed back in redirect after approved authorization. Just pack all the data you wish to send in JSON format and submit that under custom_params variable.

Calculating digest

Digest is calculated using following formula:

digest = SHA1(key + order_number + amount + currency)

With the following example data

the digest formula gives a result as follows:

digest = SHA1("qwert123abcdef54321EUR") = "16e943d2b84546ce4271de51679abc3bf1eb163b"

Transacton management through API

WebPay API for capture/refund/void is a REST web service and you will need a HTTP client library (like cURL - http://curl.haxx.se). All API calls are XML documents POST-ed over HTTPS to our test server at https://ipg.pikpay.ba.

important Parametrize https://ipg.pikpay.ba URL, in production mode the subdomain will be different.

An example of such call using cURL from command line may look like this:

curl -H "Content-Type: application/xml" -H "Accept: application/xml" -k -i -d request_xml https://ipg.pikpay.ba/action
    

where request_xml is a XML document that contains data necessary for transaction processing and https://ipg.pikpay.ba/action is an URL that responds to certain API call.

important Accept and Content-Type headers must be set to application/xml for all message types.

Capture

After an authorization is successfully made, a capture call must be done to settle that authorization.

Capture XML document is POST-ed to https://ipg.pikpay.ba/transactions/:order_number/capture.xml, where :order_number has a value from original authorization.

Document example for capture message may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
  <amount>54321</amount>
  <currency>EUR</currency>
  <digest>e64d4cd99367f0254ed5296d38fad6ce87d3acab</digest>
  <authenticity-token>7db11ea5d4a1af32421b564c79b946d1ead3daf0</authenticity-token>
  <order-number>11qqaazz</order-number>
</transaction>

where digest is calculated the same way as for authorize or purchase messages.

notice Node names are dasherized version of corresponding variable names, ie. underscores are replaced with dashes.

If all values pass validations at our side, transaction is send to the bank and response is returned. That response may look like this:

  • HTTP status code: 201 - Created
  • HTTP headers: {:connection=>"close", :date=>"Tue, 25 Oct 2011 01:18:37 GMT", :location=>"https://ipg.pikpay.ba/transactions/845", :content_type=>"application/xml; charset=utf-8", :cache_control=>"no-cache", :x_ua_compatible=>"IE=Edge", :x_runtime=>"1.475305", :transfer_encoding=>"chunked"}
  • HTTP body:
    <?xml version="1.0" encoding="UTF-8"?>
    <transaction>
      <id type="integer">845</id>
      <acquirer>rogach bank</acquirer>
      <order-number>abcdef</order-number>
      <amount type="integer">54321</amount>
      <response-code>000</response-code>
      <approval-code>38860</approval-code>
      <response-message>authorization OK</response-message>
      <reference-number>898951263</reference-number>
      <systan>83704</systan>
      <cc-type>visa</cc-type>
      <status>approved</status>
      <transaction-type>authorize</transaction-type>
      <created-at type="datetime">2011-10-25T03:18:38+02:00</created-at>
    </transaction>

New transaction is generated - 201 Created HTTP status code, and it's location is set in appropriate HTTP header. A client then must parse a body from HTTP response and extract all values from that XML document. Transaction is approved only and if only status is set to approved. All other fields are standard data carried over payment networks. If issuer declines a transaction, status flag is set to decline. In a case of an error, the flag will be set to invalid.

important Do not rely on any output variable except status to determine successful of autorization.

notice We highly recommend to our merchants to keep a whole response string and to save all parsed values for easier troubleshooting during the integration phase and production later on. The quality of our support depends on availability of these information.

In case of invalid request, service will also return a response with 406 Not Acceptable HTTP status code and XML document in it's body. Each ofended variable will be printed out along with brief explanation what went wrong. That response may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Digest is invalid</error>
</errors>

Refund

Purchase and capture messages can be refunded within 180 days. Request XML for this transaction_type is identical to capture example, but now the document is POST-ed to https://ipg.pikpay.ba/transactions/:order_number/refund.xml, where :order_number has a value from original purchase or capture.

Response has identical structure as capture response and all response fields should be treated in the same way.

Void

Void messages are POST-ed to to https://ipg.pikpay.ba/transactions/:order_number/void.xml, where :order_number has a value from original message (authorization, capture, purchase or refund). They have identical structure as capture or refund messages.

Response has identical structure as capture response and all response fields should be treated in the same way.

Transactions with installments

To send a request with installments, number_of_installments is submitted for authorization or purchase requests. This number depends on merchant's setting in acquiring bank, it's value is a number between 2 and 12.

3-D Secure

WebPay handles 3-D secure processing for you, this kind of integration doesn't require any additional programming.

Demo client

For easier integration we provided a demo client. Turn on the debug mode in API settings under your merchant account to activate the client. A link to client is available upon activation. Append /success and /cancel to that link and set them as success and cancel URLs if you want to see how those pages could look like.

Look & feel

It is possible to customize the form using CSS and HTML code. That code can be entered under Look & feel settings of your merchant account. The form has semantic markup for easier CSS overrides. Also, header and footer HTML code is injected into document body removing original content.

notice Some page elements that are required by card associations can't be removed using CSS. Before going live, our staff will check if the form meets this rules.

List of response codes

Here is the list of response codes and their description:

ipg.pikpay.ba