Payment Gateway Server API

Introduction

This document describes the Server to Server API which enables merchants and PSP to integrate Payxpert payment solution. Prior to use you should have submitted an application and supporting documents to receive an originator ID and a password. All examples are using a generic originatorId and password that must be change prior to their execution.

Using the Server to Server API, the merchant transmits all the informations required to make the payment directly to PayXpert system via an HTTP request. The merchant is responsible for collecting and storing sensitive payment details of his customers. He must ensure the confidentiality and security of those details.

A separate account permits to access the backoffice where summary statistics, individual transactions details are available. Operation can also be manually done on transactions (like refunds, rebill…). The backoffice is available at: https://central.payxpert.com/

For integration questions please email: support@payxpert.com.

Revisions

API revisions

Revision	Date	Description
0200	2011-07-19	Draft
0202	2012-08-27	Stable
0203	2015-01-21	Stable
0204	2015-11-18	Stable
0205	2016-04-12	Stable
0206	2016-05-31	Stable
0207	2016-08-22	Stable

Document revisions

This table outlines the last API document revisions.

Revision	Date	Engineer	QA Engineer	Description
r01	2011-07-19	RV	JS	Draft
r02	2012-08-27	JS	RV	Proof reading. Adapt to the last 0202 revision.
r03	2012-10-29	RV	JS	Extend cardHolderName, shopperName and shipToName to 80 chars
r04	2013-01-22	RV	JS	Add orderDescription in exported transaction field
r05	2013-01-28	RV	JS	Fix productID field type
r06	2013-02-05	RV	JS	Add support for CAVVAlgorithm in 3D secure
r07	2014-05-13	RV	JS	Update test cards
r08	2014-10-20	RV	JS	Add support for subscriptions in CCAuthorize. Add new IPSP parameters
r09	2014-11-06	RV	JS	Allow rebill on CCAuthorize as referral. Add new error codes
r10	2014-11-28	RV	JS	Add new IPSP parameters
r11	2015-01-21	RV	JS	Add a new Export subscriptions parameter
r12	2015-05-27	RV	JS	Add optional CVV on S3DCheck
r13	2015-09-03	RV	JS	Add optional statementDescriptor on Rebill
r14	2015-11-18	JS	RV	Add optional cancelSubscription on Refund calls
r15	2016-01-05	JS	RV	Update expiration year on AVS Check test cards
r16	2016-04-12	JS	RV	Add conditional paymentMeanInformation on CCAuthorize and CCSale results and in transactions/subscriptions export
r17	2016-06-03	JS	RV	Add “charge card” and “virtual” in payment mean info cardSubType field values
r18	2016-07-20	AC	RV	Add shopperBirthDate and shopperIDNumber on CCAuthorize and CCSale request
r19	2016-08-22	JS	RV	Add PaRes parameter on CCAuthorize and CCSale request

Types

Naming convention

The API uses the camelCase naming convention for parameter names as in cardSecurityCode.
Acronyms and initials such as IP or ID remain in upper case as in customerIP, AVSPolicy or CAVV.

Data types

The parameters in both the requests and the responses have a type that must be respected. This changes their final representation in the JSON format: strings are quoted, numerics are not, objects are enclosed in {}…
See RFC 4627 for the details of the JSON format.

Field type	Description	Notes
D	Numeric string	A string containing only numbers in it, ie: “02”, “00111”, “232432”, “34234323000”
AN	Alphanumeric string	A string consisting of letters (a to z and A to Z), digits (0 to 9) or the characters “-“, “_” and ” “.
S	String	A string consisting of every possible characters.
B	Boolean	A boolean value either true or false (without quotes)
N	Numeric	A true numeric value. Represented in JSON as a numeric (without quotes).
C	Constant strings defined by the system or ISO or National standards
E	Email format	ie: jsmith@example.com
DT	Date format	UTC Unix Timestamp (seconds since 1970)
IP	IP v4 format x.x.x.x	ie: 192.168.1.1
O	Object	Can be a transaction, a subscription…
L	List	Array of entities.

Requirement Types

Requirement	Meaning	Description
M	Mandatory	These fields must be set in requests, and will always have a value in responses
O	Optional	These fields don’t need to be set and can take the NULL value in response (note that in that case the field still will be present)
C	Conditional	These fields can be present or absent according to the merchant settings/options
R	Required conditionally	depends on the merchant account settings and the bank processor

Data character encoding

Every data transmitted and received is encoded in UTF-8 character set.

Authentication

The authentication during the API calls is using the standard HTTP basic authentication.
The user and password to use are the originator ID and password provided at subscription.

Data Transmission Format

Requests

Requests towards the payment gateway consists in standard HTTP method with parameters.

In case of POST requests, the parameters must be transmitted in the body of the request as a JSON structure.
In case of GET requests, the parameters are transmitted as standard parameters in the URL.

Responses

Every responses from the payment gateway consist in a JSON structure in the body of the response.

This is a sample of the output you will get in when calling a CCSale function:

{"transactionID":512345,"errorCode":"000","errorMessage":"Transaction successfully completed","statementDescriptor":"payxpert.net"}

API call summary

The Payment Gateway API is based on the REST principle. In short the calls are manipulating (fetching, creating, deleting…) resources identified by URIs by applying a method (standard HTTP methods).

This page is a summary of all the API calls available. They will all be detailed along with their parameters in the following sections.

Environment	Base Url
Production	https://api.payxpert.com/

