Ultimo aggiornamento 29/10/2014

4. Automatic upload process

There are 2 different ways to upload a file:

  1. Manual file upload: You can upload the payment files manually from your account’s back office. Go to Basic Batch for more information.
  2. Automatic upload from a merchant application: the merchant application makes https file upload and download requests on specific pages in our system. This requires developments in the merchant application.

This chapter describes the automatic upload process from a merchant application.

4.1 Request URL and specific parameters

An Automatic File Upload allows you to process multiple payments directly from your own system (programme, scheduled task, etc.) without the need for a browser or human intervention. Your server sends an HTTPS POST request to our server. The transaction file and additional parameters are transmitted in the “content” of the https request.

Your application sends an HTTPS request to the following page on our server:

  • Test: https://ogone.test.v-psp.com/ncol/test/AFU_agree.asp (will be used in further examples)
  • Production: https://secure.ogone.com/ncol/prod/AFU_agree.asp

The file format is identical for manual and automatic file uploads. In the event of automatic file upload however, login data, certain process data and general parameters are mandatory in the request. You can submit these parameters as header/footer parameters included in the file, or as POST parameters separately from the file.

The general parameters set out below need to be sent in each automatic file upload request. These parameters refer to “Content-disposition” in the HTTP protocol and can only be specified as POST parameters separately from the file, not in headers.

Field Description
REPLY_TYPE
Defines which response format is requested from our system. Possible values:
  • XML (default)
  • HTML
The HTML reply contains the same page as when a file is uploaded manually.
PROCESS_MODE

Possible values for the processing mode:

  • SEND: a new file is uploaded but no format check is requested
  • CHECK: a simple format check is requested (corresponds to step 2 of the manual file upload)
  • PROCESS: the processing of an already uploaded file is requested (corresponds to step 3 of the manual file upload)
  • CANCEL: the cancellation of an already checked (but not loaded) file is requested (corresponds to the cancel button after step 2 of the manual file upload)
  • Some steps can also be combined (not recommended):
  • CHECK: can combine SEND and CHECK (the transaction file is transmitted with PROCESS_MODE=CHECK but without our system’s FileID that is normally returned after the SEND step).
  • CHECKANDPROCESS: can combine CHECK and PROCESS or SEND, CHECK and PROCESS.
MODE

Can be used to specify whether your application is waiting for a response from our server or if you will retrieve the response later. Valid modes are:

  • SYNC (Default)
  • ASYNC

Currently this option only has an effect on the PROCESS or CHECKANDPROCESS steps (see PROCESS_MODE above).

In SYNC mode, you will receive the result of the payment validation process if you stay connected (not the result of the authorisation with the acquirer(s), as this always occurs offline for file uploads).

In ASYNC mode, the validation process is performed offline and you only receive the FILE ID as confirmation. An email is sent to the merchant when the file has been validated by our system. If you send large files, we advise you to use ASYNC mode.

Independently of the mode used, an email is also sent once the file has been processed (submitted to the acquirer).


Examples

Additional parameters specified as separate POST parameters

<form action="https://ogone.test.v-psp.com/ncol/test/AFU_agree.asp" method=POST>
<textarea name=FILE>
10000;EUR;;4111111111111111;11/12;Order0001;golf balls;Paul Smith;;;;;;;;;;;;;;;;;;;123;
9500;EUR;;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;;;;;;;;;;;;;;;;;;485;
2050;EUR;;4444333322221111;11/09;Order0003;cocktails;John Doe;;;;;;;;;;;;;;;;;;;875;
</textarea>
<input type=text name=FILE_REFERENCE value=”File53484”>
<input type=text name=PSPID value=”FishShop1”>
<input type=text name=USERID value=”FishAPI”>
<input type=text name=PSWD value=”MySecret81”>
<input type=text name=TRANSACTION_CODE value=”ATR”>
<input type=text name=OPERATION value=”RES”>
<input type=text name=NB_PAYMENTS value=”3”>
<input type=text name=REPLY_TYPE value=”XML”>
<input type=text name=MODE value=”SYNC”>
<input type=text name=PROCESS_MODE value=”SEND”>

</form>

Additional parameters specified in the file headers/footer

