Introduction

This guide explains how to integrate Two's Trade Account Onboarding process using our APIs. This allows you to onboard your business customers (as "Trade Accounts") and their employees (as "Users"). The result is a smoother purchasing experience for them, featuring instant credit assessments and potentially faster checkouts.

Key Benefits:

• Instant Credit Insights: Get immediate feedback on a company's creditworthiness.
• Defined Credit Limits: Clearly understand the approved credit limit and maximum single order value for onboarded companies.
• Streamlined Buyer Experience: Verified users linked to a trade account can often enjoy a "1-click" or skip-verification checkout.
• Enhanced B2B Workflow: Customize the purchasing journey for your known business customers.

This guide covers:

1. Creating a Trade Account for a business customer.
2. Registering an employee (buyer) as a User under that Trade Account.
3. The User verification flow.
4. Using verified Trade Accounts when placing orders.

Prerequisites

Before you start, please ensure you have:

• Your unique Merchant ID and API Key from Two.
• Access to Two's Trade Account API specification and Two Order API specification for detailed definitions of parameters and response objects.

The Trade Account Onboarding Flow

The onboarding process uses a sequence of API calls. First, you establish the company's trade account with Two. Then, you register and verify individual users who can make purchases on behalf of that company. We'll break this down into four main pillars.

Pillar 1: Create a Trade Account (Onboard a Company)

The first step is to register your business customer (the company) with Two. This action creates a "Trade Account" and triggers an initial credit assessment.

Endpoint: POST /v2/merchant/<merchant_id>/customer

Key Request Parameters:

• merchant_customer_id (string, required): Your unique internal identifier for this company. This ID must be unique for each company you onboard.
• legal_name (string, required): The official legal name of the company.
• organization_id (string, required): The company's official registration number (e.g., Company Number in the UK, Organisasjonsnummer in Norway).
• country_prefix (string, required): The two-letter ISO country code for the company (e.g., "GB", "NO", "SE").
• email_domain (string, optional): The company's email domain (e.g., "examplecorp.com"). This can help with user verification later.
• billing_email_address (string, optional): The primary email address for sending invoices to this company.
• official_address (object, required): The company's registered address details, including street_address, city, postal_code, and country.

Example Request:

{
    "merchant_customer_id": "YOUR_UNIQUE_COMPANY_ID_123",
    "legal_name": "Example Corp Ltd",
    "organization_id": "00123456",
    "country_prefix": "GB",
    "email_domain": "examplecorp.com",
    "billing_email_address": "accounts@examplecorp.com",
    "official_address": {
        "street_address": "123 Business Park",
        "city": "London",
        "postal_code": "EC1A 1BB",
        "country": "GB"
    }
}

Interpreting the Response:

Key Response Fields:

• id (string): Two's unique identifier for this trade account (customer). Store this, as it's needed for subsequent API calls.
• merchant_customer_id (string): The ID you provided.
• approved_for_credit (boolean): Indicates if Two has approved this company for credit.
• credit_limit (number): The total credit amount granted.
• credit_limit_currency (string): Currency of the credit limit.
• credit_limit_balance (number): The remaining available credit.
• max_single_order_value (number): The maximum value for a single order.
• decline_reason (string, nullable): If not approved for credit, this may provide a reason.
• buyer_is_in_arrears (boolean): Indicates if the company has overdue payments.

Example Response Snippet:

{
    "id": "two_customer_abc123xyz",
    "merchant_customer_id": "YOUR_UNIQUE_COMPANY_ID_123",
    "approved_for_credit": true,
    "credit_limit": 50000.0,
    "credit_limit_currency": "GBP",
    "credit_limit_balance": 50000.0,
    "max_single_order_value": 10000.0,
    "decline_reason": null,
    "buyer_is_in_arrears": false
}

Pillar 2: Register a User to the Trade Account

Once the company's trade account is established, you can register individual employees (buyers) as users under this account. This enables them to make purchases for the company and can lead to a streamlined checkout if they complete verification.

