LinkPay API

The LinkPay API makes it possible to automatically generate LinkPay payment links. It can be used to automatically transfer payment and order information over to LinkPay from your existing system, and thus integrate LinkPay as a seamless part of your business process. The API is interfaced using standard HTTPS POST calls which makes the integration straightforward from any system.

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]

Do you have question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00