DIBS Payment Gateway - Version 2.0

Document Logs
Change log:

Terms and definitions:

1 - Purpose of Document

This document provides the overall technical details and design of implementing and using the functionality as specified in section 2 - Introduction. This document will not cover implementation details – for this the code base should be inspected.

This is an implementation of a payment gateway that will be triggered by the Account Payment Engine (internal link).

2 - Introduction to Functionality

2.1 Split Payment (Split Capture)

Split payment covers the option of splitting an authorized payment into several payments/captures. This functionality can only be used on single payments. Payments authorized via Tickets (TicketAuth / Authorizing a RechargeTicket in Rator terms) are not single payments and therefore cannot be split.

2.2 Delete Ticket

A Ticket at DIBS is a RechargeTicket in Rator terms. Deleting a Ticket at DIBS removes the possibility of authorizing any new payments on the ticket (RechargeTicket).

The transaction requires a userid and password from an API user in the particular DIBS Account used when Deleting.

2.3 Cancel Authorization

The Cancel of an AccountPayment cancels the Authorization at DIBS. A Cancel Authorization releases any reserved amounts at DIBS associated with the original transaction.

The transaction requires a userid and password from an API user in the particular DIBS Account used when cancelling.

Note that DIBS states that the cancel operation/reversals might not be supported by the acquirer.

2.4 Refund

The refunding of an AccountPayment cancels the Captured payment at DIBS and transfers the money back to the card holder's account.

The transaction requires a userid and password from an API user in the particular Dibs Account used when refunding.

2.4.1 Partial Refund

The partial refund of an AccountPayment refunds part of a Captured payment at DIBS and transfers the money back to the card holder's account.

The transaction requires a user-id and password from an API user in the particular Dibs Account used when partially refunding.

2.5 MD5-Key Control

DIBS offers MD5-key control, in order to secure that the data (parameters) has not been tampered with during the transfer from your server to the DIBS server, i.e. due to errors, or due to hacking. The control works for both transfer of information from your server to the DIBS server, and also for the transfer back to your server.

Before calling the DIBS functions auth.cgi, capture.cgi, refund.cgi, or ticket_auth.cgi an MD5-key must be calculated using important parameters and a set of two shop specific keys. Depending on the function you want to call, a specific algorithm is used for calculating the exact key to send to the DIBS server.

2.6 Calcfee

Calcfee is a payment fee that is calculated and returned by DIBS at TicketAuth (Recharging or Authorizing a new payment on a RechargeTicket). When the fee is calculated at DIBS, it is also reserved together with/next to the original amount (the base of the calculation). DIBS must set up the calcfee on the gateway for outside use.

3. Implementation

3.1  Payment Gateway

The integration point implements the PaymentGatewayInterface and supports functionality for authorizing, capturing, cancelling, deleting tickets and refunding against an account payment.

3.2 Transaction Control Flow

A transaction to the gateway has to be performed only once. So, once the gateway is contacted, independently from the result, it should not be contacted again for the same payment.
The flow is controlled using PaymentLog methods and PaymentLog table records.

Example for Capture:

• if there is a PaymentLog persistent which is not linked to an account payment, the payment is set to error
• if there is a PaymentLog with status CAPTURED for the same transactionID, the payment is set to error
• otherwise, capturing the payment is attempted.

The same principle will be applied in case of authorization.

The gateway uses HTTP post request to communicate with DIBS. A list of the transactions possible are found here: http://tech.dibs.dk/dibs_api/flexwin/.

4. Operation

4.1 Split Payment (Split Capture)

An Account Payment will be attempted split at capture, if the name of the AccountPaymentType of the Account Payment has the prefix of SPLIT_PAYMENT.

Receiving a reason 8 from DIBS while attempting to split capture a payment might indicate that a split capture has been attempted upon a non-single payment, which is not possible.

4.2 Delete Ticket

Calling deleteFromPaymentGateway on a RechargeTicket will execute the deletion of the Ticket at DIBS. The following setup is necessary for a successful ticket deletion.

