In cooperation with
Paytrail

Paylink API

Paylink API – Orders

Paylink API offers the following functions for managing orders:

EndpointAction
GET api/v1/ordersList orders
POST api/v1/ordersAdd order
GET api/v1/orders/{orderId}Get order
POST api/v1/orders/{orderId}/deliverSend payment request
PUT api/v1/orders/{orderId}Edit order
DELETE api/v1/orders/{orderId}Delete order

List orders

List all orders in descending order by date of creation.

Parameters

page Optional
Page from which orders will be fetched. API will return 50 entries in a single page.
GET api/v1/orders
cURL
curl -i -X GET -H "Authorization:Token API-KEY" 'https://test.app.paylink.fi/api/v1/orders?page=1'
Response
{
  "has_more":false,
  "data":[
    {
      "id":5735,
      "display_id":"1030",
      "order_number_prefix":"PL",
      "due_date":"2020-08-25",
      "customer_locale":"fi_FI",
      "status":"pending",
      "notes":"Order notes",
      "info_before": "Info before line items",
      "info_after": "Info after line items",
      "customer_id":null,
      "email":"matti.meikalainen@example.com",
      "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
      "created_at":"2020-08-14T15:06:14.000+03:00",
      "updated_at":"2020-08-14T15:06:14.000+03:00",
      "address":{
        "firstname":"Matti",
        "lastname":"Meikäläinen",
        "company":null,
        "company_id":null,
        "address":"Testikatu 1",
        "city":"Helsinki",
        "postcode":"00100",
        "phone":"0401234567",
        "country":"FI"
      },
      "items":[
        {
          "title":"Test product",
          "unit_base_price_cents":81,
          "unit_tax_cents":19,
          "unit_total_price_cents":100,
          "tax_rate_id":"fi_standard",
          "total_base_price_cents":81,
          "total_tax_cents":19,
          "total_price_cents":100,
          "quantity":1,
          "product_id":null
        }
      ]
    }
    ...
  ]
}

Add order

Add new order

Parameters

email Required
Email address
customer_locale Optional
Language, fi_FI or en_US. Default fi_FI
notes Optional
Internal order notes that will not be visible to customers
info_before Optional
Info before line items in the PDF invoice
info_after Optional
Info after line items in the PDF invoice
due_date Optional
Due date in format YYYY-MM-DD (e.g. 2024-04-15).
reference Optional
Order reference. Has to be valid and unique bank reference if transaction-specific settlements are enabled (Settings > Paytrail > Transaction-specific settlements). Otherwise can be string containing letters and numbers.
display_id Optional
Order number that is displayed to the customer. Has to be unique. Will be generated if left blank.
order_number_prefix Optional
Order number prefix that can be used to separate Paylink orders from other sources. Order numbers consist of prefix and order number (display_id). For example, if prefix is "P-" and order number 123, the final order number will be "P-123". Prefix can contain letters, numbers and dashes. Default prefix can be set in the settings (Settings > Orders > Order number prefix).
customer_id Optional
Customer ID
address Required
Billing address. If some field is unknown, dash (-) can be used as placeholder.
Parameters
address.firstname Required
First name
address.lastname Required
Last name
address.company Optional
Company
address.company_id Optional
Business ID
address.city Required
City
address.postcode Required
Postcode
address.phone Optional
Phone number
address.country Required
Country as two-letter country code (e.g. FI)
items Required
Order items. Order total minimum is 0.65 €.
Parameters
items.title Required
Name
items.unit_total_price_cents Required
Unit price in cents including tax
items.quantity Required
Quantity
items.tax_rate_id Required
Tax rate ID, fi_standard (24 %, 25,5 % from 1.9.2024), fi_intermediate (14 %), fi_reduced (10 %) or fi_zero (0 %)
items.tax_rate_pct Optional
Tax rate in percents. If left out, tax_rate_id will determine the value
items.product_id Optional
Product ID
POST api/v1/orders
cURL
curl -i -X POST \
   -H "Authorization:Token API-KEY" \
   -H "Content-Type:application/json" \
   -d \
