NAV Navbar
Enterpay lasku yritykselle

Payment Initiation

Integration to the Enterpay’s Lasku yritykselle service enables your customers to pay for their purchases by invoice.

From the customer perspective the purchase is initiated from the store similarly to other payment methods. The customer chooses the Lasku yritykselle payment button and is directed to Lasku yritykselle service where he/she finishes the purchase. After the purchase has been completed the customer is redirected back to the store.

Technically the integration is similar to bank integration.

The integration can be done using an existing payment service provider (PSP) or directly using Lasku yritykselle API. This document covers direct integration to the service.

1 Payment Integration Tutorial

The minimal steps for integrating Lasku yritykselle payment method are as follows:

  1. Sign a contract with Enterpay and obtain a public merchant ID and a secret API key.
  2. Create the payment button (an HTML form with hidden fields).
  3. Write a return page where the user is forwarded after the purchase completes or fails.

You can freely test the API calls against the dev installation at test.laskuyritykselle.fi.

1.1 HTML Form

The first step is to generate an HTML form as shown in the right pane.


<form action="https://laskuyritykselle.fi/api/payment/start" method="post">
  <!-- 'debug' should be 1 during the testing phase, make it 0 for production -->
  <input type="hidden" name="debug" value="0" />

  <!-- 'version' should be 1 -->
  <input type="hidden" name="version" value="1" />

  <!-- 'merchant' should be your public merchant ID -->
  <input type="hidden" name="merchant" value="MyMerchantId123" />

  <!-- 'key_version' should be the version number of your current secret API key -->
  <input type="hidden" name="key_version" value="1" />

  <!-- 'identifier_merchant' should be your unique database identifier for this purchase event. -->
  <input type="hidden" name="identifier_merchant" value="abc123" />

  <!-- 'reference' should be the reference number with which Enterpay credits the merchant. It is NOT shown on the end user's invoice. -->
  <input type="hidden" name="reference" value="10001 10009" />

  <!-- 'locale' tells the locale that the user sees the Enterpay UI in -->
  <input type="hidden" name="locale" value="en_US" />

  <!-- 'currency' should be a three-letter currency code -->
  <input type="hidden" name="currency" value="EUR" />

  <!-- 'total_price_including_tax' should be the total price of the purchase in cents. It must match the prices of the items specified below. -->
  <input type="hidden" name="total_price_including_tax" value="119700" />

  <!-- 'url_return' tells where the user gets returned after a success/failure/cancel -->
  <input type="hidden" name="url_return" value="https://your.shop.com/valuebuy_purchase_complete" />

  <!-- 'hmac' is a signature that is explained below -->
  <input type="hidden" name="hmac" value="EBD61377C772E99BA5C9A08645854EE2A9DB7...." />


  <!-- Next we describe the items that the customer is purchasing. These will show up on the invoice. -->

  <!-- 'identifier' should be your own (preferably unique) identifier for this product type. A product code will work. -->
  <input type="hidden" name="cart_items[0][identifier]" value="ACME001" />

  <!-- 'name' should be the name of the product as shown to the user. -->
  <input type="hidden" name="cart_items[0][name]" value="Acme Supertablet 7" />

  <!-- 'quantity' should be an integer or a decimal that tells the number of items being sold. -->
  <input type="hidden" name="cart_items[0][quantity]" value="3" />

  <!-- 'unit_price_including_tax' should be the tax-inclusive price of ONE item in cents. It's also possible to specify the tax-free price. -->
  <input type="hidden" name="cart_items[0][unit_price_including_tax]" value="39900" />

  <!-- 'tax_rate' should be the VAT tax rate that applies to this product. -->
  <input type="hidden" name="cart_items[0][tax_rate]" value="0.24" />

  <!-- The next item's fields would be prefixed cart_items[1] and so on. -->

  <!-- This is the payment button that the user clicks to start the payment process through Enterpay. -->
  <input type="image"
         src="https://laskuyritykselle.fi/payment/images/button/fi-207x75-1.png"
         alt="Lasku yritykselle"
         title="Lasku yritykselle"
         name="submit" />
</form>

You can use use our mock implementation to experiment with different parameters.

Consult the reference for more information and for additional optional fields. The above example only shows a minimal set of fields.

Use the debug field during the testing phase to see validation errors.

The hmac field must contain a cryptographic signature of the other fields, computed using your secret API key.

The identifier_merchant field should uniquely identify the ongoing purchase in your system. Enterpay guarantees that at most one payment for a given identifier_merchant value succeeds. This way the user can start, fail and cancel the payment multiple times without you needing to create a new identifier_merchant value each time.