1. The TicketValue on the RechargeTicket must correspond to an existing and active Ticket in DIBS associated with the DIBS Account used (Set in the parameter SHOP_ID)
2. The parameters DELETE_TICKET_URL and DELETE_TICKET_CREDENTIALS must be present. The URL of DELETE_TICKET_URL is found at the Dibs site (currently https://login:password@payment.architrade.com/cgi-adm/delticket.cgi). The DELETE_TICKET_CREDENTIALS requires the format <userid>:<password> from a registered API user in the Account used at DIBS.

4.3 Cancel Authorization

Calling cancel on AccountPayment will cancel the Authorization of payment and release the reserved amounts related to the payment. The following setup is necessary for a successful cancellation of an authorization.

1. The CaptureStatus of the AccountPayment must be in AUTHORIZED ( or 5). AccountPayments not in this CaptureStatus will be rejected by the DIBS gateway.
2. The parameters CANCEL_URL and CANCEL_CREDENTIALS must be present. The CANCEL_URL is found at the DIBS site (currently https://login:password@payment.architrade.com/cgi-adm/cancel.cgi). The CANCEL_CREDENTIALS requires the format <userid>:<password> from a registered API user in the Account used at DIBS.

4.4 Refund

Calling refund on an AccountPayment will refund/reverse the capture of the payment and return the captured amounts related to the payment. The following setup is necessary for a successful refund transaction of a captured account payment.

1. The CaptureStatus of the AccountPayment must be in DO_REFUND ( or 65 ). AccountPayments not in this CaptureStatus will be rejected by the DIBS gateway.
2. The parameters REFUND_URL and REFUND_CREDENTIALS must be present. The REFUND_URL is found at the DIBS site (currently https://login:password@payment.architrade.com/cgi-adm/refund.cgi). The REFUND_CREDENTIALS must be in the format <userid>:<password> from a registered API user in the Account used at Dibs.

4.4.1 Partial Refund

Calling partial refund on an AccountPayment will refund part of a captured payment. The following setup is necessary for a successful partial refund transaction of a captured or partially refunded account payment.

1. The CaptureStatus of the AccountPayment must be in DO_REFUND ( or 65 ) and the Refund Amount must be set to an amount less or equal to the non-refunded amount of the payment. AccountPayments not in this CaptureStatus will be rejected by the DIBS gateway.
2. The parameters REFUND_URL and REFUND_CREDENTIALS must be present. The REFUND_URL is found at the DIBS site (currently https://login:password@payment.architrade.com/cgi-adm/refund.cgi). The REFUND_CREDENTIALS must be in the format <userid>:<password> from a registered API user in the Account used at Dibs.

For each successful refund of an Account Payment an extry is created in ACCOUNT_PAYMENT_REFUND.

4.5 MD5-Key Control

Setting the USE_TRANSACTION_VERIFICATION, SHOP_HASH_KEY_1 and SHOP_HASH_KEY_2 parameters enables the use of MD5-key control towards DIBS.

See the parameter setup section for more details.

4.6 Calcfee

Setting the PAYMENT_GATEWAY.CHARGE_FEE (Full path) parameter to the value 'Y' will enable the use of calcfees. When the successful TicketAuth/AuthorizationAutoRecharge response is received, the calcfee amount will be saved with the AccountPayment in the fee_amount field.

The AccountPayment will be captured with a total amount consisting of both the base amount and the fee_amount amount.

5. Setup

5.1 Database

Two changes in the database are necessary.

1. One PAYMENT_GATEWAY_DEF table entry
2. One or more entries in the ACCOUNT_PAYMENT_TYPE table

PAYMENT_GATEWAY_DEF

The Payment Gateway must be defined in the PAYMENT_GATEWAY_DEF table. The entry follows below.

ACCOUNT_PAYMENT_TYPE

For each of the Account Payment Types that is to use the DIBS Payment Gateway the PAYMENT_GATEWAY_DEF_ID column must be set to the id of the entry created in the PAYMENT_GATEWAY_DEF table. In the example used above 1 needs to be appended to ACCOUNT_PAYMENT_TYPE.PAYMENT_GATEWAY_DEF_ID column.

5.2 Parameter Setup

General Parameters

The DIBS tree node used is WEB.SELFCARE.PAYMENT.DIBS. If the BillingGroup related to the AccountPayment has the field PaymentGatewayKey set, then this is appended to the path tree for additional configuration. Example: WEB.SELFCARE.PAYMENT.DIBS.<BG.PaymentGatewayKey>. The following parameters are used when configuring the DIBS 2.0 payment gateway.

5.3 Response Action Parameters

These parameters sets the action for the different transactions in case an ErrorCode is received from DIBS. The parameters are mandatory. All the possible Error Codes from DIBS must be added.

5.4 Miscellaneous Parameters

Additional parameter used for enabling calcfee. These is not located with the other DIBS parameters.

5.5 Timeout parameters

6. Test Setup

The procedure of setting up the DIBS Payment Gateway for testing purposes is basically to set up the engine as for production, but with the following changes:

1. The parameter TESTMODE_ENABLED should be set to 'Y'.
   This will append a test flag to all requests sent and will tell DIBS to handle the request as a test.
2. The parameter SHOP_ID should be changed to the shop id of the CDRator Test Account. This way the actual result of each request can be confirmed/observed at the Dibs Administration site when testing. The CDRator Test Account shop id and login credentials for the account can be found at http://confluence.cdrator.com/display/Integration/Dibs+-+CDRator+Test+Account.