LinkPay API - DIBS Technical Documentation

Examples

This is a minimal HTML form containing only the three mandatory parameters and the MAC:

<form name="RedirForm" method="post" action="/%7Bcall%20URL%7D">
  <input type="hidden" name="amount" value="130,95" />
  <input type="hidden" name="orderid" value="141224_1" />
  <input type="hidden" name="currency" value="EUR" />
  <input type="hidden" name="MAC" value="d13eb0a0775d717e3f80d0bb31546455d38d6c1cabe7559149a1042cde644b35" />
</form>

This is a HTML form containing all parameters:

<form name="RedirForm" method="post" action="/%7Bcall%20URL%7D">
  <input type="hidden" name="amount" value="1300" />
  <input type="hidden" name="orderid" value="141224_1" />
  <input type="hidden" name="orgno" value="554433-2211" />
  <input type="hidden" name="vat" value="25" />
  <input type="hidden" name="cname" value="G%F6sta+Dagius" />
  <input type="hidden" name="oinfo" value="Order+specification%0D%0AArticle+1%0D%0AArticle+2%0D%0AArticle+3%0D%0A" />
  <input type="hidden" name="currency" value="SEK" />
  <input type="hidden" name="lang" value="en_UK" />
  <input type="hidden" name="edate" value="140331" />
  <input type="hidden" name="multipay" value="1" />
  <input type="hidden" name="discount" value="15" />
  <input type="hidden" name="MAC" value="01a02e07651d706efa83366b773b071c39361b50be73beadb249d6a2e20139f8" />
</form>

Note that the cname and oinfo parameters are URL-encoded. This allows national characters to transfer between systems using different code pages without being corrupted. URL-encoding is also necessary to transfer special characters like line feed.

The content of the example oinfo above is as follows:

Order specification
Article 1
Article 2
Article 3

The content of cname is: Gösta Dagius

The {call URL} in the action form element is a unique URL of your account provided by Censeo.

MAC calculation

The MAC calculation is done with the HMAC-SHA256 algorithm using a MACSeed string and a secret key as input.

The MACSeed string is created by concatenating all the parameters and their values in ascii-betical order as follows:

MACSeed = "amount=" + amount +
          "&cname=" + URLEncode(cname) +
          "&currency=" + currency +
          "&discount=" + discount +
          "&edate=" + edate +
          "&lang=" + lang +
          "&multipay=" + multipay +
          "&oinfo=" + URLEncode(oinfo) +
          "&orderid=" + orderid" +
          "&orgno=" + orgno +
          "&vat=" + vat

The above example shows almost all API parameters, however only used parameters (included in the HTML form) are to be included in the MACSeed string.

As shown above the cname and the oinfo parameters must be URL encoded before being concatenated in the MACSeed string.

The MAC is then calculated as follows:

MAC = HMAC_SHA256(SecretKey, MACSeed)

The secret key is provided by Censeo and is unique for your LinkPay account.

Parameter description

Parameters used in the call to LinkPay API:

Parameter	Mandatory	Value	Description
amount	Yes	Numeric Point (.) or comma (,) can be used as decimal delimiter. Examples: amount=10275 amount=12,95 amount=7.85	The amount to be paid. If the account is set to handle amounts without VAT, then the vat parameter have to be set in order to add eventual VAT to be paid.
vat	No	Numeric Vat in % where point (.) or comma (,) can be used as decimal delimiter. Examples: vat=25 vat=6,5 vat=12.5	VAT handling has to be activated in the account in order for this parameter to have any effect. If the account is set to handle amounts without VAT, then this parameter must be used to add eventual VAT to the amount. Only VAT values that have been configured in the account is valid. Other values will give “not allowed value” error.
orderid	Yes	Alpha Numeric Characters a-z, A-Z, 0-9, - and _ can be used. Space characters will be replaced by _ and other characters will be removed. Max length 60 characters Examples: orderid=12384-377 orderid=TF100_a5	The number used as reference such as the order or booking number. Orderid must be unique for each new LinkPay link. If there already exists a LinkPay link with this orderid and it has not yet been paid, then it will be updated with these new parameters. If the LinkPay link already exists and has been paid, then an “already paid” error will occur and the parameters sent will be discarded.
currency	Yes	Alpha Numeric Examples: currency=SEK currency=NOK currency=DKK currency=EUR currency=USD	The currency of the amount. Only currencies included in the agreement with the acquirer and activated in the Dibs account should be used.
cname	No	Alpha Numeric Should be URL encoded. Max length 40 characters (unencoded length). Examples: cname=John%20Smith (i.e. John Smith) cname=G %F6ran%20Ek (i.e. Göran Ek)	The name of the payer. Might be a person or a company.
orgno	No	Alpha Numeric Max length 40 characters Examples: orgno=556699-1111 orgno=NO78451232	The organization number or VAT number of the payer.
oinfo	No	Alpha Numeric Should be URLencoded. Max length 10240 characters (can be increased). See separateexample.	A description to clarify for the payer what is being paid for. The oinfo text will be shown on the LinkPay landing page, on the receipt and in the confirmation e-mail.
lang	No	Alpha Numeric Examples: lang=sv_SE lang=nb_NO lang=da_DK lang=en_UK lang=en_US	The language that will be used for the LinkPay link. If omitted the standard language of the LinkPay account will be used. At time of writing this document Swedish, Norwegian, Danish and English issupported.
edate	No	Numeric Date in the format: YYMMDD (length must be 6 characters) Example: 140324	The expiry date of the payment. The last day that the payment can be carried out.
discount	No	Numeric Discount in percent. Valid range is 1 – 99. Decimals not allowed. Example: discount=25	Discount or commission to be deducted from the total amount to be paid.
lpuser	No	Alpha numeric A valid LinkGen user Example: lpuser={any user id}	Set if the payment should be registered on a specific user (i.e. sales person). This user will also get a copy of the payment confirmation e-mail.
multipay	No	Binary Set to 0or 1 Example: multipay=1	Specifies if a LinkPay link is a MultiPay link or not. If set to 1 then MultiPay will be set and the link can be used for more than one payment.
gebyr	No	Binary Set to 0or 1 Example: gebyr=1	Specifies if the Dibs system should automatically add credit card fee to the amount. For this parameter to have any effect this feature first must be activated in the Dibs system.
curl	No	Alpha numeric A valid return URL Example: curl=www.linkpay.se/ret/	A URL to be shown as a return link to a page on your own site, shown on the receipt page after payment. The API must be set to generate the link automatically, for this parameter to have any effect.
extraid	No	Alphanumeric max length 20 characters Example: extraid={your extra id}	An extra ID that will be included in the confirmation e-mail. Not active by default. Needs to be activated in the account.

Return parameters

The return parameters are returned in plain text format.

The successful generation of a LinkPay link will give the following return parameter and value:

result=ok

If the API is configured to also deliver the LinkPay-link it will be included as a return parameter:

result=ok&link={your LinkPay link}

The link will be in URL-encoded format and needs to be URL-decoded before it can be used.

If any error occur the return parameters will have the following format:

result=error&reason={cause of error}[{error description}]

If more than one error occurred they will all be listed in the return parameter reason separated by a comma.

Example:

result=error&reason=currency[invalid],vat[not allowed value]

Then following return parameters will be returned if a paid LinkPay link with the same orderid exists:

result=error&reason=orderid[already paid]

When sending your customers a Link Payment, remember to inform your return, refund and cancellation policy clearly in the message that contains the link.