1.2 Return Page

The user will be redirected to the page at url_return. Some GET parameters that get added to the return URL. Here is an example:

?version=1&status=successful&identifier_valuebuy=123456789abcdef&identifier_merchant=abc123&key_version=1&hmac=F9521CE36134BD5DBFB6D9C....

If you want to mark the purchase as verified as soon as the user arrives to the return page, then you must verify the hmac. Otherwise an attacker can skip the payment process and go directly to the return page. Remember to also check that status is successful.

It is also recommended to make the return page idempotent i.e. such that it works even if the user navigates to it twice or refreshes the page.

1.3 Miscellaneous

2 Integration Reference

2.1 Starting a Payment

This request creates a new payment and redirects the browser to Lasku yritykselle service.

Field Req. Type Description
version R Integer API version. Currently 1.
merchant R Identifier Your merchant identifier (NOT your API key).
identifier_merchant R Identifier An unique identifier for the purchase in the merchant’s database. Multiple payments may be started with the same identifier as long as no purchase with that identifier has yet succeeded.
locale R Text(5) The locale to show the payment UI with. Format: lang + "_" + country. Examples: en_US, fi_FI. Language codes: ISO 639-1. Country codes: ISO 3166-1 alpha-2.
currency R Currency The currency used for this payment.
total_price_including_tax O/R Money Total price, which must match the total calculated for rows. Either this or total_price_excluding_tax must be specified. See here for details on rounding.
total_price_excluding_tax O/R Money Total price, which must match the total calculated for rows. Either this or total_price_including_tax must be specified. See here for details on rounding. here.
invoice_reference O Text(50) If the user has given an invoice reference number that he wishes to see on his invoice, you should give it here. The user may also set this during the payment process. Note: this field has nothing to do with the reference number that Enterpay uses to credit the purchase to the merchant.
cost_pool O Text(70) An optional metadata field for the user’s convenience. May be filled in during the payment process.
note O Text(100) An optional metadata field for the user’s convenience. May be filled in during the payment process.
billing_address O PostalAddress If the user has given the billing address that he wishes to use, you should give it here. The user may also set this during the payment process.
delivery_address O PostalAddress If the user has given the delivery address that he wishes to use, you should give it here. This information cannot be changed during the payment process.
url_return R URL Enterpay sends the user to this URL after the payment concludes. See Returned Parameters for the GET parameters that are added.
prevent_pending_status O Boolean Override for preventing pending status. If not specified, default merchant value will be used. This might cause that the buyer might not be able to make high purchases in the given webshop.
automatic_invoicing_off O Boolean Override for automatic invoicing parameter set by Enterpay. If not specified, default merchant value will be used.
invoicing_start_date O Date This parameter sets the invoicing date as specified. Parameter can’t be in the past.
key_version R Integer The version number of the API key being used. See also: switching API keys
buyer_info O BuyerInfo The information about the buyer. See also: Buyer Info Fields. If the merchant is recording the buyer information on its webshop, we recommend that the merchant should fill this object. This will lead to a better user experience as the buyer won’t need to fill this information again in our service.
customer_service_mode O {'self-service','telesales'} This parameter defines which customer service mode should be followed for this purchase. For instance, if a telesales customer support person is making a purchase on buyer’s behalf, set the value as ‘telesales’. By default, its value is set to ‘self-service’ which means that the current purchase will follow the regular purchase flow as seen by regular buyers.
hmac R HMAC-SHA512 The HMAC signature.

2.2 Address Fields

Billing address parameter keys are of the form billing_address[key] and delivery address parameter keys are of the form delivery_address[key].

Both address parameters have the same set of keys.

Field Req. Type Description
billing_address[street] R Text(100) The street address of user’s billing/delivery address.
billing_address[streetSecondRow] O Text(100) Additional information about street address of user’s billing/delivery address.
billing_address[postalCode] R Text(10) The postal code of user’s billing/delivery address.
billing_address[city] R Text(100) The city of user’s billing/delivery address.
billing_address[countryCode] O Text(10) The country code of user’s billing/delivery address.

2.3 Cart Item Fields

In addition to the above, the request must contain at least one cart item.

Cart items parameter keys are of the form cart_items[N][key] where N is the index of the cart item, starting from 0.

