Payment Page API for the hosted payment page
This document describe the API to access the Payment Page V2 payment page system. The Payment Page Payment Page application permits to process payments by interacting with the end user.
By using this guide you will be able to generate an unique URL hosted by PayXpert, and redirect your end user to this URL in order to fulfill the payment.
General Information
- The Payment Page API is following the REST principles. No SOAP or RPC is used to communicate, only plain HTTP.
- Every exchanges between the merchant and the payment page are encoded in UTF-8 character set.
- For POST HTTP requests, information are transferred serialized in JSON format in the body of the request
- Merchants must have an account on the payment page to be able to use it.
Notice: The API calls are all authenticated using the standard Basic HTTP Authentication mechanism with the credentials provided at the subscription to the service.
Global Workflow
1 - The customer validates his order on the merchant website
2 - The merchant website issues an HTTP POST request to a specified URL of the payment page with the parameters of the payment
3 - The payment page returns two unique tokens to the merchant website, one for the customer access and the other for private communication between the merchant and the payment page
4 - The merchant website redirects the customer to the payment page with the unique token in parameter of the GET HTTP request
5 - The customer fills in the missing information to complete the transaction (payment mean informations) and validates the payment
6 - If enabled, the payment page submits payment information to anti-fraud system
7 - Based on anti-fraud’s score, the payment page processes the payment towards the Payment Gateway activating 3D secure or not. If no anti-fraud is enabled, 3D secure can be enabled or not in the request (or enforced by the merchant configuration).
8 - If a callbackURL parameter is present in the payment information, the payment page issues an HTTP POST request on this URL with the status of the payment in parameter
9 - The payment page displays the status of the payment to the customer with a link to go back to the merchant site, the link is in fact a form that will issue a POST request towards the redirect URL with as parameter the result of the payment encrypted with the merchant token
10 - The merchant website receives the customer return request and reacts according to the payment status
Revisions
Here is the list of the API stable revision with their dates. The API used must be set in the apiVersion field. Some fields are not available in every revisions, the revisions in which fields are available are specified for each fields.
| Revision number | Release Date | Description |
|---|---|---|
| 001 | 2011.03 | Initial API revision. Discontinued. |
| 002 | 2012.09.26 | |
| 002.01 | 2014.06.16 | Add parameters “merchantNotification”, “merchantNotificationTo”, “merchantNotificationLang”, “timeOut” and render “ctrlRedirectURL” optional. |
| 002.02 | 2016.04.28 | Add parameter “paymentMeanInfo” in transaction status. Move “cardHolderName” to this new structure. Remove request parameters “afClientId” and “afPassword”. |
| 002.03 | 2016.06.02 | Add parameters “operation”, “shopperBirthDate” and “shopperIDNumber” in transaction creation request. Add parameter “shopperBirthDate” and “shopperIDNumber” in transaction status. Fix “shopperName” length to 80 in transaction status. |
| 002.50 | 2017.05.15 | * Update API URLs * Add BankTransfer payment type * In payment prepare, change shopperID from Integer to String(32) * Add provider field in payment prepare call * In payment prepare call, paymentType is not mandatory anymore. If absent it will be inferred from payment types available for the account (Credit Card by default if available) * Add a refund call on transaction * In payment status response, add a transactions array with all transaction attempts done to process the payment * The payment status call now accepts an apiVersion parameter to force the returned wanted format * In payment status response, statementDescriptor has been moved to credit card specific payment mean information |
| 002.51 | 2018.02.05 | * Add Direct Debit payment type * Add rebill and cancel calls * Add refTransactionId field in transaction attempt object of payment status * Add provider field in transaction attempt object of payment status * Add operation field in transaction rebill, refund, cancel responses * Add Chargeback and Reversal transactions in Direct Debit status |
| 002.60 | 2018.10.31 | * Add a new Transaction information API call * Add a new API Account Information API call * Add a new direct WeChat payment processing call * Rename paymentType to paymentMethod and provider to paymentNetwork * Add new EPS, POLi and DragonPay bank transfer networks * Add providerTransactionID field in transaction information |
| 002.61 | 2019.10.30 | * Added new Export Transactions List API call * Added the parameter openID to the direct WeChat process * Added the fields orderID and orderDescription to Transaction Attempt |
| 002.62 | 2021.01.08 | * Added orderID in rebill call * Send back test flag in API response |
| 002.70 | 2021.02.15 | * API refactoring for SCA support * Added new parameters totalFee and exchangeRate in Wechat and Alipay payment mean information |
| 002.71 | 2022.08.30 | * Add new card token field |
| 002.72 | 2024.02.05 | * Add new fields sdkOsType and sdkRedirectUrl for Alipay direct payment in SDK mode. * Add new field merchantIdentifier in order object for prepare call. |