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 Extranet 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.
  • 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 Extranet 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.be2bill.com/front/service/rest/batch/process" \
--data "method=check" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=check" \
--data "params[ORDERID]=1234" \
--data "params[FILEHASH]=" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--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.be2bill.com/front/service/rest/batch/process" \
--data "method=check" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--data "params[OPERATIONTYPE]=check" \
--data "params[ORDERID]=1234" \
--data "params[FILE]=" \
--data "params[FILEHASH]=" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

JSON formatted synchronous response:

Here is the request result from the platform:

  • OPERATIONTYPE check

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

Possible execution codes:

Code Message
0000 Successful operation
2013 File not found
2014 Invalid file
4. File processing: process method

The PROCESS method triggers the file’s processing.

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE process

    The action you want to process.

  • ORDERID string(1-40)

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

  • FILEHASH

  • HASH string(64)

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

  • VERSION 3.0

    The API protocol version.

Example:

$> curl --request POST --url "https://secure-test.be2bill.com/front/service/rest/batch/process" \
--data "method=process" \
--data "params[FILE]=" \
--data "params[FILEHASH]=" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[IDENTIFIER]=YOUR_IDENTIFIER" \
--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:

  • OPERATIONTYPE process

    The action you want to process.

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

Possible execution codes:

Code Message
0000 Successful operation
2013 File not found
2014 Invalid file
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:

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • OPERATIONTYPE process

    The action you want to process.

  • BATCHID

  • REPORT

  • REPORTHASH

  • ORDERID string(1-40)

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

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • HASH string(64)

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

Possible execution codes:

Code Message
0000 Successful operation
2013 File not found
2014 Invalid file
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 Extranet 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 443, the protocol SFTP, and the identifier found in the Batch section of the Extranet

    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:

  • OPERATIONTYPE process

    The action you want to process.

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

  • BATCHID

  • REPORT

  • REPORTHASH

  • ORDERID string(1-40)

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

  • EXECCODE string(4)

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

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

  • HASH string(64)

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

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.