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://secure.paypage.be/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