Trade Account API v3 - Preview (3.0)

Download OpenAPI specification:Download

**This API is currently in preview.**

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

Authentication & IDs

Trade Account API v3 supports flexible identification of resources, allowing you to use either your own internal identifiers or our system-generated identifiers in path segments.

How it works:

When you provide an ID in a path parameter (e.g., in /customer/), our system attempts to resolve it:

If the ID begins with two_: We interpret this as an identifier generated by our system. You would typically use this when referencing resources that you've previously created or retrieved from our API.

Example: GET /trade-account/v3/customer/two_XYZ789 If the ID does NOT begin with two_: We interpret this as your own internal identifier for the resource. This allows you to integrate seamlessly with your existing data structures.

Example: GET /trade-account/v3/customer/yourInternalID123

Collision Avoidance:

To ensure unambiguous resolution, it is CRITICAL that any customer or entity identifiers you use and pass directly to our API (i.e., those without the two_ prefix) DO NOT begin with the string two_. This prefix is strictly reserved for identifiers originating from our platform. Please ensure your internal ID generation logic adheres to this constraint.

Getting Started

Step 1: Create a B2B trade account customer

  • Create a new trade account customer using the POST /trade-account/v3/customer endpoint.

Step 2: Create users for your trade account customers.

  • The employees who place orders on behalf of your trade account customer (their employer), can be set up for purchasing through POST /trade_account/v3/customer/<cid>/user.

  • Upon successfully creating a user for a customer, onboarding is completed. To verify the user generate the verification link using POST /trade_account/v3/user/<uid>/verification/url. 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

Customer

Create trade account customer record

SecurityX-Api-Key
Request
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
Default: null
Request Body schema: application/json
Canonical Id (string) or Canonical Id (null) (Canonical Id)
Default: null

Canonical id of the company can be found by using company search in Two Company API, strongly recommended this value is used to create the customer.

required
Array of objects (Contact Persons) non-empty

List of contact persons for the customer. At least one contact person is required.

CountryCodeEnum (string) or null
Default: null

The country code of the customer company. If canonical id not supplied, customer company is looked up using this field and organization_number.

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

The customer id registered in the merchant's solution

Organization Number (string) or Organization Number (null) (Organization Number)
Default: null

The organization number of the customer company.If canonical id not supplied, customer company is looked up using this field and country_code.

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

If the customer is using a different brand/trade name, this value will set trade_name on the orders associated with the customer.

Responses
201

Created

400

Customer company not found

409

Customer already exists

default

Error response

post/trade-account/v3/customer
Request samples
application/json
{
  • "canonical_id": null,
  • "country_code": null,
  • "organization_number": null,
  • "merchant_customer_id": "string",
  • "contact_persons": [
    ],
  • "trade_name": null
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_customer_id": "string",
  • "contact_persons": [
    ],
  • "trade_name": null,
  • "company": null
}

Replace values on the customer record

SecurityX-Api-Key
Request
path Parameters
cid
required
string

Customer ID, if it starts with two_ it is a system generated ID otherwise it is a custom ID

Request Body schema: application/json
required
Array of objects (Contact Persons) non-empty

List of contact persons for the customer. At least one contact person is required.

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

The customer id registered in the merchant's solution

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

If the customer is using a different brand/trade name, this value will set trade_name on the orders associated with the customer.

Responses
200

OK

404

Customer not found

default

Error response

put/trade-account/v3/customer/{cid}
Request samples
application/json
{
  • "merchant_customer_id": "string",
  • "contact_persons": [
    ],
  • "trade_name": null
}
Response samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_customer_id": "string",
  • "contact_persons": [
    ],
  • "trade_name": null,
  • "company": null
}

Get customer record

SecurityX-Api-Key
Request
path Parameters
cid
required
string

Customer ID, if it starts with two_ it is a system generated ID otherwise it is a custom ID

Responses
200

OK

404

Customer not found

default

Error response

get/trade-account/v3/customer/{cid}
Request samples 
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "merchant_customer_id": "string",
  • "contact_persons": [
    ],
  • "trade_name": null,
  • "company": null
}
Customer User
Create a user record and assign it to a customer
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
Customer ID


 
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) 
 Default:  null
 
Request Body schema: application/json
email
required
string <email>  (Email) 
User email address


 
first_name
required
string (First Name) 
User first name


 
last_name
required
string (Last Name) 
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 Number (string) or Phone Number (null) (Phone Number) 
 Default:  null
User phone number


 
Responses 
201
Created


404
Customer not found


409
User already exists


default
Error response


post/trade-account/v3/customer/{cid}/user
Request samples 
application/json
{
  • "merchant_user_id": "string",
  • "email": "johndoe0112358@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "phone_number": "+44XXXXXXXXXX"
}
Response samples 
application/json
{
  • "merchant_user_id": "string",
  • "email": "johndoe0112358@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "phone_number": "+44XXXXXXXXXX",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "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


 
Responses 
200
OK


404
Customer not found


default
Error response


get/trade-account/v3/customer/{cid}/user
Request samples 
Response samples 
application/json
[
  • {
    }
]
User
Create a trade account user verification url.
SecurityX-Api-Key 
Request 
path Parameters
uid
required
string
User ID


 
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) 
 Default:  null
 
Request Body schema: application/json
return_url
required
string (Return Url) 
Url the user should be returned to on completion of verification


 
Responses 
201
Created