Endpoint: POST /v2/merchant/<merchant_id>/customer/<customer_id>/user

Key Request Parameters:

• merchant_user_id (string, required): Your unique internal identifier for this user within this company. This ID must be unique for each user you add to a specific trade account.
• email (string, required): The user's email address.
• first_name (string, required): The user's first name.
• last_name (string, required): The user's last name.
• phone (string, optional but recommended): The user's phone number.
• verification_success_redirect_url (string, required): The URL where the user will be redirected after successfully completing their verification via the user_verification_url.

Example Request:

{
    "merchant_user_id": "USER_JOHN_DOE_456",
    "email": "john.doe@examplecorp.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+447123456789",
    "verification_success_redirect_url": "https://yourshop.com/user-verification/success"
}

Interpreting the Response:

A successful call will return a JSON object with details about the newly registered user.

Key Response Fields:

• id (string): Two's unique identifier for this user. Store this.
• merchant_user_id (string): The ID you provided.
• customer_id (string): The ID of the trade account this user belongs to.
• verified (boolean): Indicates if the user has completed Two's verification process. This will initially be false.
• user_verification_url (string): A unique URL the user must visit to complete their verification.

Example Response Snippet:

{
    "id": "two_user_def456uvw",
    "merchant_user_id": "USER_JOHN_DOE_456",
    "customer_id": "two_customer_abc123xyz",
    "email": "john.doe@examplecorp.com",
    "first_name": "John",
    "last_name": "Doe",
    "verified": false,
    "user_verification_url": "https://checkout.sandbox.two.inc/onboarding/customer/user?mid=...&token=...",
    "verification_success_redirect_url": "https://yourshop.com/user-verification/success"
}

Pillar 3: User Verification

The Verification Process:

1. Redirect the User: Your application should redirect the user (or provide them with the link) to the user_verification_url.
2. User Interaction: The user interacts with Two's hosted page to complete any necessary verification steps (e.g., confirming their email via a one-time passcode).
3. Redirection on Completion: Upon successful verification, Two redirects the user to the verification_success_redirect_url you specified when registering the user.

Notifying the User (Optional):

If you don't redirect the user immediately, you can request Two to send a verification notification to them.

Request Body:

{
    "channel": "email" // Or "sms"
}

Checking Verification Status:

After the user has had an opportunity to verify, you can fetch their latest details to check their status.

Pillar 4: Leveraging Verified Trade Accounts in Orders

The main advantage of this onboarding flow is to streamline the checkout process. When a verified user places an order, Two may allow the trade buyer if verified to benefit from a 1-click checkout.

Associating an Order with a Verified User:

Example POST /v1/order Snippet (Buyer Representative):

{
    // ... other order details
    "buyer": {
        "company": {
            "company_name": "Example Corp Ltd",
            "organization_number": "00123456",
            "country_prefix": "GB"
        },
        "representative": {
            "email": "john.doe@examplecorp.com",
            "first_name": "John",
            "last_name": "Doe",
        }
    "merchant_user_id": "USER_JOHN_DOE_456" // Key for linking to the verified user

    }
    // ... merchant_urls, etc.
}

Key Considerations

• Uniqueness of IDs: Ensure merchant_customer_id (your ID for the company) and merchant_user_id (your ID for the user) are unique within their respective scopes (per company for users).
• Data Accuracy: Providing accurate company and user information is vital for effective credit assessment and a smooth user experience.
• Redirect URLs: Double-check that your verification_success_redirect_url (for user verification) are correctly configured and can handle the redirects.
• API Versioning: This guide refers to /v2/ of the Trade Account API and /v1/ of the Checkout API. Always consult the latest official API documentation for any updates.
• Error Handling: Implement robust error handling in your integration to manage various API responses, including potential errors or alternative flows.
• Idempotency: When creating trade accounts or users, be mindful of how the API handles requests with already existing merchant_customer_id or merchant_user_id values (e.g., the 409 Conflict for trade accounts). Design your system to handle these scenarios gracefully,