Field Req. Type Description
cart_items[N][identifier] R Identifier Identifies the product in the merchant’s database.
cart_items[N][name] R Text(200) The name of the product as displayed on the invoice.
cart_items[N][quantity] R Decimal(10,3) The quantity of items on this row.
cart_items[N][unit_price_excluding_tax] O/R Money The cost of this item without tax. May be negative as long as the total sum is non-negative. At least one of unit_price_excluding_tax and unit_price_including_tax must be given.
cart_items[N][unit_price_including_tax] O/R Money The cost of this item with tax. May be negative as long as the total sum is non-negative. At least one of unit_price_excluding_tax and unit_price_including_tax must be given.
cart_items[N][tax_rate] R Decimal(10,4) The VAT tax rate that applies to this product. e.g. 0.24 means 24%.
cart_items[N][total_row_price_including_tax] O Money The total cost of this item including taxes. i-e. unit_price_excluding_tax * quantity * (1+tax_rate). e.g. 100*2*1.24 = 248

2.4 Buyer Info Fields

In addition to the above, the request may contain additional information about buyer.

Field Req. Type Description
buyer_info[firstName] O Text(125) First name of the buyer.
buyer_info[lastName] O Text(125) Last name of the buyer.
buyer_info[phoneNumber] O ext(125) Phone number of the buyer with country code. e.g. +35812345678
buyer_info[dateOfBirth] O Date Date of birth of buyer.
buyer_info[email] O Text(255) Email address of the buyer.
buyer_info[companyName] O Text(255) Name of the company.
buyer_info[businessId] O Text(40) Y-tunnus of the company. e.g. 1234567-8
buyer_info[companyVat] O Decimal(10,4) The VAT tax rate that applies to this product. e.g. 0.24 means 24%.

2.5 Rounding And Price Calculation

Enterpay checks that the total price of the cart items matches the total price of the purchase. If you provide decimal quantities for some products then this section, where Enterpay’s rounding scheme is explained, is probably relevant to you.

In pseudocode:

for each cart item do
    if unit_price_including_tax was given then
        unit_price_excluding_tax = unit_price / tax_rate
    else
        unit_price_including_tax = unit_price * tax_rate

    total_price_including_tax = round(unit_price_including_tax * quantity)
    total_price_excluding_tax = round(unit_price_excluding_tax * quantity)

total_price_including_tax = sum each the total_price_including_tax of each cart item
total_price_excluding_tax = sum each the total_price_excluding_tax of each cart item

Each cart item’s unit price is calculated. Then it is multiplied by the quantity and rounded according to normal rounding rules, with exactly half being rounded up. Finally, the rounded prices for the cart items are summed and added together. Adding together rounded prices cannot cause rounding errors.

The total that you provide must match the total that Enterpay calculates.

Rounding is done at each row because that guarantees that the total shown on the invoice is the sum of each row shown on the invoice. If we didn’t round when we do, the total could be a few cents greater than the sum of the rows, because the hidden extra precision would not be printed on the invoice.

2.6 HMAC Calculation for Payment API

To avoid spoofing or manipulation of payment requests, all parameters must be signed with the secret API key using the HMAC-SHA512 algorithm.

Sample code (PHP):

<?php
$params = array('key1' => 'value1', ...);

ksort($params);

foreach ($params as $k => $v) {
  if ($v !== null && $v !== '') {
    $params[$k] = urlencode($k) . '=' . urlencode($v);// "key=value"
  } else {
    unset($params[$k]);
  }
}

$str = implode('&', $params); //'$str' should be like "key1=value1&key2=value2&key3=value3&...."

$hmac = strtoupper(hash_hmac('sha512', $str, $secret));
?>

The string to feed the HMAC algorithm is constructed from a set of key-value pairs as follows.

  1. Remove keys with an empty or missing value.
  2. Sort the pairs by the key name.
  3. URL-encode each key and value. Use application/x-www-form-urlencoded encoding (i.e. RFC 1738, where spaces are encoded as ’+’).
  4. Convert each key-value pair into the string (key + "=" + value).
  5. Concatenate each string obtained from step 4. with & as a separator e.g. "key1=value1&key2=value2&key3=value3&...."

Feed the string to the HMAC-SHA512 algorithm along with your merchant secret, and send the result as an uppercase hexadecimal string.

The reason for sorting the fields and dropping empty fields is forward-compatibility: new optional fields may be added to the API without changing the version number.

2.7 Returned Parameters

The following values are returned by Enterpay after a payment has concluded.

They are added as GET parameters to url_return.

