Skip to main content

Trade Account Onboarding

Introduction​

This guide explains how to integrate Two's Trade Account Onboarding process using the Trade Account API V3. This is an advanced workflow designed for merchants with registered, repeat B2B customers.

Unlike the standard Order Creation flow (which handles ad-hoc or guest buyers), Trade Account Onboarding allows you to:

  1. Register a Company: Establish a relationship with a business customer ("Trade Account").
  2. Register Users: Link specific employees to that Trade Account.
  3. Pre-Verify: Verify these users once so they face less friction during future checkouts.

When to use this:

  • You have a B2B portal where users log in.
  • You want to offer credit limits and "Pay on Account" features to specific customers.
  • You want to offer a faster, "1-click" style checkout experience for returning buyers.

The Onboarding Flow​

The process consists of four main steps plus the final checkout integration.

  1. Step 1: Create Trade Account: Register the company.
  2. Step 2: Create User: Register the buyer (employee).
  3. Step 3: Generate Verification URL: Create a verification link for the user.
  4. Step 4: User Verification: The user confirms their identity.
  5. Step 5: Streamlined Checkout: Place orders linked to the verified user.

Step 1: Create Trade Account (Onboard a Company)​

Register your business customer to create a "Trade Account".

Endpoint: POST /trade-account/v3/customer

Use Canonical ID

We strongly recommend using the canonical_id from the Company API to identify the company. This ensures accurate company matching.

Example Request:

{
  "merchant_customer_id": "YOUR_INTERNAL_CUSTOMER_ID_123",
  "canonical_id": "GB:00123456",
  "contact_persons": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "phone_number": "+447123456789",
      "email": "[email protected]"
    }
  ],
  "invoice_email_addresses": ["[email protected]"],
  "invoice_billing_address": {
    "street_address": "123 Business Park",
    "city": "London",
    "postal_code": "EC1A 1BB",
    "country": "GB"
  }
}

Key Request Fields:

  • merchant_customer_id: Required. Your unique ID for this company.
  • canonical_id: The company's canonical ID from Two's Company API (recommended).
  • contact_persons: Required. At least one contact person with first_name, last_name, phone_number, and email.
  • invoice_billing_address: The default billing address for invoices.

Key Response Fields:

  • merchant_customer_id: Your ID, echoed back.
  • company: Contains company_canonical_id, organization_number, country_prefix, and company_name.

Step 2: Register a User to the Trade Account​

Link an employee to the newly created Trade Account.

Endpoint: POST /trade-account/v3/customer/{cid}/user

Use the merchant_customer_id (or Two's ID) from Step 1 as {cid}.

Example Request:

{
  "merchant_user_id": "USER_JOHN_DOE_456",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+447123456789"
}

Key Request Fields:

  • merchant_user_id: Required. Your unique ID for this user.
  • email: Required. User's email address.
  • first_name, last_name: Required. User's name.
  • phone_number: Optional but recommended.

Key Response Fields:

  • merchant_user_id: Your ID, echoed back.
  • verified: false initially. Becomes true after verification.

Step 3: Generate Verification URL​

In V3, you must explicitly request a verification URL for the user. This is a separate step from creating the user.

Endpoint: POST /trade-account/v3/user/{uid}/verification/url

Use the merchant_user_id (or Two's ID) from Step 2 as {uid}.

Example Request:

{
  "return_url": "https://yourshop.com/profile/verified"
}

Key Request Fields:

  • return_url: Required. Where to redirect the user after they complete verification.

Key Response Fields:

  • redirect_url: The URL to send the user to begin verification.

Step 4: User Verification​

The user must complete a one-time verification to unlock streamlined checkouts.

  1. Redirect: Send the user to the redirect_url from Step 3.
  2. Verify: The user completes the flow (e.g., email/SMS OTP) on Two's hosted page.
  3. Return: Two redirects the user back to your return_url.

You can check their status anytime using GET /trade-account/v3/user/{uid}. When verified is true, they are ready.

Step 5: Streamlined Checkout​

When this verified user places an order, link it to their Trade Account profile.

Endpoint: POST /v1/order

Add the merchant_user_id to the request root.

Example Request:

{
  "merchant_user_id": "USER_JOHN_DOE_456",
  "buyer": {
    "company": {
      "company_name": "Example Corp Ltd",
      "organization_number": "00123456",
      "country_prefix": "GB"
    },
    "representative": {
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe"
    }
  },
  "merchant_urls": {
    // ...
  }
  // ... items, totals, etc.
}

The Benefit: Because USER_JOHN_DOE_456 is already verified, Two can often skip the interactive verification steps during the payment_url flow, making the checkout feel like a "1-click" approval.

Flexible ID Usage​

Trade Account API V3 supports flexible identification. You can use either:

  • Your internal IDs: merchant_customer_id or merchant_user_id directly in path parameters
  • Two's system IDs: IDs starting with two_ returned by the API

For example, both of these are valid:

  • GET /trade-account/v3/customer/YOUR_INTERNAL_ID_123
  • GET /trade-account/v3/customer/two_abc123xyz
ID Collision Avoidance

Do NOT use IDs starting with two_ for your internal identifiers. This prefix is reserved for Two's system-generated IDs.