Two Checkout API (1.0)

Download OpenAPI specification:Download

This API is for creating orders to complete an online purchase at your store.

Environments

Testing

https://sandbox.api.two.inc/v1

Production

https://api.two.inc/v1

Authentication

X-API-Key

You will obtain two different keys, one for testing and another for production.

Your API keys enables others to act on your behalf if they are able to obtain them, so make sure to keep them safe. Your API key is not to be shared with anyone, including in your source control service, client-side code, in public chatrooms and so on.

The API key is applied in the request header:

Example

GET /something
X-API-Key: secret_test_abcdef12345

The HTTPS protocol is enforced, HTTP calls will return an error.

Key Generation API Keys have the following structure:

secret_<env>_<key>

where env is determined by the environment (prod for production, test for test environments), and key is a random, URL-safe, 64-bit encoded text string containing 32 random bytes.

Security Scheme Type API Key
Header parameter name: X-API-Key

Order intent

Create order intent

The endpoint enables the merchant to check in advance whether an invoice payment is applicable as a payment method for the Buyer.

Two will perform a risk assessment and credit check using the data provided in the OrderIntent before a boolean is returned as a result.

If line_items are provided Two will be able to do a more accurate assessment and the approval rate will in general increase.

Request
Request Body schema: application/json
required
object (Buyer)
currency
required
string

Currency code in ISO 4217 format. E.g. "NOK".

gross_amount
required
string
invoice_type
string
Enum: "FUNDED_INVOICE" "DIRECT_INVOICE" "CARD"
required
Array of objects (LineItem)
merchant_id
required
string <uuid>
merchant_short_name
string or null

Deprecated. Use merchant_id where possible.

Responses
201

Created

400

Bad Request

404

Not Found

post/order_intent
Request samples
application/json
{
  • "invoice_type": "DIRECT_INVOICE",
  • "gross_amount": "200",
  • "currency": "GBP",
  • "line_items": [
    ],
  • "buyer": {
    },
  • "merchant_id": "YOUR_MERCHANT_ID_HERE",
  • "merchant_short_name": "test"
}
Response samples
application/json
{
  • "approved": true,
  • "buyer": {
    },
  • "currency": "GBP",
  • "decline_reason": null,
  • "gross_amount": "200.00",
  • "id": "196d5b61-52b6-4691-bfb0-c43b6583445b",
  • "invoice_type": "DIRECT_INVOICE",
  • "line_items": [
    ],
  • "merchant_id": "YOUR_MERCHANT_ID_HERE",
  • "merchant_short_name": "test"
}

Get the order intent

Endpoint for fetching an OrderIntent.

Request
path Parameters
id
required
string

ID of the order intent

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Responses
200

OK

400

Bad Request

get/order_intent/{id}
Request samples
curl -i -X GET \
  https://sandbox.api.two.inc/v1/order_intent/:id \
  -H 'X-API-Key: string'
Response samples
application/json
{
  • "approved": true,
  • "buyer": {
    },
  • "currency": "GBP",
  • "decline_reason": null,
  • "gross_amount": "200.00",
  • "id": "196d5b61-52b6-4691-bfb0-c43b6583445b",
  • "invoice_type": "DIRECT_INVOICE",
  • "line_items": [
    ],
  • "merchant_id": "YOUR_MERCHANT_ID_HERE",
  • "merchant_short_name": "test"
}

Order

Cancel the order

Endpoint to cancel the order and void the invoice.

Request
path Parameters
id
required
string

ID of the order to be cancelled

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Responses
200

OK

202

Accepted. Order has already been cancelled.

400

Bad Request

404

Not Found

post/order/{id}/cancel
Request samples
curl -i -X POST \
  https://sandbox.api.two.inc/v1/order/:id/cancel \
  -H 'X-API-Key: string'
Response samples
application/json
{
  • "error_code": "INVALID_STATE_CHANGE_ERROR",
  • "error_details": "",
  • "error_message": "Invalid state change"
}

Create order

Endpoint for creating an order.

Request
header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Request Body schema: application/json
required
object (Address)
required
object (Buyer)
buyer_department
string
buyer_project
string
currency
required
string

Currency code in ISO 4217 format. E.g. "NOK".

Enum: "NOK" "SEK" "GBP" "EUR" "USD"
date_fulfilled
string <date-time>

ISO 8601 datetime of when the order was fulfilled. Format: "yyyy-mm-ddThh:mm:ss"

