NAV
http php java

Checkout Page

Overview

Checkout page is used when Merchant provides customer with choice of available payment methods. Customer is redirected from Merchant’s website to our checkout page and may select desired payment method.

Cardpay API Endpoint

POST & GET methods can be used, all data must be sent in a request’s body.

HTML Form

Example HTML Form

<!DOCTYPE html>
<html>
    <body>
        <form action="https://cardpay.com/MI/checkout.html" method="POST">
            <input type="hidden" name="orderXML" VALUE="PG9yZGVyIHdhbGxldF9pZD0iMjEiIG51bWJlcj0iNDU4MjEwIiBkZXNjcmlwdGlvbj0iQmVzdCBldmVyIHNlZW4gVC1TaGlydHMsIDExMDIxIiBjdXJyZW5jeT0iVVNEIiBhbW91bnQ9IjI5MS44NiIgZW1haWw9ImN1c3RvbWVyQGV4YW1wbGUuY29tIi8+"/>
            <input type="hidden" name="sha512" VALUE="b258f153463c8787535a6e90836a4927b2ccddb5af64999ff4b530d74fff2a34959ff77d0b003004d0f9f6d923702c78b579187287809f820c8e77e0be5c9254"/>           
        </form>
    </body>
</html>

To use API of checkout page customer must be provided with HTML Form with filled hidden input fields. This Form is posted to the API URL by pressing “Pay” button.

There are only 2 parameters of request: orderXML and sha512.

XML Request

XML Request Example

<order wallet_id="21" number="458210" description="Best ever seen T-Shirts" amount="291.86" currency="USD" email="[email protected]"></order>

Elements and attributes are case in-sensitive. Single quotes may be used instead of double quotes.

Elements in bold are mandatory. Attributes in bold are mandatory only if Element is present, default value is shown after equals sign.

Following data types are used:

Element Attribute Type Description
order wallet_id String Unique merchant’s ID used by the CardPay payment system.
number String(50) Order ID used by the merchant’s shopping cart.
description String(200) Description of product/service being sold.
amount Decimal The total checkout amount in selected currency with dot as a decimal separator, must be less than 100 millions.
currency String(3) ISO 4217 currency code
email String(256) Customer’s e-mail address
customer_id String(256) Customer’s ID in the merchant’s system.
authentication_request=false Boolean If set to “true”, amount must not be present in request, no payment will be made, only cardholder authentication will be performed. Also can be used to generate Card Token. The default value is “false”.
locale=en String(2) Preferred locale for the payment page (ISO 639-1 language code). “=en” stands for the default value. Also the default locale (en) will be applied if the selected locale is not supported. Supported locales are: az ar, hy, bg, cs, el, en, es, id, ja, ka, hu, ms, pt, ro, ru, sr, tr, th, uk, vi, zh.
note String(100) Note about the order that will not be displayed to customer.
return_url String Overrides default success URL, decline URL and cancel URL.
success_url String Overrides default success URL only. See section Return URLs.
decline_url String Overrides default decline URL only. See section Return URLs.
inprocess_url String Overrides default In process URL only. See section Return URLs.
cancel_url String Overrides default cancel URL only. See section Return URLs.
order/shipping List of shipping element Represents an address where the order will be delivered to. See shipping element structure below
order/items List of item element List of order positions (items in the shopping cart). See item element structure below
order/flights List of flight element List of flights and passenger information for airlines. See flight element structure below

Shipping Element Structure

SHIPPING is the address where the order will be delivered. It is used in Anti-fraud System and also can be seen in Payment Manager. But it may be omitted and all the fields of it except country may be omitted too.

Element Attribute Type Description
shipping country String(3) ISO 3166-1 code of delivery country: 2 or 3 latin letters or numeric code
state String(20) Delivery state or province. May include whitespaces, hyphens, apostrophes, commas and dots
zip String(12) Delivery postal code
city String(20) Delivery city. May include whitespaces, hyphens, apostrophes, commas and dots
street String(2-100) Delivery street address. May include whitespaces, hyphens, apostrophes, commas, quotes, dots, slashes and semicolons
phone String(5-20) Valid customer phone number

Item Element Structure

Item element represents individual order item or service.

Element Attribute Type Description
item name String(50) The name of product / service, provided to the customer
description String(200) The description of product / service, provided to the customer
count Numeric The count of product / service, provided to the customer. Any positive number
price Decimal Price of product / service with dot as a decimal separator, must be less than 100 millions

Flights Element Structure

Flights element represents common airlines information for the whole travel like passenger name or travel agency. Each flight element represents a separate flight. Since flights order matters it is recommended to additionally control it by adding index attribute to each flight element.

Element Attribute Type Description
flights passenger_name String(20) The name of the passenger using only latin alphabet
origination_code String(3) Airport of origination code
departure_date String(10) Departure date in DD.MM.YYYY format
travel_agency_code String(8) Travel agency code
travel_agency_name String(25) Travel agency name using only latin alphabet
computerized_res_system String(4) Computerized reservation system code
credit_reason_indicator String(1) Credit reason indicator
ticket_change_indicator String(1) Ticket change indicator
is_restricted Boolean Restricted ticket indicator
flights/flight index Numeric Sequence number of a flight
number String(5) Flight number
carrier_code String(2) Carrier code
destination_code String(3) Airport of destination code
service_class_code String(1) Service class code
fare_basis_code String(6) Fare basis code
stop_over_code String(1) Stop over code

Calculating Digest

Digest is used for authentication and protecting the message from changes. It is calculated from the orderXML and the Secret Word you received with your Wallet ID.

For example if you have following access parameters:

And you are sending the following order:

<order wallet_id="21" number="458210" description="Best ever seen T-Shirts" currency="USD" amount="291.86" email="[email protected]"/>

Then you’ll need to calculate SHA-512 digest of the following string:

"<order wallet_id="21" number="458210" description="Best ever seen T-Shirts" currency="USD" amount="291.86" email="[email protected]"/>se1cr2et3w0r4d"

That will result in the following: 8877da7b52eea2266d9b4f2c7dd4630dd3ea6d1e066a3f2f0921b5163196095a3a7028ba5cf80671471f313719325de1c694f3a9927eaa7cc6370e6ddbe82d3d

And these will be the parameters to be sent to API:

Response

After request is completed, the Customer is directed to Return URLs.

Return URLs

Return URLs are the URLs where customer returns after checkout page request or by pressing “Back to the shop” / “Cancel” button.

URL Selection

There can be 3 different URLs:

By default they all point to the Shop’s home page. The default URLs can be changed only by CardPay manager, but they can be sent with each request

Changelog

2018-11-15 - 2.62

http php java