Two Onboarding API (1.0)

Download OpenAPI specification:Download

This API allows you to onboard your business customers to your own product and to the Two "Buy Now Pay Later" product.

Specifically:

  • Enable 1-click checkout with Two
  • Approve additional users to place orders on behalf of your business customers
  • Access insights and enriched data on your business customers
  • Receive validation that Two believes it is an accurate and valid representative of the business

Note: Merchant ID is denoted as mid. This can be obtained alongside the API key from the merchant portal.

Step 1: Create a B2B business customer

  • Create a new business customer using the POST /v2/merchant/<mid>/customer endpoint.

Step 2: Create users for your business customers.

  • The employees who place orders on behalf of your business customer (their employer), can be set up for purchasing through POST /v2/merchant/<mid>/customer/<cid>/user.

  • Upon successfully creating a customer user, onboarding is completed. You may optionally redirect the user to the user_verification_url for them to verify their account. Verification of the customer user will allow one-click purchases for the customer user.

Note: Two reserves the right to add extra verification steps for certain orders.

Environments

Testing

https://api.sandbox.two.inc

Note: Read about our sandbox environment specific behaviour.

Production

https://api.two.inc

Merchant Customer Onboarding

Create customer record

SecurityX-Api-Key
Request
path Parameters
mid
required
string

Merchant ID

Request Body schema: application/json
Additional Identifiers (object) or Additional Identifiers (null) (Additional Identifiers)
Default: null

Optionally provide us with any other relevant identifiers related to this company.

billing_email_address
required
string <email> (Billing Email Address)

This email address is designated to receive the invoices attached to this trade account. In case the order is placed using a billing account ID, emails will be directed to the address specified for that billing account instead.

country_prefix
required
string (CountryCodeEnum)

Country code in ISO 3166-1 alpha-2 format

Enum: "AT" "BE" "CH" "CZ" "DE" "DK" "ES" "FI" "FR" "GB" "GR" "IE" "IT" "LU" "NO" "NL" "PL" "RO" "SE" "SI" "US"
Email Domain (string) or Email Domain (null) (Email Domain)
Deprecated
Default: null

Unique name that appears after the @ sign in email addresses

Estimated Monthly Spend (string) or Estimated Monthly Spend (null) (Estimated Monthly Spend)
Default: null

The estimated monthly spend for the customer.

Insights Webhook (string) or Insights Webhook (null) (Insights Webhook)
Default: null

Subscribe to updates for company insights. A json object will be POST-ed to this url whenever the insights for this company get updated. The schema for this json-object it the same as for the response body of GET /merchant/{mid}/customer/{cid}/insights.

legal_name
required
string (Legal Name)

The legal name of the buyer company

merchant_customer_id
required
string (Merchant Customer Id) [ 1 .. 255 ] characters

The customer id registered in the merchant's solution

MerchantRedirectUrlsSchema (object) or null
Default: null
required
object (CreateAddressRequestSchema)

Address fields connected to the business customer

organization_id
required
string (Organization Id) [ 1 .. 255 ] characters

National id of the buyer company

Array of Shipping Addresses (objects) or Shipping Addresses (null) (Shipping Addresses)
Default: null

Address fields connected to the business customer

Trade Name (string) or Trade Name (null) (Trade Name)
Default: null

If the company is using a different brand/trade name, this can included here.

HookSchema (object) or null
Default: null
Website (string) or Website (null) (Website)
Default: null

The website of the business customer

Responses
201

Created

default

Error response

post/v2/merchant/{mid}/customer
Request samples
application/json
{}
Response samples
application/json
{}

Get customer list

Fetch a list of customers

SecurityX-Api-Key
Request
path Parameters
mid
required
string

Merchant ID

Responses
200

OK

default

Error response

get/v2/merchant/{mid}/customer
Request samples 
Response samples 
application/json
[]
Replace customer record
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
Request Body schema: application/json
Additional Identifiers (object) or Additional Identifiers (null) (Additional Identifiers) 
 Default:  null
