CardPay API Reference

CardPay API Reference Version: 2.56 Date: 29.11.2016 Table of Contents Table of Contents Introduction Environments Sandbox Environment Production E...
Author: Beverly Lewis
1 downloads 1 Views 284KB Size
CardPay API Reference

Version: 2.56 Date: 29.11.2016

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.

Callback See section Callbacks.

CardPay API Reference v.2.57 | 05.12.2016

Page 17 of 41

Calculating Digest