Batch processing

Introduction

This integration mode is used to process bundles of transactions offline.

A CSV file containing a list of transactions to be processed must be submitted via SFTP.

This mode is available for server to server transactions.

warning

3-D Secure is not available, any 3-D Secure transaction will fail.

security

For security reasons, bank cards’ parameters are forbidden.

info

Thereby, only recurring payments are available for Payment methods using bank cards.

Batch mode activation

Contact your Dalenys account manager for batch mode activation.

Once the module is activated, the SFTP login identifier can be found in the dedicated Dashboard section : Accounts > Account list > Configuration > BATCH section.

EXTRANET_BATCH

The Batch feedback URL is optional and allows you to receive a specific notification, once the batch file has been processed: (see notification dedicated section).

Instructions

Here is how a batch process unwinds:

  1. Merchant creates the file
  2. File is uploaded onto his SFTP workspace
  3. Check method: file integrity is verified
  4. Process method: starts the file processing
  5. Platform response
  6. Result retrieval
1. File creation

You should create a CSV file containing all the necessary columns : ALIAS, ORDERID, AMOUNT, VERSION

It MUST respect the following format:

  • CSV (separator ; (semi-colon), field values inside “ (double quotes), line break (unix), utf-8 encoding)
  • Unique filename using only alphanumerical characters and - (dash), _ (underscore) and . (period)
  • File should not exceed 150 KO
  • For security reasons, these columns are forbidden : CARDCODE, CARDCVV and CARDVALIDITYDATE
info
  • The following fields are not authorized : CARDCODE, CARDVALIDITYDATE, CARDCVV. It is however possible to use the corresponding ALIAS for recurring transactions.

  • Transactions with ALIASMODE=oneclick are not allowed with batch processing.
  • The HASH field is not expected for each operation present in the file, only the global request HASH must be calculated.
  • All operations in one same file must use the same IDENTIFIER.

Example:

"ALIAS";"AMOUNT";"CLIENTEMAIL";"CLIENTIDENT";"IDENTIFIER";"OPERATIONTYPE";"ORDERID";"VERSION"
"A112448";"100";"john.do@email.com";"145_john.doe@email.com";"payment";YOUR_Dalenys_IDENTIFIER";"12345";"3.0"
2. File is uploaded on the SFTP workspace

File must be uploaded using a SFTP client.

The SFTP address will be communicated by your Dalenys account manager.

The SFTP user login can be found in the dedicated Dashboard section.

The authentication is done via a SSH-2 RSA (2048 bits) key typed into the SFTP client. (see section SSH key generation and SFTP login)

3. Optional (recommanded) step: check method

This steps allows you to verify each line’s name, size and format.

A REST request with the following information must be sent to the server:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/batch/process" \
--data "method=check" \
--data "params[FILEHASH]=62efb12401dcbdfc61fea9de67e77c44f4e0d0ec78208f37ac0830b16ee9e41d" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=check" \
--data "params[ORDERID]=1234" \
--data "params[VERSION]=3.0" \

warning

A file which has already been processed with the PROCESS method cannot be checked again.

Example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/batch/process" \
--data "method=check" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=check" \
--data "params[ORDERID]=1234" \
--data "params[FILE]=" \
--data "params[FILEHASH]=62efb12401dcbdfc61fea9de67e77c44f4e0d0ec78208f37ac0830b16ee9e41d" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

JSON formatted synchronous response:

Here is the request result from the platform:

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE check

    The action you want to process.

    Example: payment

Possible execution codes:

Code Message
0000
message
2013
2014
4. File processing: process method

The PROCESS method triggers the file’s processing.

  • FILEHASH string(64)

    File verification signature.

    Example: 62efb12401dcbdfc61fea9de67e77c44f4e0d0ec78208f37ac0830b16ee9e41d

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: Demo Shop

  • OPERATIONTYPE process

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/batch/process" \
--data "method=process" \
--data "params[FILE]=" \
--data "params[FILEHASH]=62efb12401dcbdfc61fea9de67e77c44f4e0d0ec78208f37ac0830b16ee9e41d" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=process" \
--data "params[ORDERID]=1234" \
--data "params[VERSION]=3.0" \