Optionally provide us with any other relevant identifiers related to this company.


 
billing_email_address
required
string <email>  (Billing Email Address) 
This email address is designated to receive the invoices attached to this trade account. In case the order is placed using a billing account ID, emails will be directed to the address specified for that billing account instead.


 
country_prefix
required
string (CountryCodeEnum) 
Country code in ISO 3166-1 alpha-2 format


 Enum: "AT" "BE" "CH" "CZ" "DE" "DK" "ES" "FI" "FR" "GB" "GR" "IE" "IT" "LU" "NO" "NL" "PL" "RO" "SE" "SI" "US"  
Email Domain (string) or Email Domain (null) (Email Domain) 
 Deprecated 
 Default:  null
Unique name that appears after the @ sign in email addresses


 
Estimated Monthly Spend (string) or Estimated Monthly Spend (null) (Estimated Monthly Spend) 
 Default:  null
The estimated monthly spend for the customer.


 
Id (string) or Id (null) (Id) 
 Default:  null
 
Insights Webhook (string) or Insights Webhook (null) (Insights Webhook) 
 Default:  null
Subscribe to updates for company insights. A json object will be POST-ed to this url whenever the insights for this company get updated. The schema for this json-object it the same as for the response body of GET /merchant/{mid}/customer/{cid}/insights.


 
legal_name
required
string (Legal Name) 
The legal name of the buyer company


 
merchant_customer_id
required
string (Merchant Customer Id)   [ 1 .. 255 ] characters 
The customer id registered in the merchant's solution


 
MerchantRedirectUrlsSchema (object) or null
 Default:  null
 
CreateAddressRequestSchema (object) or null
 Default:  null
Address fields connected to the business customer


 
organization_id
required
string (Organization Id)   [ 1 .. 255 ] characters 
National id of the buyer company


 
Array of Shipping Addresses (objects) or Shipping Addresses (null) (Shipping Addresses) 
 Default:  null
Array of address fields connected to the business customer


 
Trade Name (string) or Trade Name (null) (Trade Name) 
 Default:  null
If the company is using a different brand/trade name, this can included here.


 
HookSchema (object) or null
 Default:  null
 
Website (string) or Website (null) (Website) 
 Default:  null
The website of the business customer


 
Responses 
200
OK


default
Error response


put/v2/merchant/{mid}/customer/{cid}
Request samples 
application/json
{}
Response samples 
application/json
{}
Patch customer record
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
Request Body schema: application/json
Additional Identifiers (object) or Additional Identifiers (null) (Additional Identifiers) 
 Default:  null
Optionally provide us with any other relevant identifiers related to this company.


 
Billing Email Address (string) or Billing Email Address (null) (Billing Email Address) 
 Default:  null
This email address is designated to receive the invoices attached to this trade account. In case the order is placed using a billing account ID, emails will be directed to the address specified for that billing account instead.


 
CountryCodeEnum (string) or null
 Default:  null
Country code in ISO 3166-1 alpha-2 format


 
Email Domain (string) or Email Domain (null) (Email Domain) 
 Deprecated 
 Default:  null
Unique name that appears after the @ sign in email addresses


 
Id (string) or Id (null) (Id) 
 Default:  null
 
Insights Webhook (string) or Insights Webhook (null) (Insights Webhook) 
 Default:  null
Subscribe to updates for company insights. A json object will be POST-ed to this url whenever the insights for this company get updated. The schema for this json-object it the same as for the response body of GET /merchant/{mid}/customer/{cid}/insights.


 
Legal Name (string) or Legal Name (null) (Legal Name) 
 Default:  null
The legal name of the buyer company


 
Merchant Customer Id (string) or Merchant Customer Id (null) (Merchant Customer Id) 
 Default:  null
The customer id registered in the merchant's solution


 
MerchantRedirectUrlsSchema (object) or null
 Default:  null
 
CreateAddressRequestSchema (object) or null
 Default:  null
Address fields connected to the business customer


 
Organization Id (string) or Organization Id (null) (Organization Id) 
 Default:  null
