Understanding the Order Creation Path with Two

This guide explains the essential steps and concepts for developers integrating Two's services directly via our API. A successful integration hinges on understanding key aspects of the Two ecosystem:

Identify the Buyer: Gather accurate company data.
Proactive Credit Assessment with Order Intent: How to gauge creditworthiness before creating an order.
Order status: How Two evaluates credit for an order.
Order state: How an order progresses through necessary verification steps.
Post-Verification Actions: Optional steps and rules for managing verified orders.
Order Fulfilment: The final step to complete the order and trigger invoicing.

Step 1: Identify the Buyer

Before you can create an order or assess credit, you need to know who the buyer is. Two relies on accurate company identification (specifically the organization_number) to perform credit checks.

We strongly recommend using our Company API to search for and validate business customers during checkout.

tip

Read the Company Identification Guide to learn how to find and verify businesses.

Step 2: Proactive Credit Assessment (Order Intent)

Before creating an order, you can proactively assess a buyer's potential creditworthiness using the POST /v1/order_intent endpoint. This step is highly recommended as it can enhance the buyer experience, reduce unnecessary API calls, and provide an early indication of Two's likelihood to approve credit for a potential order.

The Order Intent endpoint allows you to submit key details about the prospective buyer and order. In return, Two provides an assessment, typically indicating if the intent is approved. This is a strong signal, though not a final guarantee, of credit approval.

Benefits of Order Intent

Optimise API Usage: Avoid creating full orders if the initial credit assessment is unfavourable.
Improve Buyer Experience: Provide earlier feedback to buyers regarding their ability to use Two for a purchase.
Streamline Decision Making: Get a quick credit signal before committing to the full order creation process.

For a comprehensive understanding of how to best utilise this endpoint, please refer to our dedicated guide: Using the Order Intent Endpoint.

Step 3: Create Order & Check Status

When you create an order with Two using the POST /v1/order endpoint, our system performs an immediate, real-time credit check on the buyer's company specified in your API request. The API response will include a status field, which reflects Two's credit decision for that order.

Status	Description
`APPROVED`	Two can provide credit for this particular order
`REJECTED`	Two cannot offer a credit guarantee for the order amount at this time

Important

To proceed with an order towards completion and payout, always ensure its latest status is APPROVED. An APPROVED status is your assurance that Two will back the credit for this order, making it "fulfillable".

Step 4: Verification

Once an order is credit-approved (i.e., its status is APPROVED), the next critical field to monitor is its state. This field tracks the order's progression through the necessary verification steps.

Initial State: UNVERIFIED

Every new order created with Two automatically starts with a state of UNVERIFIED.

The Goal: Achieving VERIFIED State

Even if an order has an APPROVED credit status, it cannot be fulfilled until its state transitions from UNVERIFIED to VERIFIED. This transition requires the buyer's representative to complete an active verification step with Two.

Standard Verification Process (Buyer-Interactive Flow)

Here's the most direct way to facilitate verification in a typical checkout experience where the buyer is present:

Create the Order: Submit the order details via the POST /v1/order endpoint.
Use the payment_url: The API response will contain a payment_url field. Redirect the buyer's representative to this URL.

This payment_url leads to a unique, Two-hosted page where the buyer completes the required verification steps. Successfully completing this process automatically updates the order's state from UNVERIFIED to VERIFIED.

Managing the payment_url

Aspect	Details
Activation	Becomes active once first opened
Lifespan	Valid for 24 hours after activation
Expiration	Verification will fail if used after the 24-hour window
Renewal	Obtain a fresh URL via `GET /v1/order/:order_id`

Verification Methods Employed by Two

Upon visiting the payment_url, the buyer's representative will be prompted to complete a verification step. The specific method Two employs (e.g., OTP via SMS/email, or Open Banking check) is determined dynamically by Two's risk assessment based on:

The representative's details
The buyer's company profile
The order amount

Redirecting the User After Verification

Control where the user is redirected after interacting with the payment_url page by setting URLs in the merchant_urls object during order creation:

URL	Purpose
`merchant_confirmation_url`	Redirect destination after successful verification
`merchant_cancel_order_url`	Redirect destination if buyer clicks "cancel"

Handling Buyer-Initiated Cancellation

Note

If a buyer is redirected to your merchant_cancel_order_url, Two does not automatically change the order's state from UNVERIFIED to CANCELLED. The order will remain UNVERIFIED, giving you flexibility to handle such situations.

