Skip to content

Latest commit

 

History

History
158 lines (134 loc) · 4.32 KB

purchase_v2.adoc

File metadata and controls

158 lines (134 loc) · 4.32 KB
Raw

Purchase API V2

Service Description

The purchase API provides information about a purchases made through the iZettle point-of-sale.

Scopes

The Purchase API implements the following scopes:

  • READ:PURCHASE

  • WRITE:PURCHASE

Scope of this documentation

Version 2 of the purchase API is identical to version 1 in all regards except for payments. This document will only focus on those differences. For all other aspects of the API you should consult the version 1 documentation

Endpoints

The following endpoints exist in version 2. Any endpoints that exist in version 1 but are not represented in version 2 can still be accessed through the version 1 API.

All parameters and behaviours, except for the representation of payments, are the same as for version 1

Purchase history

GET /purchases/v2

Purchase details

GET /purchase/v2/{purchaseUUID}

Payment representations in the purchase

Version 1

In the version 1 API, payments are represented in three separate lists

  • cardPayments

  • cashPayments

  • payments

The reason for this is historical, but suffice it to say that card payments always goes into the cardPayments list, cash payments always into the cashPayments list and all other payments into the generic payments list.

example: Version 1 purchase with one card, one cash and one invoice payment
{
  ...
  "cardPayments": [
    {
      ...
    }
  ],
  "cashPayments": [
    {
      ...
    }
  ],
  "payments": [
    {
      "type": "IZETTLE_INVOICE",
      ...
    }
  ],
  ...
}

Version 2

The version 2 API guarantees that all payments are represented in the generic payments list only. The cardPayments and cashPayments lists do not exists in version 2. The example purchase from above would look like this:

example: Version 2 purchase with one card, one cash and one invoice payment
{
  ...
  "payments": [
    {
      "type": "IZETTLE_CARD",
      ...
    },
    {
      "type": "IZETTLE_CARD_ONLINE",
      ...
    },
    {
      "type": "IZETTLE_CASH",
      ...
    },
    {
      "type": "IZETTLE_INVOICE",
      ...
    },
  ],
  ...
}

In addition to IZETTLE_CARD, IZETTLE_CARD_ONLINE, IZETTLE_CASH and IZETTLE_INVOICE, there is also payment types of SWISH, VIPPS, MOBILE_PAY, PAYPAL, STORE_CREDIT and CUSTOM.

Payment attributes

The version 1 cardPayment and cashPayment data types contain all parameters required to represent a card or a cash payment. The generic payment data type only contain a few generic parameters such as uuid, amount and type. To be able to represent all types of payments it has an attributes map that contain all payment type specific data such as maskedPan or cardType for card payments or handedAmount for cash payments.

Other payments such as Swish, Vipps and MobilePay don’t have attributes. They will only be represented by a uuid, an amount and a type.

example of cash payment
{
  "uuid": "ce90dc90-dcaa-11e6-87a4-0cd119752226",
  "amount": 1000,
  "type": "IZETTLE_CASH",
  "attributes": {
    "handedAmount": 1000
  }
}
example of card payment
"purchaseUUID": "6HbDrnUNRji5iniGikNLiQ",
"amount": 2000,
"gratuityAmount": 0,
...
{
  "uuid": "165b88a0-07a3-11e6-9dae-43c30f1bff5b",
  "amount": 2000,
  "gratuityAmount": 0,
  "type": "IZETTLE_CARD",
  "attributes": {
    "transactionStatusInformation": "EC00",
    "cardPaymentEntryMode": "EMV",
    "maskedPan": "476173******0119",
    "installmentAmount": null,
    "referenceNumber": "AU54FYHW7X",
    "nrOfInstallments": 0,
    "cardType": "VISA",
    "terminalVerificationResults": "0080088000",
    "applicationIdentifier": "A0000000031010",
    "applicationName": "Visa Credit"
  }
}
example of invoice payment
{
  "uuid": "d65ebf50-979e-11e7-9f72-df4bb64e0df9",
  "amount": 2960,
  "type": "IZETTLE_INVOICE",
  "attributes": {
    "orderUUID": "d5b126c4-979e-11e7-9af0-a3d2806c42a1",
    "invoiceNr": "iz37",
    "dueDate": "2017-10-12"
  }
}

Note: gratuityAmount corresponds to the tipping amount in the purchase. This feature is not available in all countries. When the gratuityAmount is set, the card payment amount will include the gratuity amount.