<form action="https://ogone.test.v-psp.com/ncol/test/AFU_agree.asp" method=POST>
<textarea name=FILE> OHL;FishShop1;MySecret81;;FishAPI;
OHF;File53484;ATR;RES;3;
10000;EUR;;411111111111111;11/12;Order0001;golf balls;Paul Smith;;RES;;;;;;;;;;;;;;;;;123;
9500;EUR;;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;RES;;;;;;;;;;;;;;;;;485;
2050;EUR;;4444333322221111;11/09;Order0003;cocktails;John Doe;;RES;;;;;;;;;;;;;;;;;875;
</textarea>
<input type=text name=REPLY_TYPE value=”XML”>
<input type=text name=MODE value=”SYNC”>
<input type=text name=PROCESS_MODE value=”SEND”>
</form>

4.2 Upload process

We advise you to split the upload process into the different steps: SEND, CHECK and PROCESS (“PROCESS_MODE” values). These steps correspond to the different steps of the manual file upload.

There are two main advantages of splitting the upload process:

  • The split between CHECK and PROCESS allows your application to cancel the upload after our system’s format check, should there be too many format errors in the file.
  • The split between SEND and the rest of the processing prevents you from processing the same file more than once. If your application doesn't receive a response after a certain step for any reason, you can repeat the step with no risk. If you perform the upload in a single step (CHECKANDPROCESS) and a communication problem occurred before your application received the response, it might think that the file has not been uploaded and try uploading it a second time, resulting in duplicate processing of the same file.

The merchant's application triggers each step by making an HTTPS POST request to our server. The HTTPS request can be sent as a standard POST HTTPS request (with the file content in a standard field named “FILE”) or as a MULTIPART/FORM-DATA POST HTTPS request (with the file content in a “file” type field named “FILE”, <input type="file" name="File1">). For both methods, you need a component capable of sending HTTP requests to a secure server.

In the first step (SEND), the file itself is part of the content of the request. Our system returns a FileID in the XML response to this request. You will use this FileID instead of the file itself in the subsequent upload steps (CHECK and PROCESS).

4.2.1 Send

When you send PROCESS_MODE=SEND, you upload a new transaction file, but no check or processing is performed (this corresponds to Step 1 of a manual file upload).

When our system receives the HTTPS request, it checks that the general parameters are valid. If something is wrong, an error is returned to your application and the process stops without performing any operation.

If the general parameters are valid, our system returns a FILEID and a GUID. This FILEID will be used in subsequent requests instead of the file itself. The GUID can be used in subsequent requests to replace Login/Password.

After this step, the file status is set to “Uploaded” (visible in the back office or with the automatic file download).

Example

Request

<form action="https://ogone.test.v-psp.com/ncol/test/AFU_agree.asp" method=POST>
<textarea name=FILE>
10000;EUR;;411111111111111;11/12;Order0001;golf balls;Paul Smith;;RES;;;;;;;;;;;;;;;;;123;
9500;EUR;;5399999999999999;11/10;Order0002;mobile phone;Jane Doe;;RES;;;;;;;;;;;;;;;;;485;
2050;EUR;;4444333322221111;11/09;Order0003;cocktails;John Doe;;RES;;;;;;;;;;;;;;;;;875;
</textarea>
<input type=text name=FILE_REFERENCE value=”File53484”>
<input type=text name=PSPID value=”FishShop1”>
<input type=text name=USERID value=”FishAPI”>
<input type=text name=PSWD value=”MySecret81”>
<input type=text name=TRANSACTION_CODE value=”ATR”>
<input type=text name=OPERATION value=”RES”>
<input type=text name=NB_PAYMENTS value=”3”>
<input type=text name=REPLY_TYPE value=”XML”>
<input type=text name=MODE value=”SYNC”>
<input type=text name=PROCESS_MODE value=”SEND”>

</form>

XML reply

<?xml version="1.0" ?>
<AFU_REPLY>
<SEND_FILE>
<FILEID>2010</FILEID>
<GUID>8B1F5D65D5C7C5C80551D2AA955F810A45BD1752</GUID>
</SEND_FILE>
</AFU_REPLY>

4.2.2 Check

When you send PROCESS_MODE= CHECK, a simple format check is requested (this corresponds to Step 2 of a manual file upload).

You will use the FILEID in the request instead of the file itself.

Our system returns format errors, should any such errors occur.

After this step, the file status is set to “Checked”.

Example

Request

