Two Instalment API (1.0.0)

Download OpenAPI specification:Download

Sequence Diagram

Sequence Diagram

Overview and usage:

This API is designed for the purpose of creating and managing repayment accounts and repayment plans.

A repayment account stores the billing details of buyers, which are used to issue invoices and follow up for incoming payments.

A business can have one or multiple repayment accounts, each of which should have a corresponding account record in the merchant's system.

A repayment plan represents the receivable purchased from merchants and is expected to be paid by buyers over time. It is a collection of instalments, and the instalments of different repayment plans can be invoiced together.

The Repayment Plans fulfilled via this API will be invoiced and distributed to the Buyers the following 3-36 months.

Instalments created by the same merchant for the same repayment account will be invoiced together, typically on the 1st day of each calendar month, to allow Buyers to pay them together with a single payment.

You will receive a net payout from us upon fulfilment of the repayment plan, at the end of your negotiated payout cycle.

The Instalment API provides the following features:

  • Creation and update of repayment accounts, including their contact details
  • Creation and fulfilment of new repayment plans
  • Cancellation of existing repayment plans to prevent invoicing of uninvoiced instalments
  • Credit check of buyers to understand the terms under which a specific repayment plan amount is supported
  • Preview of repayment plans with a breakdown of instalments
  • Polling of the funding and fulfilment status of repayment plans
  • Crediting of specific repayment plans

Step 1: Identify the Business for Which You're Creating the Account

  • To help your buyers select their company's legal name, address, and national ID. You can use the Search API endpoint to search for the company's name, which is documented here: Search Company Name
  • Additionally, you can use the company address endpoint to access the address information, which is available here: Address Lookup

Step 2: Creation of repayment account

  • The repayment account is created by the merchant using details inputted by their buyer using the create repayment account POST /account endpoint
  • You can create multiple repayment accounts for the same buyer_company if you would like each to receive seperate invoices.

Step 3: Credit check the planned repayment plan amount

  • Once you have the total order amount being placed by the buyer. Call the credit check POST /credit-check endpoint
  • The API will then respond with under what conditions Two can provide an approved funding decision for this buyer and the given amount
  • The API response will provide you with the maximum and minimum terms, and a maximum monthly amount that can be offered to the buyer

Step 4: Preview the repayment plan to see the instalment breakdown

This step is optional: You might want to show a breakdown of one or more tentative repayment plans to your buyer before they commit to one of them.

  • Preview the repayment plans to show to the buyer through the create preview POST /preview endpoint
  • The API response will provide a list of instalments, including issue dates and amounts and tax subtotals, to be presented to your buyer
  • This endpoint can be polled multiple times with different options but recommended to only call within the limitations of the credit risk response.

Step 5: Create the repayment plan and commit the buyer to pay back in instalments.

  • A repayment plan can then be created by defining the following required terms through the create repayment plan POST /plan endpoint :
  • The number of payment periods associated with this set of terms. (Number Of Periods [ 1 ... 36 ])
  • The time slice over which payments are to be made as part of a repayment plan. (currently we only support Monthly cadence)

Step 6: Poll the repayment status

  • You are expected to poll the repayment status GET /status endpoint until the API responds with an "Accepted" or "Rejected" funding decision
  • Once funding has been "Accepted" proceed to fulfilment

Step 7: Fulfil the repayment plan

  • Using the PUT /fulfilment endpoint you will finalise the repayment plan and initiate the payout process
  • The next business day your payout will incorporate this repayment plan minus the agreed fees.
  • If you have negotiated a payout cadence that is not DAILY, you will receive the payout for this repayment plan minus the fees at the end of your current payout cycle.

Sandbox testing

Trigger Future Invoice

Only available in sandbox

This endpoint can be called to trigger invoice generation and distribution with a specified cut off date in sandbox and can be used to test invoicing behaviour when integrating with the API. Normal invoicing rules will run and factor in:

  • merchant-specific rules for the invoicing date within the billing cycle
  • repayment account configuration rules for the due date
  • invoicing grouping keys (if any) for specific plans for the repayment account

The endpoint will trigger invoicing as if it is running on the specified cut off date. This means it will identify any instalments with an invoicing date between today and the given cut off date (inclusive) and generate invoices for those instalments according to the factors mentioned above.

As the invoicing process is asynchronous, there will be a short delay after hitting this endpoint before invoices are distributed. This delay will typically be 2 minutes.