Type	Url	Method	Version
CCSale	/transaction/sale/creditcard	POST	>= 0200
CCAuthorize	/transaction/authorize/creditcard	POST	>= 0200
ToditoSale	/transaction/sale/todito	POST	>= 0200
3DSCheck	/transaction/3dscheck/creditcard	POST	>= 0200
3DSParse	/transaction/{transactionID}/3dsparse	POST	>= 0200
Refund	/transaction/{transactionID}/refund	POST	>= 0200
Credit	/transaction/{transactionID}/credit	POST	>= 0200
Capture	/transaction/{transactionID}/capture	POST	>= 0200
Cancel	/transaction/{transactionID}/cancel	POST	>= 0200
Rebill	/transaction/{transactionID}/rebill	POST	>= 0200
CancelSubscription	/subscription/{subscriptionID}/cancel	POST	>= 0200
InstantConversion	/subscription/{subscriptionID}/instantconversion	POST	>= 0200
StatusTransaction	/transaction/{transactionID}	GET	>= 0200
StatusSubscription	/subscription/{subscriptionID}	GET	>= 0200
BlacklistTransaction	/transaction/{transactionID}/blacklist	POST	>= 0200
BlacklistValue	/blacklist	POST	>= 0200
ExportTransaction	/transactions(/{transactionOperation})	GET	>= 0200
ExportSubscription	/subscriptions	GET	>= 0200
ExportSubscriptionOffer	/subscription/offer/{offerID}	GET	>= 0202

The strings in the URL between {} are dynamic parameters that must be replaced by the corresponding references (for example the transaction ID on which the call will act on).
The strings in the URL between () are optional parameters.

Common Data Structures

The API is manipulating JSON data structures. Some are specifics to a particular API call, others are present in several calls.
These common data structures are described in this section and referenced when necessary from the other sections.

Transaction

This is a JSON object with the following fields:

Field	Type	Requirement	Description
transactionID	N	M	Unique identifier of that transaction.
orderID	S	O	orderID of this transaction or of the referral transaction, if set
referralID	N	O	Optional unique identifier of the transaction that this transaction refers to.
subscriptionID	N	O	Optional unique identifier of the subscription this transaction belongs to.
status	AN	M	Textual status of the transaction Authorized or Not authorized.
errorCode	D	M	Result code of the transaction.
operation	AN	M	Can be sale, refund, credit, authorize, capture, cancel, rebill
paymentType	AN	M	Type of payment of the transaction. Can be creditcard, toditocash
paymentMeanInfo	O	C	Details on the payment mean. Will vary according to the PaymentType. See below for a description of the structure.
date	DT	M	UTC Unix timestamp representing the date of the transaction processing.
shopperName	S	M	Name of the shopper.
shopperEmail	E	M	Email address of the shopper.
customerIP	IP	M	IP address of the shopper.
amount	N	M	Amount of the transaction in cents.
currency	C	M	3 letters currency code according to ISO 4217 (EUR, USD, GBP…).
orderDescription	S	O	Order description

Payment Mean Info

Payment Mean Information is a JSON object that varies according to the payment type.

Credit Card

Field	Type	Requirement	Description
cardNumber	C	M	The card number (truncated)
cardExpireYear	C	M	Expiration year of the card
cardExpireMonth	C	M	Expiration month of the card
cardHolderName	C	M	Name of the card holder
cardBrand	C	O	Brand of the card, see below for possible values
cardLevel	C	O	Level of the card, see below for possible values
cardSubType	C	O	Sub type of the card, see below for possible values
iinCountry	C	O	ISO2 country code of the issuer of the card
iinBankName	C	O	Card Issuer Bank Name
is3DSecure	B	O	The liability shift for 3D Secure. Can be true or false

Card brands

Card brand field can take the following values:

Value	Description
VISA	Visa card
MCRD	Mastercard card
MAES	Maestro card
NACA	National card
AMEX	American Express card
CUP	China Union Pay card
DINE	Diners Club card
DISC	Discover card
JCBC	JCB Card
AURA	Aura card
ELO	Elo card
HIPE	Hipercard
LASER	Laser card
SOLO	Solo card
NA	Card brand unavailable

Card Level

Card level field can take the following values:

Value
atm
business
classic
electron
gift
gold
other
platinum
premier
premium
prepaid
private
virtual

Card Sub Type

Card subtype field can take the following values:

Value
credit
debit
charge card
virtual

Subscription

This is a JSON object with the following fields:

Field	Type	Requirement	Description
subscriptionID	N	M	Unique identifier of that subscription.
subscriptionType	C	M	Type of subscription: normal, lifetime, onetime, infinite.
offerID	N	O	Optional identifier of the offer this subscription is based on.
transactionID	N	M	Unique identifier of the original Sale transaction that triggered the subscription.
amount	N	M	Amount of the subscription in cents.
period	AN	M	Period between iterations of the subscription according to ISO 8601.
trialAmount	N	O	Amount for the trial period in cents.
trialPeriod	AN	O	Duration of the trial period of the subscription according to ISO 8601
state	C	M	Current state of the subscription: trial, active, retry, unpaid, finished, disabled or canceled
subscriptionStart	DT	M	date of the first operation
periodStart	DT	O	Start date of the current iteration period
periodEnd	DT	O	End date of the current iteration period
cancelDate	DT	O	Termination date for expired subscriptions (unpaid, finished, disabled or canceled)
cancelReason	D	O	Code of the reason of the termination if in state canceled or disabled.
iterations	N	M	Current number of successful automatic iterations.
iterationsLeft	N	M	Number of iterations left. -1 if no limit.
retries	N	O	Number of failed attempts for the current iteration when in states retry or unpaid

Was this article helpful?

Yes No