PostFinance integration

logo PostFinance

Introduction

PostFinance is the financial department of Swiss Post.

It involves redirecting the cardholder to PostFinance to finalize its transaction.

info

Upon receipt of EXECCODE = 0002 in the synchronous response, you must redirect the cardholder to the PostFinance form by displaying the content of the REDIRECTHTML parameter. (Base64 encoded)

After validating the payment on PostFinance, the cardholder is redirected to the REDIRECT_URL.

The result of the transaction will also be transmitted by HTTP notification. (See the specifics of the notification)

Compatible operations and options

Server to server integration

In this mode, you have to send a POST request containing your order’s parameters over HTTPS to the Dalenys platform.

Authorization

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=" \
--data "params[OPERATIONTYPE]=payment" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[AMOUNT]=1000" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[CLIENTUSERAGENT]=Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0" \
--data "params[CLIENTIP]=10.1.1.1" \
--data "params[ORDERID]=1234" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Parameters

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CLIENTIP ipv4

    The user’s public IP address.

    Example: 10.1.1.1

  • CLIENTUSERAGENT string(1-255)

    The HTTP user agent.

    Example: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • 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

  • METADATA string(1-255)

    Additional transactional data. Contact your account manager for more informations.

    Example: @METADATA-MYWEBSITE

  • OPERATIONTYPE (payment,authorization,capture,refund,void)

    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

Request result

Here is the request result from the platform:

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • 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 authorization

    The action you want to process.

    Example: payment

  • REDIRECTHTML string(no length limit)

    HTML content to display to the user to continue the processing. The string is base64 encoded.

    Example:

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

Notification result parameters

Please see the dedicated section about notification and redirection

Here is the request result from the platform:

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

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

    Example: 0000

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • 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

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, sk

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE authorization

    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

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Capture

Authorizations have to be captured by a server to server request.

info

You can only capture a succeeded authorization transaction and an authorization can only be captured once.

warning

A capture must be triggered within 7 days of an authorization, otherwise capture success is no longer guaranteed.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=capture" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=capture" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \

Parameters

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • 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 capture

    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

  • TRANSACTIONID string(1-32)

    The authorization’s TRANSACTIONID you want to capture.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • 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 capture

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

Notification result parameters

Here is the request result from the platform:

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

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

    Example: 0000

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • 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

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, sk

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE capture

    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

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Refund

Refunds can either be processed through server-to-server request or Dalenys Dashboard.

Example

Here is a server to server request example:

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=refund" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=refund" \
--data "params[TRANSACTIONID]=A1123456" \
--data "params[ORDERID]=1234" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[VERSION]=3.0" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \

Parameters

  • AMOUNT integer

    The amount to refund. When not specified, refund 100% of the initial transaction resting amount. Could not be higher than the resting amount.

    Example: 1000

  • DESCRIPTION string(1-510)

    A short description of the operation, can be used to trigger fraud actions. Don’t hesitate to ask your Payment Manager for some advice on this topic.

    Example: Knows nothing

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • 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 refund

    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

  • TRANSACTIONID string(1-32)

    The capture’s TRANSACTIONID you want to refund.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0

Request result

Here is the request result from the platform:

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • 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 refund

    The action you want to process.

    Example: payment

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

Notification result parameters

Here is the request result from the platform:

  • AMOUNT integer

    The transaction amount in the smallest money decimal (e.g. cents for euro).

    Example: 1000

  • CLIENTEMAIL email(5-255)

    The user’s email.

    Example: john.snow@example.com

  • CLIENTIDENT string(1-255)

    Unique identifier of the user in your application (e.g. a login or a primary key).

    Example: john.snow

  • CURRENCY string(3)

    Currency code (ISO 4217 format).

    Example: EUR

  • DESCRIPTOR string

    The transaction label sent to the bank network. The transaction will display with this label on the user’s bank statement.

    Example: myshop.com

  • EXECCODE string(4)

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

    Example: 0000

  • EXTERNALENTITYID int (1-10)

    Merchant account’s reference

    Example:

  • EXTERNALREFERENCE int (9)

    Transaction’s reference (string left padded with 0 of 9 digits)

    Example: 19

  • EXTRADATA string(1-255)

    Free field (Dalenys will send you back the content of the EXTRADATA you specified ahead).

    Example: referrer=myshop.com;order=premium

  • 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

  • LANGUAGE fr, en, de, es, it, nl, zh, ru, pt, sk

    Configure the hosted form display language.

    Example: en

  • MESSAGE string(no length limit)

    The operation result description linked to EXECCODE.

    Example: The transaction has been accepted

  • OPERATIONTYPE refund

    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

  • TRANSACTIONID string(1-32)

    Unique Dalenys transaction ID. Make sure to store this ID in your database.

    Example: A1123456

  • VERSION 3.0

    The API protocol version.

    Example: 3.0