discount_amount
string
discount_rate
string
gross_amount
required
string
object (InvoiceDetails)

Invoice details are provided by:

  • The merchant via Merchant Portal for Order.invoice_type == DIRECT_INVOICE
  • Two Bank or a 3rd-party bank for Order.invoice_type == FUNDED_INVOICE
  • Void for Order.invoice_type == CARD
invoice_type
required
string
Default: "DIRECT_INVOICE"

The type of invoice.

  • FUNDED_INVOICE: Two will handle the invoice and transfer the funds to the merchant as per the factoring agreement. The invoice_details field will be populated by Two.
  • DIRECT_INVOICE: Two generates and sends the invoice to the customer based on the bank account provided by the merchant.
  • CARD: Not publicly available.
Enum: "FUNDED_INVOICE" "DIRECT_INVOICE" "CARD"
required
Array of objects (LineItem) [ 0 .. 2000 ] items

List of the line items that constitute the order.

merchant_additional_info
string >= 0 characters

Additional info the merchant can set on the order. Will appear on invoice.

merchant_id
string
merchant_order_id
required
string
merchant_reference
string [ 0 .. 255 ] characters

Field set by merchant for adding a reference to be used internally by the merchant. Does not appear on invoice.

object

List of urls hosted by the merchant.

net_amount
required
string
order_note
string
original_order_id
string
recurring
boolean
Default: false

If set to true, an invoice will be generated periodically according to the specification provided in recurring_details.

object (RecurringDetails)

Not implemented

required
object (Address)
object (ShippingDetails)
tax_amount
required
string
tax_rate
required
string
tracking_id
string
Responses
201

CREATED

400

Bad Request

post/order
Request samples
application/json
{
  • "currency": "GBP",
  • "invoice_type": "DIRECT_INVOICE",
  • "gross_amount": "400",
  • "net_amount": "360",
  • "discount_amount": "0.0",
  • "discount_rate": "0.00",
  • "tax_amount": "40",
  • "tax_rate": "0.01",
  • "buyer": {
    },
  • "line_items": [
    ],
  • "merchant_order_id": "1232",
  • "merchant_urls": {},
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "invoice_details": {
    }
}
Response samples
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "currency": "GBP",
  • "date_created": "2021-12-20T16:34:37.104629",
  • "date_fulfilled": null,
  • "date_updated": "2021-12-20T16:34:37.266925",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "event_log_url": "https://two.inc",
  • "external_order_id": "a1c67de6-6aa6-4ca7-9d1d-bdc8e048ad4f",
  • "external_order_status": "OFFERED",
  • "fixed_fee": null,
  • "gross_amount": "400.00",
  • "id": "93724c9c-d849-49ce-9567-7fe4dc1b72f7",
  • "invoice_details": {
    },
  • "invoice_type": "DIRECT_INVOICE",
  • "line_items": [
    ],
  • "merchant_additional_info": null,
  • "merchant_id": "3fdf14e7-1afd-409d-aeb5-c2462327807e",
  • "merchant_order_id": "1232",
  • "merchant_reference": null,
  • "merchant_short_name": "testtillitnor",
  • "merchant_urls": {
    },
  • "net_amount": "360.00",
  • "order_intent_id": null,
  • "order_note": null,
  • "original_order_id": null,
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "shipping_address": {
    },
  • "shipping_details": null,
  • "state": "UNVERIFIED",
  • "status": "APPROVED",
  • "tax_amount": "40.00",
  • "tax_rate": null,
  • "total_fee": null
}

Edit order

Edit a previously created order.

Request
path Parameters
id
required
string

The ID of the order to be retrieved

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Request Body schema: application/json
required
object (Address)
buyer_department
string
buyer_project
string
currency
required
string

Currency code in ISO 4217 format. E.g. "NOK".

Enum: "NOK" "SEK" "GBP" "EUR" "USD"
discount_amount
required
string
discount_rate
required
string
gross_amount
required
string
object (InvoiceDetails)

Invoice details are provided by:

  • The merchant via Merchant Portal for Order.invoice_type == DIRECT_INVOICE
  • Two Bank or a 3rd-party bank for Order.invoice_type == FUNDED_INVOICE
  • Void for Order.invoice_type == CARD
invoice_type
required
string
Default: "DIRECT_INVOICE"