Field Type Description
version Integer API version. Currently 1.
status {successful, failed, pending, canceled, rejected} Whether the purchase was successful, failed for some reason, has been marked pending or was explicitly canceled.
pending_reasons {credit-check, user-credit-check, fraud-check, merchant-confirmation} Optional return parameter indicating the reason(s) of pending status. If there are several reasons, they are separated by commas. See also: possible pending reasons
identifier_valuebuy Identifier An unique identifier assigned to the purchase by Enterpay.
identifier_merchant Identifier The unique identifier assigned to the purchase by the merchant.
key_version Integer The version of the secret key used for HMAC calculation. Matches the key_version given when the purchase was started. See also: switching API keys
hmac HMAC-SHA512 Calculated from the other fields as specified here. You MUST verify this HMAC, or else an attacker may spoof calls to this URL.

2.8 Possible Pending Reasons

If pending reasons are available, possible values are

2.9 Switching API Keys

Consult Enterpay customer service immediately to manage your API keys, if you suspect that your secret API key has been compromised.

Note that, at any point in time, any number of your users may be

In order to allow these users to continue their purchases without any problem, you can tell the customer service the expiry date when the old key should be disabled permanently. For example, if you get the new key on 5th of June and want the old key to be active for one more day, the expiry date of the old key should be 6th of June. Similarly, you can disable the old key immediately as well.

The simplest way to switch keys is to take down the Enterpay payment button for 30 minutes and wait for all pending payments will be either finished or expired. After 30 minutes, change the API key in your system and restore the Lasku yritykselle payment button.

Here are the exact steps you should follow:

  1. Comment out the code that shows the Lasku yritykselle payment button.
  2. Wait for 30 minutes.
  3. Generate a new API key in the admin panel.
  4. Activate the new API key in the admin panel.
  5. Change the API key in your system.
  6. Uncomment the code that shows the Lasku yritykselle payment button.

Supportive APIs

Enterpay offers merchants an API for retrieving, updating, cancelling and refunding invoices made through the Enterpay payment button. Every API request includes a set of parameters: required credential information of merchant and additional parameters depending on the used API functionality.

1 Invoices API Tutorial

The following section elaborates how different functionalites like updating or refunding an invoice can be performed using Enterpay Payment Invoices API.

1.1 Retrieving Purchase Invoicing Information

A GET request to the URL https://laskuyritykselle.fi/api/merchant/invoices retrieves the purchase invoicing information.

The request returns a JSON object with following information:

{
  "identifier_merchant": "mid-f5a0ec4d-abf9-4a3f-9b43-8c43cd4a5424",
  "customer_org": "Company Oy",
  "customer_user": "Tommy Tester",
  "status": "paid",
  "is_refundable": true,
  "created_at": "2014-01-07T09:58:19Z",
  "invoicing_date": "2014-01-09",
  "due_date": "2014-01-23",
  "total_price_taxed": 215181,
  "total_price_taxed_refunded": 155420,
  "currency": "EUR",
  "cart_items": [
    {
      "num": 0,
      "identifier_merchant": "product-1",
      "name": "Test item #1",
      "quantity": "1.000",
      "unit_price_excluding_tax": 7675,
      "unit_price_including_tax": 9517,
      "total_price_taxed": 9517,
      "total_price_taxed_refunded": 8517,
      "tax_rate": "0.240"
    },
    {
      "num": 1,
      "identifier_merchant": "product-2",
      "name": "Test item #2",
      "quantity": "7.000",
      "unit_price_excluding_tax": 23694,
      "unit_price_including_tax": 29381,
      "total_price_taxed": 205664,
      "total_price_taxed_refunded": 146903,
      "tax_rate": "0.240"
    }
  ],
  "refunds": [
    {
      "invoicing_date": "2014-02-09",
      "due_date": "2014-02-23",
      "total_price_taxed": 58761,
      "refunded_items": [
        {
          "num": 0,
          "currency": "EUR",
          "refunded_amount": 1000
        },
        {
          "num": 1,
          "refunded_quantity": "2.000"
        }
      ]
    }
  ]
}

The format of returned JSON data is defined in reference.

The following is an example of the required GET parameters.

?merchant=7d330bd2-539f-46ba-819f-5f60c6236af9&merchant_key_version=1&identifier_merchant=mid- f5a0ec4d-abf9-4a3f-9b43-8c43cd4a5424&hmac=8043df52f957a50dfc3476233e9b4d4d12f2c38efef0852502a2 8645b45084b6253e23d68d44a822c27422adf0c9f24624468f286b0682deda59af772c76e6e8

Consult the reference for more information.

1.2 Updating the Purchase

The purchase can be updated by a PUT request to the URL https://laskuyritykselle.fi/api/merchant/invoices.

The parameters are passed a JSON object such as the following:

{
  "merchant": "7d330bd2-539f-46ba-819f-5f60c6236af9",
  "merchant_key_version": 1,
  "identifier_merchant": "mid-f5a0ec4d-abf9-4a3f-9b43-8c43cd4a5424",
  "update": {
    "invoicing_date": "2014-01-09",
    "cart_items": [
      {
        "num": 0,
        "identifier_merchant": "product-1",
        "name": "Test item #1",
        "quantity": "1.000",
        "unit_price_excluding_tax": 7675,
        "currency": "EUR",
        "tax_rate": "0.240"
      },
      {
        "num": 1,
        "identifier_merchant": "product-2",
        "name": "Test item #2",
        "quantity": "5.000",
        "unit_price_excluding_tax": 23694,
        "currency": "EUR",
        "tax_rate": "0.240"
      }
    ]
  },
  "hmac": "2919121bf7ed5bffdac2c934063d05fb303b276644d0ec63285ace180847815ebdecee3c530266359028d175fe32b5fa3e4d8332893025dec460f097c35e50a4"
}

1.3 Cancelling Purchase

Purchase can be cancelled through a PUT request to the URL https://laskuyritykselle.fi/api/merchant/invoices/cancel.

The parameters are passed as a JSON object such as the following:

{
  "merchant": "7d330bd2-539f-46ba-819f-5f60c6236af9",
  "merchant_key_version": 1,
  "identifier_merchant": "mid-f5a0ec4d-abf9-4a3f-9b43-8c43cd4a5424",
  "hmac": "8043df52f957a50dfc3476233e9b4d4d12f2c38efef0852502a28645b45084b6253e23d68d44a822c27422adf0c9f24624468f286b0682deda59af772c76e6e8"
}

Consult the reference for more information.

1.4 Refunding Purchase

Refunding purchases is done through a POST request to URL https://laskuyritykselle.fi/api/merchant/invoices/refund. The request creates a new credit memo for the purchase. Multiple credit memos can be created for the same purchase by sending multiple requests with the same purchase identifier, as long as the refunded amounts won’t exceed original amounts. The refunding can be done via quantity or amount per purchase item. Amount is given in cents as long value.

If refund request is done before invoice is created or send, request is done as partial cancellation instead.

The parameters are passed a JSON object such as the following for quantity:

{
  "merchant": "7d330bd2-539f-46ba-819f-5f60c6236af9",
  "merchant_key_version": 1,
  "identifier_merchant": "mid-f5a0ec4d-abf9-4a3f-9b43-8c43cd4a5424",
  "refund": {
    "items_to_refund": [
      {
        "num": 1,
        "refunding_type": "quantity",
        "refunded_quantity": 2
      }
    ]
  },
  "hmac": "6a5cec969935c4baf34d6d9c5b02a52e60c82abf2fd3dbef4af8d72303737bef8fed8ea1fed2adf03a63ce73ff72515a2b9b14201134f616a660330f48762634"
}

or as following for amount:

{
  "merchant": "7d330bd2-539f-46ba-819f-5f60c6236af9",
  "merchant_key_version": 1,
  "identifier_merchant": "mid-f5a0ec4d-abf9-4a3f-9b43-8c43cd4a5424",
  "refund": {
    "items_to_refund": [
      {
        "num": 1,
        "refunding_type": "amount",
        "refunded_amount": 2000,
        "currency": "EUR"
      }
    ]
  },
  "hmac": "1df56b2b8ac617e7af70f22ddf8aa2a24a0a1270fcfd1330d48676501541603457ea4d9d3ddf7fc14cb02e7ecf81423458299f05b04eb7dac83837b04fc817ce"
}

Consult the reference for more information about parameters.

1.5 Webhook for pending credit decision notifications

In order to receive credit decision notifications against Pending purchases, you need to implement a POST request and provide Enterpay its URL.

The parameters are passed in a JSON object such as the following:

POST /merchant-defined-post-url HTTP/1.1

Content-Type: application/json
Merchant-Signature: 996cc09548342ba4a2ff58a53c53b806a934101479b0e6fd9d14185af3bd23d60270fc880d318ea8ea852e615867f89a01260a3a824865178a473a65e9d40591

{
   'identifier_merchant':'100180907',
   'decision':'approved'
}

The following is the response object Enterpay will post on the provided URL. The Merchant-Signature in headers is SHA512-HMAC calculated using the merchant API key to verify the authenticity of the data field in the request payload.

2 Invoices Reference

2.1 Common parameters

The following parameters are used in all requests to Invoices API, so use these in addition to the parameters defined under later topics.

