Last update 20/04/2016

5. Direct Maintenance

A direct maintenance request from your application allows you to:

  • Perform a data capture (payment) of an authorised order automatically (as opposed to manually in the back office);
  • Cancel an authorisation of an order;
  • Renew an authorisation of an order;
  • Refund a paid order.

Data captures, authorisation cancellations and authorisation renewals are specifically for merchants who have configured their account/requests to perform the authorisation and the data capture in two steps.

5.1 Maintenance request

5.1.1 Request URL

  • The request URL in the TEST environment is https://ogone.test.v-psp.com/ncol/test/maintenancedirect.asp.
  • The request URL in the PRODUCTION environment is https://secure.ogone.com/ncol/prod/maintenancedirect.asp.

Change "test" to "prod"

Replace “test” with “prod” in the request URL when you switch to your production account. If you forget to change the request URL, once you start working with real orders, your maintenance transactions will be sent to the test environment and will not be sent to the acquirers/banks.

5.1.2 Request parameters

The following table contains the mandatory request parameters for performing a maintenance operation:

Field Description
AMOUNT
Order amount multiplied by 100.

This is only required when the amount of the maintenance differs from the amount of the original authorisation. However, we recommend its use in all cases.

Our system will check that the maintenance transaction amount is not higher than the authorisation/payment amount.
OPERATION

Possible values:

  • REN: renewal of authorisation, if the original authorisation is no longer valid.
  • DEL: delete authorisation, leaving the transaction open for further potential maintenance operations.
  • DES: delete authorisation, closing the transaction after this operation.
  • SAL: partial data capture (payment), leaving the transaction open for another potential data capture.
  • SAS: (last) partial or full data capture (payment), closing the transaction (for further data captures) after this data capture.
  • RFD: partial refund (on a paid order), leaving the transaction open for another potential refund.
  • RFS: (last) partial or full refund (on a paid order), closing the transaction after this refund.

Please note that with DEL and DES that not all acquirers support the deletion of an authorisation. If your acquirer does not support DEL/DES, we will nevertheless simulate the deletion of the authorisation in the back office.

ORDERID You can send the PAYID or the orderID to identify the original order. We recommend the use of the PAYID.
PAYID
PSPID Your account's PSPID
PSWD Password of your API-user
SHASIGN Signature (hashed string) to authenticate the data (see SHA-IN-signature)
USERID Your API-user

5.1.3 Test page

You can test direct maintenance requests here: https://ogone.test.v-psp.com/ncol/test/testdm.asp

5.2 Maintenance response

Our server returns an XML response to the maintenance request:

Example of an XML response to a direct maintenance request
<?xml version=”1.0”?>
<ncresponse orderID=”99999” PAYID=”1111111” PAYIDSUB=”3” NCSTATUS=”0” NCERROR=”” NCERRORPLUS=”” ACCEPTANCE=”12345” STATUS="91" amount="125" currency="EUR"/> 

The following table contains a list of the ncresponse tag attributes:

Field
Description
ACCEPTANCE Acceptance code returned by acquirer
AMOUNT Order amount (not multiplied by 100)
CURRENCY Order currency
NCERROR Error code
NCERRORPLUS Explanation of the error code
NCSTATUS First digit of NCERROR
ORDERID
Your order reference
PAYID Payment reference in our system
PAYIDSUB The history level ID of the maintenance operation on the PAYID
STATUS Transaction status (Possible statuses)

The standard ncresponse tag attributes are the same as those for the XML reply to a new order, except for the extra attribute PAYIDSUB.

5.3 Duplicate request

If maintenance is requested twice for the same order, the second request will theoretically be declined with an error “50001127” (This order is not authorised), because the initial successful transaction will have changed the order status.

This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

Cookie settings

Introduction

Functional

Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

Optimized

Optimization cookies allow us to analyze site usage so we can measure and improve our website.
This is the default level.

Personalized

Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


Example functionality allowed

  • Store country preference
  • Store language preference

Example functionality not allowed

  • Saving personal data
  • Anonymous tracking via Google Analytics
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics

Example functionality not allowed

  • Saving personal data
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics
  • Serve content relevant to your interests
  • Serve ads relevant to your interests
  • Tracking for remarketing purposes

Example functionality not allowed

  • Saving personal data