The type of invoice.

  • FUNDED_INVOICE: Two will handle the invoice and transfer the funds to the merchant as per the factoring agreement. The invoice_details field will be populated by Two.
  • DIRECT_INVOICE: Two generates and sends the invoice to the customer based on the bank account provided by the merchant.
  • CARD: Not publicly available.
Enum: "FUNDED_INVOICE" "DIRECT_INVOICE" "CARD"
required
Array of objects (LineItem) [ 0 .. 2000 ] items

List of the line items that constitute the order.

merchant_additional_info
required
string >= 0 characters

Additional info the merchant can set on the order. Will appear on invoice.

merchant_reference
required
string [ 0 .. 255 ] characters

Field set by merchant for adding a reference to be used internally by the merchant. Does not appear on invoice.

net_amount
required
string
order_note
string
recurring
boolean
Default: false

If set to true, an invoice will be generated periodically according to the specification provided in recurring_details.

object (RecurringDetails)

Not implemented

required
object (Address)
required
object (ShippingDetails)
tax_amount
required
string
tax_rate
required
string
Responses
200

OK

400

Bad Request

404

Not Found

422

Unprocessable Entity

put/order/{id}
Request samples
application/json
{
  • "currency": "NOK",
  • "invoice_type": "DIRECT_INVOICE",
  • "gross_amount": "200",
  • "net_amount": "180",
  • "discount_amount": "0",
  • "discount_rate": "0.0",
  • "tax_amount": "20",
  • "tax_rate": "0.1",
  • "buyer_department": "Okonomi",
  • "buyer_project": "project 12",
  • "line_items": [
    ],
  • "merchant_reference": "merchant reference",
  • "merchant_additional_info": "add info",
  • "invoice_details": {
    },
  • "shipping_details": {},
  • "order_note": "ship details",
  • "billing_address": {
    },
  • "shipping_address": {
    }
}
Response samples
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "currency": "GBP",
  • "date_created": "2021-12-20T16:34:37.104629",
  • "date_fulfilled": null,
  • "date_updated": "2021-12-20T16:34:37.266925",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "event_log_url": "https://two.inc",
  • "external_order_id": "a1c67de6-6aa6-4ca7-9d1d-bdc8e048ad4f",
  • "external_order_status": "OFFERED",
  • "fixed_fee": null,
  • "gross_amount": "400.00",
  • "id": "93724c9c-d849-49ce-9567-7fe4dc1b72f7",
  • "invoice_details": {
    },
  • "invoice_type": "DIRECT_INVOICE",
  • "line_items": [
    ],
  • "merchant_additional_info": null,
  • "merchant_id": "3fdf14e7-1afd-409d-aeb5-c2462327807e",
  • "merchant_order_id": "1232",
  • "merchant_reference": null,
  • "merchant_short_name": "testtillitnor",
  • "merchant_urls": {
    },
  • "net_amount": "360.00",
  • "order_intent_id": null,
  • "order_note": null,
  • "original_order_id": null,
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "shipping_address": {
    },
  • "shipping_details": null,
  • "state": "UNVERIFIED",
  • "status": "APPROVED",
  • "tax_amount": "40.00",
  • "tax_rate": null,
  • "total_fee": null
}

Get list of orders

NOTE - uses /v2/. Endpoint for accessing all orders made by a given merchant or buyer.

Request
header Parameters
Buyer-Id
string <UUID>
Merchant-id
string <UUID>
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Responses
200

OK

400

Bad Request

404

Not Found

get/orders
Request samples
curl -i -X GET \
  https://test.api.two.inc/v2/orders \
  -H 'Buyer-Id: string' \
  -H 'Merchant-id: string' \
  -H 'X-API-Key: string'
Response samples
application/json
[
  • {
    }
]

Get order details

Retrieve a previously created order.

Request
path Parameters
id
required
string

The ID of the order to be retrieved

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Responses
200

OK

404

Not Found

get/order/{id}
Request samples
curl -i -X GET \
  https://sandbox.api.two.inc/v1/order/:id \
  -H 'X-API-Key: string'