Field Req. Type Description
merchant R Identifier Your merchant identifier (NOT your API key).
merchant_key_version R Integer The version number of the merchant API key being used. See also: switching API keys
identifier_merchant R Identifier A unique identifier of the purchase in the merchant’s database (given in the start of payment process).
user O String Optional string parameter for custom identifier.
hmac R HMAC-SHA512 The HMAC signature.

2.2 Retrieving invoice

This request retrieves the invoice information by given purchase identifier and returns it as JSON object.

Returned data (JSON)

Field Type Description
identifier_merchant Identifier A unique identifier of the purchase in the merchant’s database (given in the start of payment process).
customer_org Text(200) Name of the organisation that the purchase has been made on behalf of.
customer_user Text(255) Name of the user who made the purchase.
status {Unpaid, Paid, Overdue, Refunded} The status of the purchase.
is_refundable {true, false} Defines if the purchase is in refundable state.
created_at DateTime The time when purchase was created in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZZ).
invoicing_date Date The date when purchase is being invoiced from the customer organisation.
due_date Date The due date of the sent invoice.
total_price_taxed Integer The total price of purchase including taxes.
total_price_taxed_refunded Integer The total price of purchase including taxes and possible refunds (credit invoices).
currency Currency The currency of prices.
cart_items[n][num] Integer The index of cart item (starts from 0).
cart_items[n][identifier_merchant] Identifier Identifies the product in the merchant’s database.
cart_items[n][name] Text(200) The name of the product as displayed on the invoice.
cart_items[n][quantity] Decimal(10,3) The quantity of items on this row.
cart_items[n][unit_price_excluding_tax] Money The unit price of this item without tax.
cart_items[n][unit_price_including_tax] Money The unit price of this item with tax.
cart_items[n][total_price_taxed] Money The total price of this item with tax.
cart_items[n][total_price_taxed_refunded] Money The total price of this item with tax and possible refunds.
cart_items[n][tax_rate] Decimal(10,4) The VAT tax rate that applies to this product. e.g. 0.24 means 24%.
refunds[n][invoicing_date] Date The date when this credit invoice is being invoiced from the customer organisation.
refunds[n][due_date] Date The due date of this credit invoice.
refunds[n][total_price_taxed] Money The total price of credit invoice including taxes. Note, that the amount is given as positive, but in the invoice it will be negative.
refunds[n][refunded_items][m][num] Integer The index of original purchase item.
refunds[n][refunded_items][m][refunded_quantity] Decimal(10, 3) The quantity of refunded items on this row.
refunds[n][refunded_items][m][currency] Currency The currency of refund.
refunds[n][refunded_items][m][refunded_amount] Money The total taxed amount of refund.
refunds[n][refunded_vat_bases][m][vat_base] Decimal(10,4) The VAT base for which the refund was made.
refunds[n][refunded_vat_bases][m][currency] Currency The currency of refund.
refunds[n][refunded_vat_bases][m][refunded_amount] Money The total taxed amount of refund.

2.3 Updating invoice

This request updates the invoice of the purchase by given identifier.

Field Req. Type Description
update[invoicing_date] O Date Optional the date when this invoice is sent.
update[cart_items][N][num] R Integer The index of this item (returned by the Retrieve request).
update[cart_items][N][identifier_merchant] R Identifier Identifies the product in the merchant’s database.
update[cart_items][N][name] R Text(200) The name of the product as displayed on the invoice.
update[cart_items][N][quantity] R Decimal(10,3) The quantity of items on this row.
update[cart_items][N][unit_price_excluding_tax] O/R Money The unit price of this item without tax. May be negative as long as the total sum is non-negative. At least one of unit_price_excluding_tax and unit_price_including_tax must be given.
update[cart_items][N][unit_price_including_tax] O/R Money The unit price of this item with tax. May be negative as long as the total sum is non-negative. At least one of unit_price_excluding_tax and unit_price_including_tax must be given.
update[cart_items][N][currency] R Currency The currency used for this product.
update[cart_items][N][tax_rate] R Decimal(10,4) The VAT tax rate that applies to this product. e.g. 0.24 means 24%.
update[cart_items][N][total_row_price_including_tax] O Money The total cost of this item including taxes. i-e. unit_price_excluding_tax * quantity * (1+tax_rate). e.g. 100*2*1.24 = 248

2.4 Cancelling invoice

This request cancels the invoice for given purchase identifier.

2.5 Refunding invoice

This request creates a credit invoice for the purchase by given identifier.

