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
object (Additional Identifiers)

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" "NO" "NL" "PL" "RO" "SE" "SI" "US"
email_domain
string (Email Domain)
Deprecated

Unique name that appears after the @ sign in email addresses

estimated_monthly_spend
string <decimal> (Estimated Monthly Spend) ^-?[0-9]+(\.[0-9]{0,2})?

The estimated monthly spend for the customer.

insights_webhook
string (Insights Webhook)

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

object (MerchantRedirectUrlsSchema)
required
object (Official Address)

Address fields connected to the business customer

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

National id of the buyer company

Array of objects (Shipping Addresses)

Address fields connected to the business customer

trade_name
string (Trade Name)

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

object (HookSchema)
website
string (Website)

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
object (Additional Identifiers) 
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" "NO" "NL" "PL" "RO" "SE" "SI" "US"  
email_domain
string (Email Domain) 
 Deprecated 
Unique name that appears after the @ sign in email addresses


 
estimated_monthly_spend
string <decimal>  (Estimated Monthly Spend) ^-?[0-9]+(\.[0-9]{0,2})?
The estimated monthly spend for the customer.


 
id
string <uuid>  (Id) 
 
insights_webhook
string (Insights Webhook) 
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


 
object (MerchantRedirectUrlsSchema) 
 
object (Official Address) 
Address fields connected to the business customer


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


 
Array of objects (Shipping Addresses) 
Array of address fields connected to the business customer


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


 
object (HookSchema) 
 
website
string (Website) 
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
object (Additional Identifiers) 
Optionally provide us with any other relevant identifiers related to this company.


 
billing_email_address
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
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" "NO" "NL" "PL" "RO" "SE" "SI" "US"  
email_domain
string (Email Domain) 
 Deprecated 
Unique name that appears after the @ sign in email addresses


 
id
string <uuid>  (Id) 
 
insights_webhook
string (Insights Webhook) 
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 (Legal Name) 
The legal name of the buyer company


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


 
object (MerchantRedirectUrlsSchema) 
 
object (Official Address) 
Address fields connected to the business customer


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


 
Array of objects (Shipping Addresses) 
Array of address fields connected to the business customer


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


 
object (HookSchema) 
 
website
string (Website) 
The website of the business customer


 
Responses 
200
OK


default
Error response


patch/v2/merchant/{mid}/customer/{cid}
Request samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_customer_id": "string",
  • "official_address": {
    },
  • "shipping_addresses": [
    ],
  • "merchant_redirect_urls": {
    },
  • "country_prefix": "GB",
  • "email_domain": "string",
  • "insights_webhook": "string",
  • "legal_name": "string",
  • "organization_id": "string",
  • "trade_name": "string",
  • "website": "string",
  • "webhooks": {
    },
  • "billing_email_address": "user@example.com",
  • "additional_identifiers": {
    }
}
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": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
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 (Phone) 
This is the user phone number


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


 
verified_fields
Array of strings (Verified Fields) 
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": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ]
}
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": true,
  • "user_verification_url": "string",
  • "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 <email>  (Email) 
This is the user email address


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


 
id
string <uuid>  (Id) 
 
last_name
string (Last Name) 
This is the user last name


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


 
phone
string (Phone) 
This is the user phone number


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


 
verified_fields
Array of strings (Verified Fields) 
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": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": true,
  • "user_verification_url": "string",
  • "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 <email>  (Email) 
This is the user email address


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


 
id
string <uuid>  (Id) 
 
last_name
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 (Phone) 
This is the user phone number


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


 
verified_fields
Array of strings (Verified Fields) 
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": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
Response samples 
application/json
{
  • "email": "user@example.com",
  • "first_name": "string",
  • "last_name": "string",
  • "merchant_user_id": "string",
  • "phone": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": true,
  • "user_verification_url": "string",
  • "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": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": true,
  • "user_verification_url": "string",
  • "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) 
An enumeration.


 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": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ],
  • "error_trace_id": "string"
}
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": "string",
  • "verification_success_redirect_url": "string",
  • "verified_fields": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  • "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
  • "is_legal_rep": true,
  • "user_verification_url": "string",
  • "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": [
    ]
}