<form action="<%URL_TESTENV%>AFU_agree.asp" method=POST>
<input type=text name=PSPID value=”FishShop1”>
<input type=text name=USERID value=”FishAPI”>
<input type=text name=PSWD value=”MySecret81”>
<input type=text name=REPLY_TYPE value=”XML”>
<input type=text name=MODE value=”SYNC”>
<input type=text name=PFID value=”2010”>
<input type=text name=PROCESS_MODE value=”SEND”>
</form>

XML reply

<?xml version="1.0" ?>
<AFU_REPLY>
<FORMAT_CHECK>
<FORMAT_CHECK_ERROR>
<ERROR>|Wrong credit card number format|</ERROR>
<LINE>1</LINE>
<NCERROR>50001002</NCERROR>
<PAYID>0</PAYID>
<ORDERID>Order0001</ORDERID>
<NCSTATUS>5</NCSTATUS>
<STATUS>0</STATUS>
</FORMAT_CHECK_ERROR>
<FILEID>2012</FILEID>
</FORMAT_CHECK>

</AFU_REPLY>

4.2.3 Process

When you send PROCESS_MODE=PROCESS, the processing of the file is requested (this corresponds to Step 3 of a manual file upload).

You will use the FILEID in the request instead of the file itself.

Our system returns loading errors, should any such errors occur.

OK_PAYMENTS is the number of transactions correctly loaded. RANGE_START and RANGE_STOP represent the range of PAYIDs for the loaded transactions, as assigned by our system (only when the transaction_code is ATR).

After this step, the file status is set to “Being Processed”.

After the response is sent, the transactions are processed with the acquirers (banks) in offline mode. It is possible to retrieve results in your back office or with the automatic file download.

Example: Request in SYNC mode

Request in SYNC mode


<form action="https://ogone.test.v-psp.com/ncol/test/AFU_agree.asp" method=POST>
<input type=text name=PSPID value=”FishShop1”>
<input type=text name=USERID value=”FishAPI”>
<input type=text name=PSWD value=”MySecret81”>
<input type=text name=REPLY_TYPE value=”XML”>
<input type=text name=MODE value=”SYNC”>
<input type=text name=PFID value=”2010”>
<input type=text name=PROCESS_MODE value=”PROCESS”>
</form>

XML reply

<?xml version="1.0" ?>
<AFU_REPLY>
<PROCESSING>
<NC_ERROR>
<NCERRORPLUS>||Wrong credit card number format|</NCERRORPLUS>
<LINE>1</LINE>
<NCERROR>50001002</NCERROR>
<PAYID>37267</PAYID>
<ORDERID>Order0001</ORDERID>
<NCSTATUS>5</NCSTATUS>
<STATUS>0</STATUS>
</NC_ERROR>
<FILEID>2011</FILEID>
<SUMMARY>
<NB_PAYMENTS>3</NB_PAYMENTS>
<OK_PAYMENTS>2</OK_PAYMENTS>
<RANGE_START>37267</RANGE_START>
<RANGE_STOP>37269</RANGE_STOP>
</SUMMARY>
</PROCESSING>
</AFU_REPLY>


Example: Request in ASYNC mode

Request in ASYNC mode


<form action="https://ogone.test.v-psp.com/ncol/test/AFU_agree.asp" method=POST>
<input type=text name=PSPID value=”FishShop1”>
<input type=text name=USERID value=”FishAPI”>
<input type=text name=PSWD value=”MySecret81”>
<input type=text name=REPLY_TYPE value=”XML”>
<input type=text name=MODE value=”ASYNC”>
<input type=text name=PFID value=”2010”>
<input type=text name=PROCESS_MODE value=”PROCESS”>
</form>

XML reply

<?xml version="1.0" ?>
<AFU_REPLY>
<PROCESSING>
<FILEID>2011</FILEID>
<SUMMARY>
<NB_PAYMENTS>3</NB_PAYMENTS>
</SUMMARY>
</PROCESSING>
</AFU_REPLY>

4.3 XML response tags

Tag
Description
<AFU_REPLY>
Automatic File Upload Reply
<PARAMS_ERROR>
General parameter errors
<PARAM>
Parameter name
<ERROR>
Error description
<FILE_ERROR>
File processing error
<ERROR>
Error description
<FORMAT_CHECK>
Individual transaction format check
<FILEID>
Numeric FileID designated by our system
<GUID>

Alphanumeric Login Identifier for the file designated by our system.