404
User not found


default
Error response


post/trade-account/v3/user/{uid}/verification/url
Request samples 
application/json
{
  • "return_url": "string"
}
Response samples 
application/json
{
  • "redirect_url": "string"
}
Update trade account user record.
SecurityX-Api-Key 
Request 
path Parameters
uid
required
string
User ID


 
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) 
 Default:  null
 
Request Body schema: application/json
Email (string) or Email (null) (Email) 
 Default:  null
User email address


 
First Name (string) or First Name (null) (First Name) 
 Default:  null
User first name


 
Last Name (string) or Last Name (null) (Last Name) 
 Default:  null
User last name


 
Merchant User Id (string) or Merchant User Id (null) (Merchant User Id) 
 Default:  null
 
Phone Number (string) or Phone Number (null) (Phone Number) 
 Default:  null
User phone number


 
Responses 
200
OK


404
User not found


default
Error response


patch/trade-account/v3/user/{uid}
Request samples 
application/json
{
  • "merchant_user_id": null,
  • "email": "johndoe0112358@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "phone_number": "+44XXXXXXXXXX"
}
Response samples 
application/json
{
  • "merchant_user_id": "string",
  • "email": "johndoe0112358@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "phone_number": "+44XXXXXXXXXX",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": true
}
Delete trade account user record.
SecurityX-Api-Key 
Request 
path Parameters
uid
required
string
User ID


 
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) 
 Default:  null
 
Responses 
204
No Content


404
User not found


default
Error response


delete/trade-account/v3/user/{uid}
Request samples 
Response samples 
application/json
{
  • "error_code": null,
  • "error_details": null,
  • "error_message": null,
  • "error_json": null,
  • "error_trace_id": null
}
Get trade account user record.
SecurityX-Api-Key 
Request 
path Parameters
uid
required
string
User ID


 
Responses 
200
OK


404
User not found


default
Error response


get/trade-account/v3/user/{uid}
Request samples 
Response samples 
application/json
{
  • "merchant_user_id": "string",
  • "email": "johndoe0112358@gmail.com",
  • "first_name": "John",
  • "last_name": "Doe",
  • "phone_number": "+44XXXXXXXXXX",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "verified": true
}
Customer Payment Method
list_payment_methods <GET>
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
 
Responses 
200
OK


400
Customer not found


default
Error response


get/trade-account/v3/customer/{cid}/payment-method
Request samples 
Response samples 
application/json
{
  • "items": [
    ]
}
Create a new payment method for a customer.
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
 
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) 
 Default:  null
 
Request Body schema: application/json
required
object (MandateAcceptanceData) 
Audit data of the acceptance of the mandate by the customer


 
Mandate Reference (string) or Mandate Reference (null) (Mandate Reference) 
 Default:  null
 
Metadata (object) or Metadata (null) (Metadata) 
 Default:  null
 
required
SEPADirectDebit (object) or ACHDirectDebit (object) or BACSDirectDebit (object) (PaymentMethod) 
 
Set As Default (boolean) or Set As Default (null) (Set As Default) 
 Default:  false
 
Responses 
201
Created


400
Customer not found


default
Error response


post/trade-account/v3/customer/{cid}/payment-method
Request samples 
application/json
{
  • "set_as_default": true,
  • "metadata": null,
  • "payment_details": {
    },
  • "mandate_reference": "AWS-MANDATE-123",
  • "mandate_acceptance": {
    }
}
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "SEPA_DIRECT_DEBIT",
  • "status": "AUTHORIZATION_PENDING",
  • "is_default": true,
  • "created_at": "2025-04-01T10:30:00Z",
  • "authorized_at": "2025-04-01T11:05:00Z",
  • "metadata": {
    },
  • "display_details": null,
  • "mandate_reference": "MANDATE-123-456"
}
Get details of a specific payment method for a customer.
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
 
payment_method_id
required
string
 
Responses 
200
OK


400
Customer or payment method not found


default
Error response


get/trade-account/v3/customer/{cid}/payment-method/{payment_method_id}
Request samples 
Response samples 
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "SEPA_DIRECT_DEBIT",
  • "status": "AUTHORIZATION_PENDING",
  • "is_default": true,
  • "created_at": "2025-04-01T10:30:00Z",
  • "authorized_at": "2025-04-01T11:05:00Z",
  • "metadata": {
    },
  • "display_details": null,
  • "mandate_reference": "MANDATE-123-456"
}
Delete a payment method for a customer.
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
 
payment_method_id
required
string
 
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) 
 Default:  null
 
Responses 
204
Success, no content


400
Customer or payment method not found


default
Error response


delete/trade-account/v3/customer/{cid}/payment-method/{payment_method_id}
Request samples 
Response samples 
application/json
{
  • "error_code": null,
  • "error_details": null,
  • "error_message": null,
  • "error_json": null,
  • "error_trace_id": null
}
Set a payment method as default for a customer.
SecurityX-Api-Key 
Request 
path Parameters
cid
required
string
 
payment_method_id
required
string
 
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key) 
 Default:  null
 
Responses 
204
Success, no content


400
Customer or payment method not found


default
Error response


post/trade-account/v3/customer/{cid}/payment-method/{payment_method_id}/make-default
Request samples 
Response samples 
application/json
{
  • "error_code": null,
  • "error_details": null,
  • "error_message": null,
  • "error_json": null,
  • "error_trace_id": null
}