Table of Contents Table of Contents Introduction Environments Sandbox Environment Production Environment
API Entry Points Payment API Access Modes: Payment Page And Gateway
Payment Page Mode Overview CardPay API Endpoint
HTML Form XML Request Order Element Structure Shipping Element Structure Item Element Structure Recurring Card Token
Response Callback
Gateway Mode Overview
2 4 4 4 4
5 5
6 6 6
6 7 7 8 9 10 10
10 10
11 11
CardPay API Endpoint Workflow
11 11
Request Parameters XML Request
12 12
Order Element Structure Card Element Structure Billing Element Structure Shipping Element Structure Item Element Structure Recurring Card Token
13 14 14 15 16 16 16
HTTP Response Callback
17 17
Calculating Digest Return URLs
18 19
Example URL Selection URL Placeholders
19 19 19
Payment Result XML Status Codes Decline Codes
Callbacks Order Services Change Order Status Table of Contents | 05.12.2016
20 22 23
24 26 26 Page 2 of 41
Authentication HTTP Request
26 26
Service Endpoint
26
XML Response
27
Order Element Structure
REST API API Endpoints Authentication JSON Document Format Errors Processing Errors Error Objects
28
29 29 29 29 30 30 31
Payments
32
Operation
32
Request Response
32 32
Operation
33
Refunds
35
Operation
35
Request Response
35 35
Operation
36
Common Objects Order Report Request Attributes Order Report Response Object Order Status Object Order States
Changelog
Table of Contents | 05.12.2016
37 37 37 38 39
40
Page 3 of 41
Introduction Welcome to the CardPay API. You use our APIs to receive payments and check payment status. For recent changes please see the changelog.
Environments There are two environments available for integration: 1. Sandbox environment: https://sandbox.cardpay.com 2. Production environment: https://cardpay.com
Sandbox Environment Sandbox provides full functionality but it only emulates processing, no actual bank transactions are made. It supports the following card PANs: 4000000000000002: CONFIRMED as 3-D Secure transaction 5555555555554444: DECLINED as 3-D Secure transaction 4000000000000044: PENDING as 3-D Secure transaction 4000000000000077: CONFIRMED as non 3-D Secure transaction 5555555555554477: DECLINED as non 3-D Secure transaction 4000000000000051: PENDING as non 3-D Secure transaction You can use any cardholder name, expiry date and CVV2/CVC2 with these PANs. 3-D Secure is also emulated with a page that doesn’t require any password but only shows you 2 buttons. One button is for successful authentication, another is for failed authentication. Note, that when you chose to fail authentication, order is always declined, no matter what PAN was used.
Don’t use real cards on Sandbox environment.
To request any changes in settings of Sandbox environment you can directly contact our support via email or Skype.
Production Environment Once you complete integration with Sandbox environment you will be provided with Production credentials. These are completely different Merchant and User accounts, not related with the ones on Sandbox.
If same user has accounts both on Sandbox and Production, please set different passwords on
different environments.
Production always makes real bank transactions, cards from Sandbox are not supported on this CardPay API Reference v.2.57 | 05.12.2016
Page 4 of 41
environment. To request any changes in settings of Production environment you need to contact CardPay manager.
API Entry Points There are three merchant APIs: 1. First one is the Payment API which provides complete server-to-server operations. It is used for sending new orders to the system. It provides a Payment Page Mode. When customer enters card detail on a form located on CardPay payment page or customer enters card details on merchant’s site (Gateway Mode). 2. Second API is the Service API. It has additional methods to provide information about payments and to change payment status. 3. Third one is REST API that is still in development and supports only limited number of operations but is intended to replace the first two. All APIs are available via HTTP protocol using HTTP POST or HTTP GET methods.
Note that according to HTTP standards all parameter values must be URLEncoded before
sending and URLDecoded after receiving to escape special characters like ’ +, /, &, = ’ used in URLs to separate words, folders and parameters. When API is used for server-to-server communications the reply is printed inside of response body as text as an XML without any encoding.
Payment API Access Modes: Payment Page And Gateway Depending on account settings Payment API can work in 2 different ways: as a Payment Page or as a Gateway.
CardPay API Reference v.2.57 | 05.12.2016
Page 5 of 41
Payment Page Mode Overview Payment Page Mode is used when Merchant chooses to use our payment page. Customer is redirected from merchant’s website to our payment page to enter card details. Customer data entered on our payment page is protected and managed by CardPay and certified to and complies with PCI DSS standard. All customer data is sent via secure connection.
CardPay API Endpoint Test URL: https://sandbox.cardpay.com/MI/cardpayment.html Live URL: https://cardpay.com/MI/cardpayment.html
HTML Form Example HTML Form
In Gateway Mode the Merchant receives XML response containing URL a Customer should be redirected to. Customer may open this URL via either GET or POST method. The response is in XML format containing one
redirect
tag with one
url
attribute:
After Payment is completed, Customer is redirected to Return URL.