JSON formatted synchronous response:

Here is the request result from the platform:

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE process

    The action you want to process.

    Example: payment

Possible execution codes:

Code Message
0000
message
2013
2014
5. Platform response

When the file processing is over, a UNIQUE notification is sent to the merchant, but no notifications for each operations. (see notification dedicated section).

Send parameters:

Here is the request result from the platform:

  • BATCHID string(1-32)

    Batch request identifier.

    Example: A1234

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE process

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • REPORT string(1-50)

    Report CSV file name

    Example: csv_file.csv

  • REPORTHASH string(64)

    Report CSV file signature (a sha256 of the report file).

    Example: 62efb12401dcbdfc61fea9de67e77c44f4e0d0ec78208f37ac0830b16ee9e41d.

Possible execution codes:

Code Message
0000
message
2013
2014
6. File processing result retrieval

A CSV file containing each operation’s result can be downloaded from the SFTP workspace for a period of 7 days, after which the original file and results will be automatically deleted.

The REPORT file name is indicated in the parameter of the notification.

Each operation has its own execution code. (see execution code appendix)

The exact list of columns depends on the payment method, the processing response and the OPERATIONTYPE of each transaction.

Example:

LINE ORDERID OPERATIONTYPE EXECCODE MESSAGE TRANSACTIONID DESCRIPTION ALIAS AMOUNT
2 58cbad104b866 payment 0000 The transaction has been accepted. A456789 myShop.com    
3 58cbad104b8b2 payment 0000 The transaction has been accepted. A456790 myShop.com    
4 58cbad104b918 payment 0000 The transaction has been accepted. A456792 myShop.com   12345

SSH Key generation and SFTP login

  1. Download PuTTY Key Generator
  2. Make sure the generated key is bits SSH-2 RSA with 2048 bits:

    BATCH_SSH

  3. Click on Generate and move your mouse until the key is generated.

    BATCH_KEY

  4. Type and confirm a passphrase which will systematically be requested upon login onto the SFTP workspace:

    BATCH_PASSPHRASE

  5. Save the private key which will be used during SFTP login and also save the public key.

  6. Copy the public key generated in PuTTY Key Generator and paste it in the specific Dashboard field:

    BATCH_PUTTYKEY

    BATCH_PUTTYKEY1

    (This modification will take 5 minutes to be taken into account)

  7. Start your SFTP client (e.g. Filezilla) to log into the Dalenys SFTP. Type in the host (address) provided by your Dalenys account manager, the port number 5752, the protocol SFTP, and the identifier found in the Batch section of the Dashboard

    BATCH_SFTP

    BATCH_SFTP1

  8. Login to save the access point, type your passphrase to confirm the authentication.

Batch notification

The Batch feedback URL is optional and allows you to receive a specific notification, once the batch file has been processed: (see redirection and notification).

You will retrieve the following POST parameters on your NOTIFICATION_URL:

  • BATCHID string(1-32)

    Batch request identifier.

    Example: A1234

  • EXECCODE string(4)

    The operation result code. (See the complete list of execution code)

    Example: 0000

  • HASH string(64)

    The transaction’s hash as described in the dedicated section.

    Example: 15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: YOUR_IDENTIFIER

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE process

    The action you want to process.

    Example: payment

  • ORDERID string(1-40)

    Unique ID associated to an order in the merchant’s database (as specified in your initial POST request)

    Example: 1234

  • REPORT string(1-50)

    Report CSV file name

    Example: csv_file.csv

  • REPORTHASH string(64)

    Report CSV file signature (a sha256 of the report file).

    Example: 62efb12401dcbdfc61fea9de67e77c44f4e0d0ec78208f37ac0830b16ee9e41d.

security

‘You have to check the received HASH against the one you generate, to confirm the request’s origin and integrity before redirecting the user. See this section for more information. Other parameters relating to the original request as AMOUNT and ORDERID must be verified.’