Response samples
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "currency": "GBP",
  • "date_created": "2021-12-20T16:34:37.104629",
  • "date_fulfilled": null,
  • "date_updated": "2021-12-20T16:34:37.266925",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "event_log_url": "https://two.inc",
  • "external_order_id": "a1c67de6-6aa6-4ca7-9d1d-bdc8e048ad4f",
  • "external_order_status": "OFFERED",
  • "fixed_fee": null,
  • "gross_amount": "400.00",
  • "id": "93724c9c-d849-49ce-9567-7fe4dc1b72f7",
  • "invoice_details": {
    },
  • "invoice_type": "DIRECT_INVOICE",
  • "line_items": [
    ],
  • "merchant_additional_info": null,
  • "merchant_id": "3fdf14e7-1afd-409d-aeb5-c2462327807e",
  • "merchant_order_id": "1232",
  • "merchant_reference": null,
  • "merchant_short_name": "testtillitnor",
  • "merchant_urls": {
    },
  • "net_amount": "360.00",
  • "order_intent_id": null,
  • "order_note": null,
  • "original_order_id": null,
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "shipping_address": {
    },
  • "shipping_details": null,
  • "state": "UNVERIFIED",
  • "status": "APPROVED",
  • "tax_amount": "40.00",
  • "tax_rate": null,
  • "total_fee": null
}

Refund order

Endpoint for refunding an order.

Request
path Parameters
id
required
string

ID of the order to be refunded

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Request Body schema: application/json
amount
string or null
currency
string or null
initiate_payment_to_buyer
boolean
Array of objects or null (LineItem)
reason
string or null
Responses
201

REFUNDED

400

Bad Request

404

Not Found

post/order/{id}/refund
Request samples
application/json
{
  • "amount": "200",
  • "currency": "NOK",
  • "initiate_payment_to_buyer": true,
  • "line_items": [
    ],
  • "reason": "Damage"
}
Response samples
application/json
{
  • "amount": "200",
  • "credit_note_url": "http://example.com",
  • "currency": "NOK",
  • "external_refund_id": "868dc35e-9783-4d5e-b81f-c3433aa927fd",
  • "id": "b05bbf1a-1be5-4aed-b518-129dd12860ba",
  • "initiate_payment_to_buyer": true,
  • "line_items": [
    ],
  • "reason": "Damage",
  • "refund_no": 123
}

Update order when delivered

Optional order update: Set the order status to DELIVERED.

Request
path Parameters
id
required
string

ID of the order to be marked as delivered

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Responses
200

OK

400

Bad Request

404

Not Found

post/order/{id}/delivered
Request samples
curl -i -X POST \
  https://sandbox.api.two.inc/v1/order/:id/delivered \
  -H 'X-API-Key: string'
Response samples
application/json
{
  • "error_code": "INVALID_STATE_CHANGE_ERROR",
  • "error_details": null,
  • "error_message": "Invalid State Change"
}

Update order when fulfilled

Set the order status to FULFILLED (similar to "capture" for cards).

The invoice will be issued and distributed it to the customer.

Only for partial capture, the post body is as below.

Request
path Parameters
id
required
string

ID of the order to be marked as fulfilled

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Request Body schema:
object (Order)
object (Order)
Responses
200

OK

400

Bad Request

404

Not Found

post/order/{id}/fulfilled
Request samples
{ }
Response samples
application/json
{
  • "billing_address": {
    },
  • "buyer": {
    },
  • "buyer_department": null,
  • "buyer_project": null,
  • "currency": "GBP",
  • "date_created": "2021-08-17T06:55:35.514586",
  • "date_fulfilled": null,
  • "date_updated": "2021-12-20T17:06:23.719639",
  • "decline_reason": null,
  • "discount_amount": "0.00",
  • "discount_rate": "0.000000",
  • "event_log_url": "https://two.inc",
  • "external_order_id": "a1c67de6-6aa6-4ca7-9d1d-bdc8e048ad4f",
  • "external_order_status": "ACCEPTED",
  • "fixed_fee": null,
  • "fulfilled_order": {
    },
  • "gross_amount": "10000.00",
  • "id": "340cfe64-7ce2-49eb-bc10-585cc069e67d",
  • "invoice_details": {
    },
  • "invoice_type": "DIRECT_INVOICE",
  • "line_items": [],
  • "merchant_additional_info": "",
  • "merchant_id": "9d565b95-93f4-4166-a143-f61bfe85d85e",
  • "merchant_order_id": "3557a390-d8c2-4947-bc35-ecad391ad294",
  • "merchant_reference": "610bdb32-9a44-41e0-829f-f5f49b2dbd49",
  • "merchant_short_name": "finnno",
  • "merchant_urls": {},
  • "net_amount": "10000.00",
  • "order_intent_id": null,
  • "order_note": null,
  • "original_order_id": null,
  • "other_partial_orders": [ ],
  • "percentage_fee": null,
  • "recurring": false,
  • "recurring_details": null,
  • "refunds": null,
  • "remained_order": {
    },
  • "shipping_address": {
    },
  • "shipping_details": null,
  • "state": "VERIFIED",
  • "status": "PARTIAL",
  • "tax_amount": "0.00",
  • "tax_rate": null,
  • "total_fee": null
}