This GUID is designated the first time you submit a file (only once per FileID). When you want to process the file or perform another valid operation (or download at file level etc.), you can submit this GUID instead of the login parameters described above. It serves as a form of password, granting access only to this specific file.

<FORMAT_CHECK_ERROR>
Transaction format error
<LINE>
Corresponding line number in the file
<ERROR>
Error description
<NCERROR>
Numeric error code
<PROCESSING>
Loading of the individual transactions
<NC_ERROR>
Load error
<LINE>
Payment line
<PAYID>
Our system’s PAYID
<NCSTATUS>
Error status (first digit of NCERROR)
<STATUS>
Status of the PAYID after the transaction has been loaded
<NCERROR>
Numeric error code
<NCERRORPLUS>
Error description
<SUMMARY>
Summary of the file
<NB_PAYMENTS>
Number of received payments
<OK_PAYMENTS>
Number of correctly formatted payments
<RANGE_START>
First PAYID (for ATR-new orders only)
<RANGE_STOP>
Last PAYID (for ATR-new orders only)

4.4 Security

4.4.1 Secure requests

The automatic file upload and download functions are built on a robust secure communication protocol. 
Batch API is a set of instructions submitted with standard HTTPS Post requests. We only allow the merchant to connect to us in secure HTTPS mode.

There is no need for a client SSL certificate.

4.4.2 IP address

The IP address(es) or IP address range(s) of the servers from which you are sending us requests can be configured in the IP address field of the "Data and origin verification" tab, checks for automatic Batch section of the Technical Information page in your account. We will check the IP address when you perform a request for an automatic file upload or download.

If the IP address from which the request originates has not been defined in the IP address field of the "Data and origin verification" tab, checks for automatic Batch section of the Technical Information page in your account, you will receive the error message “unknown order/1/i”. The IP address from which the request was sent will also be displayed in the error message.

Ingenico ePayments è un provider mondiale di servizi di pagamento digitale, Ingenico Payment Services fornisce una risposta efficace alla complessità di pagamenti qualunque sia il canale: in rete, con il cellulare o in un negozio. Procura soluzioni innovative per il commercio in rete, per quanto riguardano l’aspetto finanziario, l’aspetto commerciale e la complessità dei canali, sostiene i commercianti a gestire, incassare e proteggere i propri pagamenti, prevenendo le frodi ed aumentando le entrate attraverso conversioni più elevate. Ingenico ePayments fa parte del gruppo Ingenico, leader mondiale nel settore di pagamenti in rete.

Questo sito web utilizza i cookie per essere in grado di darvi la migliore esperienza utente. Se non si desidera accettare i cookie, è possibile modificare le impostazioni dei cookie. Cliccate su 'Accetta' per consentire tutti i cookie di questo sito.

Impostazioni dei cookie

Introduzione

Funzionale

I cookies funzionali sono necessari per il funzionamento corretto del sito web. Non è possibile disattivare questi cookie.

Ottimizzato

I cookies per l’ottimizzazione ci permettono di analizzare l'utilizzo del sito in modo che possiamo monitorare e migliorare il nostro sito.
Questo รจ il livello predefinito.

Personalizzata

Cookies di personalizzazione vengono utilizzati per i social media e per personalizzazione avanzata, permettendoci di mostrarvi le informazioni collegate alla vostra azienda.


Esempio delle funzionalità consentite

  • Salvare le preferenze riguardanti il paese
  • Salvare le preferenze riguardanti la lingua

Esempio delle funzionalità non consentite

  • Salvataggio dei dati personali
  • Tracciamento per scopi di remarketing
  • Tracciamento anonimo tramite Google Analytics

Esempio delle funzionalità consentite

  • Salvare le preferenze riguardanti il paese
  • Salvare le preferenze riguardanti la lingua
  • Tracciamento anonimo tramite Google Analytics
  • Tracciamento per scopi di remarketing

Esempio delle funzionalità non consentite

  • Salvataggio dei dati personali
  • Tracciamento per scopi di remarketing

Esempio delle funzionalità consentite

  • Salvare le preferenze riguardanti il paese
  • Salvare le preferenze riguardanti la lingua
  • Tracciamento anonimo tramite Google Analytics
  • Mostrare contenuto in linea con i vostri interessi
  • Mostrare pubblicità in linea con i vostri interessi
  • Tracciamento per scopi di remarketing

Esempio delle funzionalità non consentite

  • Salvataggio dei dati personali