Securityapi-key
Request
Request Body schema: application/json
required
account_id
required
string <uuid> (Account Id)

The repayment account to be invoiced.

cut_off
required
string <date> (Cut Off)

The future date at which the invoicing logic should be triggered to run on.

invoice_grouping_key
string (Invoice Grouping Key) non-empty

Optional key specified in each repayment plan to group instalments into invoices.

Responses
200

Successful Response

403

Forbidden

404

Not Found

422

Validation Error

post/testing/send-invoices
Request samples
application/json
{
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "cut_off": "2019-08-24",
  • "invoice_grouping_key": "string"
}
Response samples
application/json
{
  • "invoice_ids": [
    ]
}

Repayment Plans

Create Repayment Plan

Create a new repayment plan.

Securityapi-key
Request
header Parameters
Idempotency-Key
required
string (Idempotency-Key) [ 1 .. 36 ] characters

A unique value generated by the client which the server uses to recognize subsequent retries of the same request

Request Body schema: application/json
required
account_id
required
string (Account Id) [ 1 .. 40 ] characters ^[a-zA-Z0-9\-_]+$

The repayment account that this repayment plan should be invoiced to.

required
object (Representative)
consent_date
required
string <date> (Consent Date)

The date that the buyer consented and committed to the repayment plan.

currency
required
string (CurrencyCode)

The currency of the repayment plan. Applies to all monetary amounts related to the repayment plan.

Enum: "GBP" "NOK" "SEK" "EUR" "USD"
description
required
string (Description)
required
Array of objects (Line Items) non-empty
reference
required
string (Reference) [ 1 .. 40 ] characters ^[a-zA-Z0-9\-_]+$

The merchant's ID or reference for this repayment plan.

required
object (ShippingAddress)

Shipping addresses have a more relaxed validation for country code, which is only checked against ISO 3166.

required
Array of objects (TaxSubtotals)
required
object (Terms)

The terms describing how the repayment plan should be split into instalments over time. Instalments are automatically created when the repayment plan is fulfilled.

total_repayment_amount
required
string <decimal> (Total Repayment Amount) ^-?[0-9]+(\.[0-9]{0,2})?

The total gross amount of the repayment plan, owed by the buyer when the RepaymentPlan is created. Other amounts, like tax and net, are derived from LineItem. The total_repayment_amount should be equal to the sum over the repayment_amount field for all instalments.

Responses
200

Successful Response

201

Created

422

Validation Error

post/plan
Request samples
application/json
{
  • "reference": "string",
  • "description": "string",
  • "total_repayment_amount": "string",
  • "tax_subtotals": [
    ],
  • "currency": "GBP",
  • "consent_date": "2019-08-24",
  • "line_items": [
    ],
  • "account_id": "string",
  • "buyer_representative": {
    },
  • "shipping_address": {
    },
  • "terms": {
    }
}
Response samples
application/json
{
  • "id": "string",
  • "reference": "string",
  • "description": "string",
  • "total_repayment_amount": "string",
  • "tax_subtotals": [
    ],
  • "currency": "GBP",
  • "consent_date": "2019-08-24",
  • "line_items": [
    ],
  • "account_id": "string",
  • "buyer_representative": {
    },
  • "shipping_address": {
    },
  • "terms": {
    },
  • "invoice_grouping_key": "string",
  • "instalments": [
    ]
}

Get Repayment Plan

Securityapi-key
Request
path Parameters
repayment_plan_id
required
string <uuid> (Repayment Plan Id)
Responses
200

Successful Response

422

Validation Error

get/plan/{repayment_plan_id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "reference": "string",
  • "description": "string",
  • "total_repayment_amount": "string",
  • "tax_subtotals": [
    ],
  • "currency": "GBP",
  • "consent_date": "2019-08-24",
  • "line_items": [
    ],
  • "account_id": "string",
  • "buyer_representative": {
    },
  • "shipping_address": {
    },
  • "terms": {
    },
  • "invoice_grouping_key": "string",
  • "instalments": [
    ]
}
Update Repayment Plan
Update repayment plan.


Securityapi-key 
Request 
path Parameters
repayment_plan_id
required
string <uuid>  (Repayment Plan Id) 
 
Request Body schema: application/json
required
invoice_grouping_key
string (Invoice Grouping Key)   non-empty 
Optional key specified in each repayment plan to group instalments into invoices.


 
Responses 
204
Successful Response


404
Not Found


422
Validation Error


