PM Query
1. Introduction
PM Query is a feature that allows a merchant to retrieve the payment conditions for a specific Payment Method (e.g. expenses, rate, amounts and dates of upcoming payments, etc.) prior to the payment, in order to show this information to the customer before he confirms his order.
This guide is a supplement and should be read alongside e-Commerce.
2. Implementation
The information is gathered via an https request to the following page, using a form containing input parameters: https://viveum.v-psp.com/ncol/test/queryPM.asp
Note: Replace 'test' by 'prod' when you want to switch from test to our production environment.
2.1 Input Parameters
| Name (* if mandatory) | Description |
|---|---|
| USERID* | User ID used to perform the query. |
| REFID | Only if PSPID is part of a group |
| REFKIND | If using REFID, specify the type: PSPID, MGID, (none) |
| PSWD* | User or PSPID Password |
| PSPID* | Unique identifier on our system |
| ORDERID* | Merchant's unique order reference |
| AMOUNT* | Amount of the transaction x100 |
| CURRENCY* | ISO 3-letter code (EUR, USD, CHF, etc.) |
| LANGUAGE* | 2-digit language code (fr, en, etc.) |
| PM* | Payment method ('3XCB') |
| OPERATION* | "VEN" or "RES" according to PM configuration |
| CIVILITY* | Civility of the buyer (Mr, Mme, etc.) |
| ECOM_BILLTO_POSTAL_NAME_FIRST* | Customer's first name |
| ECOM_BILLTO_POSTAL_NAME_LAST* | Customer's last name |
| SHASIGN* | SHA Signature (see next chapter) |
| WITHROOT | defines whether the XML response should be encapsulated in one global root element |
More information about these fields can be found in your account. Just log in and go to: "Support > Integration & user manuals > Technical guides > Parameter Cookbook".
In order to verify the integrity of the submitted data, our system requires each request to include a SHA signature. This signature is built by hashing the contents of the request, in the 'parameter=value' format in alphabetical order.
For more information on SHA, go to e-Commerce.
2.2 Output Parameters
The following information is included with each Query PM Response:
| Field | Description |
|---|---|
| NCERROR | Error code (0 if all OK) |
| NCERRORPLUS | Detailed error code (0 if all OK) |
| ORDERID | Merchant order reference |
| AMOUNT | Amount of the transaction |
| CURRENCY | Currency |
| OPERATION | Operation (VEN or RES) |
| PM | Payment Method |
| AMOUNT1 | First amount to be paid |
| AMOUNT2 | Second amount to be paid |
| AMOUNT3 | Third amount to be paid |
| EXECUTIONDATE1 | Date of the first payment |
| EXECUTIONDATE2 | Date of the second payment |
| EXECUTIONDATE3 | Date of the third payment |
| APR | Annual Percentage Rate. Also known as TAEG (Taux Annuel Effectif Global) |
| COST | Additional cost for the transaction |
| CONTRACT | base64 encoded contract text (in html format) |
| VERSION | Version of the terms and conditions |
More information about these fields can be found in your account. Just log in and go to: "Support > Integration & user manuals > Technical guides > Parameter Cookbook".
Example:
<?xml version="1.0" ?>
<ncresponse
NCERROR="0"
NCERRORPLUS=""
orderID="GHJ21233"
AMOUNT="90"
CURRENCY="EUR"
OPERATION="VEN"
PM="3XCB"
AMOUNT1="31.08"
AMOUNT2="30.00"
AMOUNT3="30.00"
EXECUTIONDATE1="12/08/2011"
EXECUTIONDATE2="14/08/2011"
EXECUTIONDATE3="16/08/2011"
APR="813.56"
COST="1.08"
VERSION="V0001"
CONTRACT="…”
/>
Notes:
- Contrary to the input parameters, the amounts in the response have a decimal separator
- Date formats are dd/MM/yyyy
We strongly advise you to verify the data by performing a SHA-OUT check on the returned data.
In order to verify the integrity of the submitted data, our system requires each request to include a SHA signature. This signature is built by hashing the contents of the request, in the 'parameter=value' format in alphabetical order.
For more information on SHA-OUT, go to e-Commerce.
3. Error Messages
The following error codes may be returned by the PM Query page:
NCERROR = 50001111
User/Password mismatch
NCERROR = 50001111
SHA Signature error
CHECK PSPID EXIST AND ACTIVE
NCERROR= 50001111
CHECK PM 3XCB CONFIGURED AND ACTIVE
NCERROR = 50001111
CHECK AMOUNT, CURRENCY AND OPERATION MATCH 3XCB CONFIGURATION
NCERROR = 50001111