National id of the buyer company


 
Array of Shipping Addresses (objects) or Shipping Addresses (null) (Shipping Addresses) 
 Default:  null
Array of address fields connected to the business customer


 
Trade Name (string) or Trade Name (null) (Trade Name) 
 Default:  null
If the company is using a different brand/trade name, this can included here.


 
HookSchema (object) or null
 Default:  null
 
Website (string) or Website (null) (Website) 
 Default:  null
The website of the business customer


 
Responses 
200
OK


default
Error response


patch/v2/merchant/{mid}/customer/{cid}
Request samples 
application/json
{
  • "id": null,
  • "merchant_customer_id": null,
  • "official_address": null,
  • "shipping_addresses": null,
  • "merchant_redirect_urls": null,
  • "country_prefix": "GB",
  • "email_domain": null,
  • "insights_webhook": null,
  • "legal_name": null,
  • "organization_id": null,
  • "trade_name": null,
  • "website": null,
  • "webhooks": null,
  • "billing_email_address": null,
  • "additional_identifiers": null
}
Response samples 
application/json
{}
Get customer record
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
Responses 
200
OK


default
Error response


get/v2/merchant/{mid}/customer/{cid}
Request samples 
Response samples 
application/json
{}
Get customer from external customer ID
SecurityX-Api-Key 
Request 
path Parameters
merchant_customer_id
required
string
External customer ID


 
mid
required
string
Merchant ID


 
Responses 
302
Redirect to the GET customer endpoint (/v2/merchant//customer/)


default
Error response


get/v2/merchant/{mid}/customer_lookup/{merchant_customer_id}
Request samples 
Response samples 
application/json
{
  • "error_code": null,
  • "error_details": null,
  • "error_message": null,
  • "error_json": null,
  • "error_trace_id": null
}
Merchant Customer User Onboarding
Create customer user record
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
Request Body schema: application/json
email
required
string <email>  (Email) 
This is the user email address


 
first_name
required
string (First Name) 
This is the user first name


 
last_name
required
string (Last Name) 
This is the user last name


 
merchant_user_id
required
string (Merchant User Id)   [ 1 .. 255 ] characters 
Your internal ID of this user (the employee of your business customer).


 
Phone (string) or Phone (null) (Phone) 
 Default:  null
This is the user phone number


 
verification_success_redirect_url
required
string (Verification Success Redirect Url) 
Redirect url after user successfully completes verification


 
Array of Verified Fields (strings) or Verified Fields (null) (Verified Fields) 
 Default:  null
List of verified user credentials set by the merchant


 
Responses 
201
Created


default
Error response


post/v2/merchant/{mid}/customer/{cid}/user
Request samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": null,
  • "verification_success_redirect_url": "string",
  • "verified_fields": null
}
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": null,
  • "verification_success_redirect_url": "string",
  • "verified_fields": null,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": null,
  • "user_verification_url": null,
  • "verified": true
}
Get customer user list
Fetch a list of users attached to the business customer account


SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
Responses 
200
OK


default
Error response


get/v2/merchant/{mid}/customer/{cid}/user
Request samples 
Response samples 
application/json
[
  • {
    }
]
Update a customer user record
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
uid
required
string
User ID


 
Request Body schema: application/json
Email (string) or Email (null) (Email) 
 Default:  null
This is the user email address


 
First Name (string) or First Name (null) (First Name) 
 Default:  null
This is the user first name


 
Id (string) or Id (null) (Id) 
 Default:  null
 
Last Name (string) or Last Name (null) (Last Name) 
 Default:  null
This is the user last name


 
Merchant User Id (string) or Merchant User Id (null) (Merchant User Id) 
 Default:  null
Your internal ID of this user (the employee of your business customer).


 
Phone (string) or Phone (null) (Phone) 
 Default:  null
This is the user phone number


 
Verification Success Redirect Url (string) or Verification Success Redirect Url (null) (Verification Success Redirect Url) 
 Default:  null
Redirect url after user successfully completes verification


 
Array of Verified Fields (strings) or Verified Fields (null) (Verified Fields) 
 Default:  null
