1. Home
  2. Payment Gateway Server API

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: .

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:
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?