patch/plan/{repayment_plan_id}
Request samples 
application/json
{
  • "invoice_grouping_key": "string"
}
Response samples 
application/json
{
  • "description": "string",
  • "code": "ERROR"
}
Get Repayment Plan Status
Securityapi-key 
Request 
path Parameters
repayment_plan_id
required
string <uuid>  (Repayment Plan Id) 
 
Responses 
200
Successful Response


422
Validation Error


get/plan/{repayment_plan_id}/status
Request samples 
Response samples 
application/json
{
  • "funding_status": "PENDING",
  • "fulfilment_status": "NOT_INITIATED",
  • "cancelled_amount": "string",
  • "invoiced_amount": "string",
  • "total_repayment_amount": "string",
  • "on_recourse": true,
  • "credit_decline_reason": "string",
  • "recourse_decline_reason": "string"
}
Get Repayment Plan Invoice Details
Securityapi-key 
Request 
path Parameters
repayment_plan_id
required
string <uuid>  (Repayment Plan Id) 
 
Responses 
200
Successful Response


422
Validation Error


get/plan/{repayment_plan_id}/invoices
Request samples 
Response samples 
application/json
{
  • "plan_id": "string",
  • "instalments": [
    ]
}
Cancel Repayment Plan
Securityapi-key 
Request 
path Parameters
repayment_plan_id
required
string <uuid>  (Repayment Plan Id) 
 
header Parameters
Idempotency-Key
required
string (Idempotency-Key)   [ 1 .. 36 ] characters 
A unique value generated by the client which the server uses to recognize subsequent retries of the same request


 
Request Body schema: application/json
required
cancel_reason
string (CancellationReason) 
 Default:  "TERMINATED"
Documents the reason for cancelling remaining instalments of a repayment plan.


Cancelling a repayment plan for any reason only cancels instalments in the
plan that do not yet have invoices.


TERMINATED is used by default if not explicitly provided.


    

  • TAX_CHANGES: Sales tax (such as VAT) rules change part-way through a
repayment plan and you need to re-create the remainder of the repayment
plan using the new tax rates and amounts.
    • 

  • CREDIT_LIMITATION: You intend to repurchase the repayment plan from Two
when we are unable to fund new repayment plans for a buyer so you can, for
example, continue to send the buyer a single invoice for all repayment
plans.
    • 

  • WRONG_DETAILS: The repayment plan has incorrect details and you intend to
recreate the repayment plan with the correct details. Note that this
excludes incorrect contact details for the repayment account, which can be
updated using the repayment account endpoints without cancelling the
repayment plan.
    • 

  • MIGRATION: The repayment plan has errors introduced while migrating
repayment plan tracking from external systems to the Two service and you
intend to recreate it without errors.
    • 

  • TERMINATED (default): Repurchase a repayment plan from Two, or termination
of a repayment plan for other reasons. There is no expectation to recreate
the repayment plan at a later date.
    • 



 Enum: "TAX_CHANGES" "CREDIT_LIMITATION" "WRONG_DETAILS" "MIGRATION" "TERMINATED"  
cancelled_at
required
string <date-time>  (Cancelled At) 
 
Responses 
200
Successful Response


422
Validation Error


put/plan/{repayment_plan_id}/cancellation
Request samples 
application/json
{
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "cancel_reason": "TERMINATED"
}
Response samples 
application/json
{
  • "id": "string",
  • "cancelled_at": "2019-08-24T14:15:22Z",
  • "cancelled_repayment_amount": "string",
  • "currency": "GBP",
  • "cancel_reason": "TERMINATED"
}
Fulfill Repayment Plan
Requests that Two marks the repayment plan as fulfilled.


This endpoint will submit a request for Two to mark the repayment plan as fulfilled (the HTTP 202 response code
indicates that Two has successfully received the request to fulfil this repayment plan). Note that fulfilment in
Two's systems will happen asynchronously, so your integration should check the repayment plan fulfilment_status
using the repayment plan status endpoint before marking the repayment plan as fulfilled (or fulfilled by Two) in
your own system.


    

  • Before the fulfilment request is received for a given repayment plan, fulfilment_status in the repayment plan
status endpoint will show as NOT_INITIATED.
    • 

  • Once the request has been received, but before it is considered fulfilled by Two, the status endpoint's
fulfilment_status will be marked as PENDING.
    • 

  • When the fulfilment request has been completed in Two's systems, fulfilment_status will be SUCCEEDED.
    • 

  • It is possible for fulfilment_status to show as FAILED if the credit decision for the plan has expired and Two