List of verified user credentials set by the merchant


 
Responses 
200
OK


default
Error response


patch/v2/merchant/{mid}/customer/{cid}/user/{uid}
Request samples 
application/json
{
  • "email": null,
  • "first_name": null,
  • "last_name": null,
  • "merchant_user_id": null,
  • "phone": null,
  • "verification_success_redirect_url": null,
  • "verified_fields": null,
  • "id": null
}
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": null,
  • "verification_success_redirect_url": "string",
  • "verified_fields": null,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": null,
  • "user_verification_url": null,
  • "verified": true
}
Replace customer user record
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
uid
required
string
User ID


 
Request Body schema: application/json
Email (string) or Email (null) (Email) 
 Default:  null
This is the user email address


 
First Name (string) or First Name (null) (First Name) 
 Default:  null
This is the user first name


 
Id (string) or Id (null) (Id) 
 Default:  null
 
Last Name (string) or Last Name (null) (Last Name) 
 Default:  null
This is the user last name


 
merchant_user_id
required
string (Merchant User Id)   [ 1 .. 255 ] characters 
Your internal ID of this user (the employee of your business customer).


 
Phone (string) or Phone (null) (Phone) 
 Default:  null
This is the user phone number


 
Verification Success Redirect Url (string) or Verification Success Redirect Url (null) (Verification Success Redirect Url) 
 Default:  null
Redirect url after user successfully completes verification


 
Array of Verified Fields (strings) or Verified Fields (null) (Verified Fields) 
 Default:  null
List of verified user credentials set by the merchant


 
Responses 
200
OK


default
Error response


put/v2/merchant/{mid}/customer/{cid}/user/{uid}
Request samples 
application/json
{
  • "email": null,
  • "first_name": null,
  • "last_name": null,
  • "merchant_user_id": "string",
  • "phone": null,
  • "verification_success_redirect_url": null,
  • "verified_fields": null,
  • "id": null
}
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": null,
  • "verification_success_redirect_url": "string",
  • "verified_fields": null,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": null,
  • "user_verification_url": null,
  • "verified": true
}
Get customer user record
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
uid
required
string
User ID


 
Responses 
200
OK


default
Error response


get/v2/merchant/{mid}/customer/{cid}/user/{uid}
Request samples 
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": null,
  • "verification_success_redirect_url": "string",
  • "verified_fields": null,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": null,
  • "user_verification_url": null,
  • "verified": true
}
Notify customer user
Send a notification to customer user with a URL to complete onboarding via specified notification channel.


SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
uid
required
string
User ID


 
Request Body schema: application/json
channel
required
string (NotificationChannel) 
 Enum: "sms" "email"  
Responses 
200
OK


default
Error response


post/v2/merchant/{mid}/customer/{cid}/user/{uid}/notify
Request samples 
application/json
{
  • "channel": "sms"
}
Response samples 
application/json
{
  • "error_code": null,
  • "error_details": null,
  • "error_message": null,
  • "error_json": null,
  • "error_trace_id": null
}
Get customer user record from external user ID
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
merchant_user_id
required
string
External user ID


 
mid
required
string
Merchant ID


 
Responses 
200
OK


default
Error response


get/v2/merchant/{mid}/customer/{cid}/user_lookup/{merchant_user_id}
Request samples 
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": null,
  • "verification_success_redirect_url": "string",
  • "verified_fields": null,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": null,
  • "user_verification_url": null,
  • "verified": true
}
Merchant Customer Limits
Get a merchant onboarded customers' credit limits
SecurityX-Api-Key 
Request 
path Parameters
mid
required
string
Merchant ID


 
Responses 
200
OK


default
Error response


get/v1/merchant/{mid}/customers/credit_check
Request samples 
Response samples 
application/json
{
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_credit_limits": [
    ]
}
Get a merchant onboarded customer credit limits
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
mid
required
string
Merchant ID


 
Responses 
200
OK


default
Error response


get/v1/merchant/{mid}/customer/{cid}/credit_check
Request samples 
Response samples 
application/json
{
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_credit_limits": [
    ]
}