'{
  "email": "matti.meikalainen@example.com",
  "customer_locale": "fi_FI",
  "notes": "Order notes",
  "info_before": "Info before line items",
  "info_after": "Info after line items",
  "due_date": "2020-08-25",
  "reference": "10003",
  "display_id": 1000,
  "order_number_prefix": "PL",
  "customer_id": null,
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "address": "Testikatu 1",
    "postcode": "00100",
    "city": "Helsinki",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Test product",
      "unit_total_price_cents": 100,
      "quantity":1,
      "tax_rate_id":"fi_standard",
      "tax_rate_pct":25.5,
      "product_id": null
    }
  ]
}' \
 'https://test.app.paylink.fi/api/v1/orders'
Response
{
  "id": 5737,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "Order notes",
  "info_before": "Info before line items",
  "info_after": "Info after line items",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Test product",
      "unit_base_price_cents": 80,
      "unit_tax_cents": 20,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "tax_rate_pct": 25.5,
      "total_base_price_cents": 80,
      "total_tax_cents": 20,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Get order

Get order details.

Parameters

orderId Required
Order ID
GET api/v1/orders/{orderId}
cURL
curl -i -X GET \
   -H "Authorization:Token API-KEY" \
 'https://test.app.paylink.fi/api/v1/orders/1'
Response
{
  "id": 1,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "Order notes",
  "info_before": "Info before line items",
  "info_after": "Info after line items",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Test product",
      "unit_base_price_cents": 81,
      "unit_tax_cents": 19,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "total_base_price_cents": 81,
      "total_tax_cents": 19,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Send payment request

Send payment request to the customer via email.

Parameters

orderId Required
Order ID
POST api/v1/orders/{orderId}/deliver
cURL
curl -i -X POST \
   -H "Authorization:Token API-KEY" \
   -H "Content-Type:application/json" \
   -d \
'' \
 'https://test.app.paylink.fi/api/v1/orders/1/deliver'
Response
{
  "id": 1,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "Order notes",
  "info_before": "Info before line items",
  "info_after": "Info after line items",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Test product",
      "unit_base_price_cents": 81,
      "unit_tax_cents": 19,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "total_base_price_cents": 81,
      "total_tax_cents": 19,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Edit order

Edit order details.

Note! Only notes can be edited for paid orders.

Parameters

orderId Required
Order ID
See other parameters at Add order »
PUT api/v1/orders/{orderId}
cURL
curl -i -X PUT \
   -H "Authorization:Token API-KEY" \
   -H "Content-Type:application/json" \
   -d \
'{
  "notes": "New notes"
}' \
 'https://test.app.paylink.fi/api/v1/orders/1'
Response
{
  "id": 1,
  "display_id": "1000",
  "order_number_prefix": "PL",
  "due_date": "2020-08-25",
  "customer_locale": "fi_FI",
  "status": "pending",
  "notes": "New notes",
  "info_before": "Info before line items",
  "info_after": "Info after line items",
  "customer_id": null,
  "email": "matti.meikalainen@example.com",
  "payment_url": "https://test.app.paylink.fi/pay/0ba5e6c045ac4e0cfd",
  "created_at": "2020-08-17T12:06:41.000+03:00",
  "updated_at": "2020-08-17T12:06:41.000+03:00",
  "address": {
    "firstname": "Matti",
    "lastname": "Meikäläinen",
    "company": null,
    "company_id": null,
    "address": "Testikatu 1",
    "city": "Helsinki",
    "postcode": "00100",
    "phone": "0401234567",
    "country": "FI"
  },
  "items": [
    {
      "title": "Test product",
      "unit_base_price_cents": 81,
      "unit_tax_cents": 19,
      "unit_total_price_cents": 100,
      "tax_rate_id": "fi_standard",
      "total_base_price_cents": 81,
      "total_tax_cents": 19,
      "total_price_cents": 100,
      "quantity": 1,
      "product_id": null
    }
  ]
}

Delete order

Delete order.

Note! Paid orders cannot be deleted.

Parameters

orderId Required
Order ID
DELETE api/v1/orders/{orderId}
cURL
curl -i -X DELETE \
   -H "Authorization:Token API-KEY" \
 'https://test.app.paylink.fi/api/v1/orders/1'
Next: Paylink API - Products »
Get started
Try demo

In cooperation with

Paylink

Contact us

BitBot Oy
asiakaspalvelu@paylink.fi

koodiasuomesta_gray