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

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 (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: "NO" "SE" "GB" "US" "NL" "ES" "DK" "FR" "DE"
email_domain
required
string (Email Domain)

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

required
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 (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: "NO" "SE" "GB" "US" "NL" "ES" "DK" "FR" "DE"
email_domain
required
string (Email Domain)

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

required
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 (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: "NO" "SE" "GB" "US" "NL" "ES" "DK" "FR" "DE"
email_domain
string (Email Domain)

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": "string",
  • "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
200

OK

default

Error response

get/v2/merchant/{mid}/customer_lookup/{merchant_customer_id}
Request samples
Response samples
application/json
{}

Verify merchant customer billing email address

SecurityX-Api-Key
Request
path Parameters
cid
required
string

Customer ID

mid
required
string

Merchant ID

Responses
default

Error response

post/v2/merchant/{mid}/customer/{cid}/verify_billing_email
Request samples
Response samples
application/json
{
  • "error_code": "string",
  • "error_details": "string",
  • "error_message": "string",
  • "error_json": [
    ]
}

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": [
    ]
}

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": [
    ]
}