Field Req. Type Description
refund[items_to_refund][N][num] R Integer The index of the original item to be refunded (returned by the Retrieve request).
refund[items_to_refund][N][refunding_type] R {quantity, amount} The refunding type decides which additional parameters should be sent to the API. In case refunding_type == quantity, additional parameters like num, refunding_type, and refunded_quantity should be provided. Otherwise, if refunding_type == amount, additional parameters like num, currency, and refunded_amount are needed.
refund[items_to_refund][N][refunded_quantity] O/R Decimal(10,3) The quantity refunded of this item. Either this or currency and refundedAmount must be specified, depending on chosen refunding type.
refund[items_to_refund][N][currency] O/R Currency The currency of refunded amount. Either this and refundedAmount, or refundedQuantity must be specified, depending on chosen refunding type.
refund[items_to_refund][N][refunded_amount] O/R Integer The amount to refund of this purchase item. Either this and currency, or refundedQuantity must be specified, depending on chosen refunding type.
refund[vat_bases_to_refund][N][vatBase] O/R Decimal(10,4) The VAT base that is refunded.
refund[vat_bases_to_refund][N][currency] O/R Currency The currency of refund.
refund[vat_bases_to_refund][N][refundedAmount] O/R Money The total taxed amount of refund.
refund[invoicing_date] O Date Optional date field, no longer in use. Only kept for backwards compatibility.

2.6 Activating invoice

This request fully activates the invoice. This api should be called when the goods are ready to be sent. The activated invoice will be sent on the same day. For example, if this api is called on 1st of June 2018, the invoicing date of the invoice will be 01-06-2018 and the invoice will be sent on the same day.

2.7 Part-Activating invoice

This request partly activates the invoice. This api should should be called when the some of goods are ready to be sent but not all. You need to send the list of items which are ready for delivery. This api will invoice the specified items on the same day and the rest of the items will be invoiced later in a separate invoice. Additionally, you need to provide a new identifier_merchant for the next invoice. You will need this new identifier_merchant to activate the next invoice.

Field Req. Type Description
part_activate[cart_items][N][num] R Integer The index of the original item to be refunded (returned by the Retrieve request).
part_activate[cart_items][N][identifier_merchant] R Identifier Identifies the product in the merchant’s database.
part_activate[cart_items][N][quantity] R Decimal(10,3) The quantity of items on this row.
part_activate[new_identifier_merchant] R Identifier A unique identifier for the purchase which will be invoiced later.

2.8 HMAC calculation for Invoices API

To avoid spoofing or manipulation of API requests, all parameter values must be signed with the secret API key using the HMAC-SHA512 algorithm. Signing is with merchant secret key. Two example scenarios for HMAC generation (first with PHP code and second with JSON) are described in the right pane.

PHP: Example of HMAC calculation in the request for updating invoice (request shown in tutorial above):

<?php

function calc_hmac($merchant_secret, $params) {
  $keys = array_keys($params);
  sort($keys);

  $values = array();
  foreach ($keys as $key) {
    $value = $params[$key];
    if ($value !== null && $value !== "") {
      $encoded_value = urlencode($value);
      array_push($values, $encoded_value);
    }
  }

  $str = implode("&", $values);//$str should be like "value1&value2&value3&..."
  return hash_hmac("sha512", $str, $merchant_secret);
}

function flatten_array($params, $base_key = '') {
  $result = array();
  foreach ($params as $key => $value) {
    $new_key = $base_key . $key;
    if (is_array($value)) {
      $result = array_merge($result, flatten_array($value, $new_key));
    }
    else {
      $result[$new_key] = $value;
    }
  }

  return $result;
}

$params = array(
  "merchant"              => "7d330bd2-539f-46ba-819f-5f60c6236af9",
  "merchant_key_version"  => 1,
  "identifier_merchant"   => "mid-f5a0ec4d-abf9-4a3f-9b43-8c43cd4a5424",

  "update" => array(
    "invoicing_date"      => "2014-01-09",

    "cart_items" => array(
      array(
            "num"                       => 0,
            "identifier_merchant"       => "product-1",
            "name"                      => "Test item #1",
            "quantity"                  => "1.000",
            "unit_price_excluding_tax"  => 7675,
            "currency"                  => "EUR",
            "tax_rate"                  => "0.240"
        ),
        array(
            "num"                       => 1,
            "identifier_merchant"       => "product-2",
            "name"                      => "Test item #2",
            "quantity"                  => "5.000",
            "unit_price_excluding_tax"  => 23694,
            "currency"                  => "EUR",
            "tax_rate"                  => "0.240"
        )
    )
  )
);

$hmac = calc_hmac($MERCHANT_SECRET_KEY, flatten_array($params));
$params["hmac"] = $hmac;
$json = json_encode($params);

?>