Invoice

Create a group invoicing ID

Endpoint to create an group invoicing ID to group subsequent order invoices.

Request
header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Request Body schema: application/json
required
object
object
invoice_email
required
string
schedule
required
string
Enum: "MONTHLY" "WEEKLY" "DAILY" "YEARLY"
Responses
201

Created

post/invoicing_group
Request samples
application/json
{
  • "invoice_email": "invoice@company.com",
  • "schedule": "MONTHLY",
  • "buyer_company": {
    },
  • "invoice_details": {
    }
}
Response samples
application/json
{
  • "invoicing_group_id": "321231132-32312-321213"
}

Generate a pdf invoice for an order.

Endpoint for downloading the invoice of a fulfilled order.

Request
path Parameters
lang
string

Specify language to generate PDF [en_US, nb_NO]

order_id
required
string

ID of the order

v
string <original>

Optional parameter v=original to download the original invoice and not the credit note (if any)

Responses
200

OK

400

Bad Request

404

Not Found

get/invoice/{order_id}/pdf
Request samples
curl -i -X GET \
  https://sandbox.api.two.inc/v1/invoice/:order_id/pdf
Response samples
application/json
{
  • "error_code": "PROVIDER_ERROR",
  • "error_details": null,
  • "error_message": "Could not find provider"
}

Provide invoice details

Invoice details are provided by:

  • The merchant via Merchant Portal for Order.invoice_type == DIRECT_INVOICE
  • Two Bank or a 3rd-party bank for Order.invoice_type == FUNDED_INVOICE
  • Void for Order.invoice_type == CARD

The merchant can provide the invoice_details when creating an order, when updating an order, or by using this endpoint directly.

Request
path Parameters
id
required
string
header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Request Body schema: application/json
due_date
string or null <date>
due_in_days
required
integer

Number of days from the invoice is created until the due date. E.g. 30

invoice_number
string or null
invoicing_group_id
string or null
object (BankAccount)
payment_reference
string or null
payment_reference_message
required
string

Text that will be attached to the payment in order for the merchant to reconcile the payment.

payment_reference_ocr
required
string

A string of numbers that will be attached to the payment in order for the merchant to reconcile the payment. E.g. "KID-nummer" in Norway.

payment_reference_type
string or null
Responses
200

OK

400

Bad Request

404

Not Found

422

Unprocessable Entity

post/order/{id}/invoice_details
Request samples
application/json
{
  • "payee": {
    },
  • "payment_reference": "string",
  • "payment_reference_type": "string",
  • "payment_reference_message": "string",
  • "payment_reference_ocr": "string",
  • "due_in_days": 0,
  • "invoice_number": "string",
  • "invoicing_group_id": "string",
  • "due_date": "2019-08-24"
}
Response samples
application/json
{
  • "error_code": "MERCHANT_MISSING_PAYEE_ACCOUNT_ERROR",
  • "error_details": null,
  • "error_message": "Merchant does not have a linked account"
}

Update group invoicing ID scheduling period

Endpoint to update the period length in which invoices are grouped.

Request
path Parameters
invoicing_group_id
required
string <UUID>

Group invoicing ID

header Parameters
X-API-Key
required
string <secret_{ENV}_{API_KEY}>
Request Body schema: application/json
schedule
string
Enum: "MONTHLY" "DAILY" "WEEKLY" "YEARLY"
Responses
200

OK

put/invoicing_group/{invoicing_group_id}
Request samples
application/json
{
  • "schedule": "WEEKLY"
}

Company

Lookup company address

Endpoint for accessing company addresses from national service

Request
path Parameters
country_code
required
string

Country code e.g NO, GB

id
required
string

ID of the company

Responses
200

OK

400

Bad Request

get/{country_code}/company/{id}/address
Request samples
curl -i -X GET \
  https://sandbox.api.two.inc/v1/:country_code/company/:id/address
Response samples
application/json
{
  • "address": {
    }
}
Copyright © 2021 Tillit AS. All rights reserved.