has reassessed the buyer for this plan and can no longer support this repayment plan.
    • 



Securityapi-key 
Request 
path Parameters
repayment_plan_id
required
string <uuid>  (Repayment Plan Id) 
 
Request Body schema: application/json
invoice_grouping_key
string (Invoice Grouping Key)   non-empty 
Optional but non-empty grouping key to put instalments into separate invoices


 
Responses 
202
Successful Response


422
Validation Error


put/plan/{repayment_plan_id}/fulfilment
Request samples 
application/json
{
  • "invoice_grouping_key": "string"
}
Response samples 
application/json
null
Create Repayment Plan Preview
Request a preview of a repayment plan based on key features of a plan including term length and total amount.


Securityapi-key 
Request 
Request Body schema: application/json
required
required
Array of objects (TaxSubtotals) 
 
required
object (Terms) 
Defines key aspects of a repayment plan, such as the period over which instalments are created and the number of
instalments as part of that plan.


 
total_repayment_amount
required
string <decimal>  (Total Repayment Amount) ^-?[0-9]+(\.[0-9]{0,2})?
Total amount the buyer will be expected to pay over the entire repayment plan.


 
Responses 
200
Successful Response


422
Validation Error


post/plan/preview
Request samples 
application/json
{
  • "total_repayment_amount": "string",
  • "tax_subtotals": [
    ],
  • "terms": {
    }
}
Response samples 
application/json
{
  • "terms": {
    },
  • "instalments": [
    ],
  • "total_repayment_amount": "string",
  • "tax_subtotals": [
    ]
}
Update Instalment
Securityapi-key 
Request 
path Parameters
instalment_id
required
string <uuid>  (Instalment Id) 
 
repayment_plan_id
required
string <uuid>  (Repayment Plan Id) 
 
Request Body schema: application/json
required
description
required
string (Description)   <= 500 characters 
New description for the given instalment.


 
Responses 
204
Successful Response


422
Validation Error


put/plan/{repayment_plan_id}/instalment/{instalment_id}
Request samples 
application/json
{
  • "description": "string"
}
Response samples 
application/json
{
  • "detail": [
    ]
}
Repayment Accounts
Create Repayment Account
Creates a repayment account for use with repayment plan invoicing.


When a repayment plan is created, an existing repayment account must be referenced. Then, whenever an instalment is
invoiced the referenced repayment account is used to determine the billing details for the invoice. Updating a
repayment account will affect subsequent invoices only.


Securityapi-key 
Request 
header Parameters
Idempotency-Key
required
string (Idempotency-Key)   [ 1 .. 36 ] characters 
A unique value generated by the client which the server uses to recognize subsequent retries of the same request


 
Request Body schema: application/json
required
required
object (Account Representative) 
Contact details of person responsible for the repayment account.


 
required
object (Address) 
 
required
object (Buyer Company) 
The buyer company associated with this repayment account.


 
due_in_days
integer (Due In Days) 
The number of days beyond the issue date that an invoice created for this account will be due. Defaults to 14 days if not set explicitly.


 
invoice_cc_emails
Array of strings <email>  (Invoice Cc Emails) 
An array of additional email addresses to send invoices to in the CC field. If no addresses in CC are required, this should be left as an empty array.


 
invoice_email
required
string <email>  (Invoice Email) 
The email that will receive invoices issued for this repayment account.


 
Responses 
200
Successful Response


201
Created


422
Validation Error


post/account
Request samples 
application/json
{
  • "buyer_company": {
    },
  • "billing_address": {
    },
  • "invoice_email": "user@example.com",
  • "invoice_cc_emails": [
    ],
  • "account_representative": {
    },
  • "due_in_days": 0
}
Response samples 
application/json
{
  • "id": "string",
  • "buyer_company": {
    },
  • "billing_address": {
    },
  • "invoice_email": "user@example.com",
  • "invoice_cc_emails": [
    ],
  • "account_representative": {
    },
  • "due_in_days": 0
}
Get Repayment Account
Securityapi-key 
Request 
path Parameters
repayment_account_id
required
string <uuid>  (Repayment Account Id) 
 
Responses 
200
Successful Response


422
Validation Error


get/account/{repayment_account_id}
Request samples 
Response samples 
application/json
{
  • "id": "string",
  • "buyer_company": {
    },
  • "billing_address": {
    },
  • "invoice_email": "user@example.com",
  • "invoice_cc_emails": [
    ],
  • "account_representative": {
    },
  • "due_in_days": 0
}
Update Repayment Account
Update the payment account information using the Two repayment_account_id.