Automatic Order Cancellation by Two (Timeout)

If an order remains in an UNVERIFIED state for more than 48 hours after creation, Two will automatically cancel it:

The order's state will change to CANCELLED
Any subsequent attempts to verify the order will be unsuccessful

Alternative Verification Scenarios (Asynchronous/Remote)

Some integrations may require asynchronous or remote verification:

Administrator-Initiated Orders: A service administrator creates a Two order on behalf of a buyer
In-Store POS Orders: A Two order is created through an in-store Point of Sale system

Using the Notify Endpoint

You can use the POST /v1/order/:order_id/notify endpoint to send a direct verification notification to the intended buyer for a specific order.

How it works:

Specify the desired communication channel (SMS or email) in the API request body
Upon a successful API call, Two issues the notification directly to the buyer
The buyer receives a message containing a unique link to complete verification

This method allows you to decouple the order creation from the immediate, on-screen verification.

Step 5: Post-Verification (Optional)

Once an order's state is VERIFIED, it's ready for fulfilment. However, there are additional considerations.

Optional Step: The CONFIRMED State

After an order is VERIFIED, you have the option to transition it to a CONFIRMED state via the POST /v1/order/:order_id/confirm endpoint.

Purpose: For your internal tracking and operational workflows
Merchant-Driven: Unlike VERIFIED, which Two sets automatically, CONFIRMED is triggered by you
Optional: A VERIFIED order can be directly fulfilled without ever entering the CONFIRMED state

Modifying Orders: Pre and Post-Verification

Editing UNVERIFIED Orders

You have flexibility to modify order details
If you change the order amount, Two will re-evaluate the credit status
If the new amount exceeds the buyer's credit limit, the status may change to REJECTED

Editing VERIFIED Orders

Once verified, the original credit approval is tied to the specific order amount at the time of verification:

Decreasing Order Amount: Generally allowed and retains APPROVED status
Increasing Order Amount: Strongly discouraged – likely to result in REJECTED status

Best Practice for Order Adjustments

Finalise Before Verification: Aim to finalise all order details before the buyer completes verification
Post-Verification Reductions: Limit adjustments to those that reduce the total order value
Post-Verification Increases: Cancel the existing order and create a new one with the correct details

Step 6: Fulfilment

Once an order is VERIFIED (and optionally CONFIRMED), the final step is fulfilment.

What is Fulfilment in Two?

Fulfilment signifies that you are ready to complete the order, which triggers Two to:

Issue the final invoice to the buyer
Arrange your payout

Triggering Fulfilment

To generate the final invoice and start the buyer's payment term window, use the POST /v1/order/:order_id/fulfillments endpoint.

The Fulfilment States

VERIFIED → FULFILLING → FULFILLED

API Call: Call the fulfillments endpoint for a VERIFIED order
Transition to FULFILLING: An interim, transitional state
Automatic Transition to FULFILLED: Two's batch job processes the order
Order Complete: Invoice email sent, payout processed, repayment term begins

Conclusion

Successfully integrating Two's order creation and processing workflow hinges on carefully managing the order status (for credit approval) and its state (for verification and fulfilment progress).

Summary

Step	Focus	Key Endpoints
1	Identify	Company API (GET)
2	Assess	POST /v1/order_intent
3	Create	POST /v1/order
4	Verify	payment_url, POST /v1/order/:order_id/notify
5	Post-Verify	POST /v1/order/:order_id/confirm
6	Fulfill	POST /v1/order/:order_id/fulfillments

Step 1: Identify the Buyer​

Step 2: Proactive Credit Assessment (Order Intent)​

Step 3: Create Order & Check Status​

Step 4: Verification​

Initial State: UNVERIFIED​

The Goal: Achieving VERIFIED State​

Standard Verification Process (Buyer-Interactive Flow)​

Managing the payment_url​

Verification Methods Employed by Two​

Redirecting the User After Verification​

Handling Buyer-Initiated Cancellation​

Automatic Order Cancellation by Two (Timeout)​

Alternative Verification Scenarios (Asynchronous/Remote)​

Using the Notify Endpoint​

Step 5: Post-Verification (Optional)​

Optional Step: The CONFIRMED State​

Modifying Orders: Pre and Post-Verification​

Step 6: Fulfilment​

What is Fulfilment in Two?​

Triggering Fulfilment​

The Fulfilment States​

Conclusion​