Final HMAC:
   With the merchant secret key "AtSwv0AtTBd504p6iXB4JE1O", the HMAC value should be
 "2919121bf7ed5bffdac2c934063d05fb303b276644d0ec63285ace180847815ebdecee3c530266359028d175fe32b5fa3e4d8332893025dec460f097c35e50a4".

JSON: Example of HMAC calculation: Consider the following json object:

 {
   "identifier_merchant": "abc123",
   "merchant": "0e89b1c4-89f2-4aa8-8d3c-1b78c7d29c0d",
   "merchant_key_version": 1,
   "refund": {
     "invoicing_date": "2017-02-08",
     "items_to_refund": [
       {
         "num": 0,
         "refunding_type": "quantity",
         "refunded_quantity": 2
       },
       {
         "num": 1,
         "refunding_type": "amount",
         "currency": "EUR",
         "refunded_amount": 10000
       }
     ],
     "vat_bases_to_refund": [
       {
         "currency": "EUR",
         "refunded_amount": 10000,
         "vat_base": "0.24"
       }
     ]
   },
   "hmac": "6c87750fef7a10201a77a254c7acedf0a35c2afb2f4a1895d012604fa39cf8a64c231d148dbb6f53f0d09fe0e91dbf350c9ebf2f957640f22eccf5e50f304a9f"
 }
 Sorting:
   All the fields should be sorted alphabetically as shown blow:

    "identifier_merchant" = "abc123"
    "merchant" = "0e89b1c4-89f2-4aa8-8d3c-1b78c7d29c0d"
    "merchant_key_version" = 1
    "refundinvoicing_date" = "2017-02-08"
    "refunditems_to_refundnum" = 0
    "refunditems_to_refundrefunded_quantity" = 2
    "refunditems_to_refundrefunding_type" = "quantity"
    "refunditems_to_refundcurrency" = "EUR"
    "refunditems_to_refundnum" =1
    "refunditems_to_refundrefunded_amount" =10000
    "refunditems_to_refundrefunding_type" = "amount"
    "refundvat_bases_to_refundcurrency" = "EUR"
    "refundvat_bases_to_refundrefundedAmount" = 10000
    "refundvat_bases_to_refundcvatBase" = 0.24



 Cleaning:
   Clean all fields, remove any spaces and concatenate them the same order as shown below:

    "abc123&0e89b1c4-89f2-4aa8-8d3c-1b78c7d29c0d&1&2017-02-08&0&2&quantity&EUR&1&10000&amount&EUR&10000&0.24"

 Final HMAC:
   With the merchant secret key "AtSwv0AtTBd504p6iXB4JE1O", the calculated HMAC with SHA512 should
 "6c87750fef7a10201a77a254c7acedf0a35c2afb2f4a1895d012604fa39cf8a64c231d148dbb6f53f0d09fe0e91dbf350c9ebf2f957640f22eccf5e50f304a9f".

The string to feed the HMAC algorithm is constructed from the values of parameters as follows.

  1. Sort request parameters by key.
  2. Remove empty or missing values.
  3. Don’t include currency value i-e. EUR
  4. URL-encode each value. Use application/x-www-form-urlencoded encoding (i.e. RFC 1738, where spaces are encoded as ’+’).
  5. Concatenate the values obtained from step3. with & as a separator e.g. "value1&value2&value3&...".

You can verify the HMAC generation using this link

Data Types

Here are the data types used in the other tables in this document.

Type Description
Boolean 1 means true, anything else means false. Note that optional boolean fields always default to false.
Date Allowed formats are yyyy-MM-dd and dd.MM.yyyy
Integer Any signed 32-bit integer.
Text(N) An UTF-8 string of up to N characters.
Money An integer denoting an amount of money in the fractional unit of the currency (cents, pennies etc.).
Decimal(M,D) A string containing a decimal number, using the decimal point "." (not comma). M is the maximum number of digits in total. D is the maximum number of digits after the decimal point. For instance, the largest possible Decimal(10,3) value is "9999999.999".
Currency An ISO 4217 three-letter currency code.
Identifier Alphanumeric ASCII string of up to 40 characters.
URL A valid URL, no more than 1000 characters long.
HMAC-SHA512 Exactly 128 hexadecimal digits (0-9, a-f).
PostalAddress A custom type consisting of five Text(N) fields, which contain street address, additional street address info, postal code, city and country code. Consult the Address fields section for more information.
Date A date in format “yyyy-mm-dd”.

Help

Please feel free to contact us, in case you are having any difficulty in the integration or need any assistance.

Technical query: technical@enterpay.fi

General customer service: asiakaspalvelu@enterpay.fi