As was stated when creating a payment account, it is strongly encouraged that the repayment accounts correspond to
existing accounts of your buyers in your system, so that Buyers have a place to change their contact details. You
are expected to provide the buyer company's national id and address, which you can easily get from Step
1.


Note that the due_in_days field can only be updated before any repayment plans have been fulfilled, otherwise a 409
error will be returned.


Securityapi-key 
Request 
path Parameters
repayment_account_id
required
string <uuid>  (Repayment Account Id) 
 
Request Body schema: application/json
required
required
object (Representative) 
 
object (Address) 
 
required
object (CompanyUpdate) 
 
due_in_days
integer (Due In Days) 
If this field is set to null or not set, due_in_days will not be changed from the currently stored value.


 
invoice_cc_emails
Array of strings <email>  (Invoice Cc Emails) 
An array of additional email addresses to send invoices to in the CC field. Sending an empty array will remove all addresses from the CC field of the invoice emails.


 
invoice_email
required
string <email>  (Invoice Email) 
 
Responses 
204
Successful Response


409
Conflict


422
Validation Error


put/account/{repayment_account_id}
Request samples 
application/json
{
  • "buyer_company": {
    },
  • "billing_address": {
    },
  • "invoice_email": "user@example.com",
  • "invoice_cc_emails": [
    ],
  • "account_representative": {
    },
  • "due_in_days": 0
}
Response samples 
application/json
{
  • "description": "string",
  • "code": "ERROR"
}
Invoices
Get Invoice Document URL
Retrieve the URL of the invoice PDF for the given invoice ID.


Securityapi-key 
Request 
path Parameters
invoice_id
required
string <uuid>  (Invoice Id) 
 
Responses 
200
Successful Response


403
Forbidden


404
Not Found


422
Validation Error


get/invoice/{invoice_id}/pdf
Request samples 
Response samples 
application/json
{
  • "url": "string"
}
Get Invoice Details
Securityapi-key 
Request 
path Parameters
invoice_id
required
string <uuid>  (Invoice Id) 
 
Responses 
200
Successful Response


403
Forbidden


404
Not Found


422
Validation Error


get/invoice/{invoice_id}
Request samples 
Response samples 
application/json
{
  • "invoice_id": "string",
  • "gross_amount": "string",
  • "net_amount": "string",
  • "tax_amount": "string",
  • "invoice_issue_date": "2019-08-24",
  • "payment_reference": "string",
  • "payment_status": "string",
  • "total_paid_amount": "string",
  • "total_credited_amount": "string",
  • "total_collected_amount": "string",
  • "total_recoursed_amount": "string",
  • "unpaid_amount": "string"
}
Credit Check
Credit Check
Securityapi-key 
Request 
Request Body schema: application/json
required
amount
required
string <decimal>  (Amount) ^-?[0-9]+(\.[0-9]{0,2})?
The amount of credit to check against the given company details.


 
company_name
required
string (Company Name) 
The name of the company.


 
country_code
required
string (CountryCode) 
Country code in ISO 3166 Alpha-2 format.


 Enum: "AT" "DE" "GB" "NL" "NO" "SE" "US"  
currency
string (CurrencyCode) 
 Default:  "GBP"
The currency of the credit check.


 Enum: "GBP" "NOK" "SEK" "EUR" "USD"  
instalment_period
string (RepaymentPeriod) 
The period over which the credit should be divided into instalments. Defaults to MONTHLY. Currently only MONTHLY is supported.


 Value: "MONTHLY"  
national_identifier
required
string (National Identifier)   [ 1 .. 40 ] characters ^[a-zA-Z0-9\-_]+$
The identifier for the company in the national company registries. For example, CRN in the United Kingdom and Org. nr. in Norway.


 
Responses 
200
Successful Response


422
Validation Error


post/credit-check
Request samples 
application/json
{
  • "country_code": "AT",
  • "national_identifier": "string",
  • "company_name": "string",
  • "amount": "string",
  • "currency": "GBP",
  • "instalment_period": "MONTHLY"
}
Response samples 
application/json
{
  • "minimum_instalments": 0,
  • "maximum_instalments": 0,
  • "maximum_instalment_amount": "string",
  • "decision": "APPROVED",
  • "currency": "GBP"
}