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 |