Skip to main content
Version: 1.0.0

Two Repay API

Download this API's OpenAPI YAML

Sequence Diagram​

Repayment Terms Guide

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 Repay 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: Get Company

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.

Environments​

Testing​

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

Note: Read about our sandbox environment specific behaviour.

Production​

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

Authentication​

Security Scheme Type:

apiKey

Header parameter name:

X-Api-Key