Introduction

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:

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

Let's explore these in detail.

Proactive Credit Assessment with Order Intent

Using Order Intent can help you:

• Optimize API Usage: Avoid creating full orders if the initial credit assessment is unfavorable.
• 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.

Pillar 1: Order status – The Credit Decision

• APPROVED: Indicates Two can provide credit for this particular order.
• REJECTED: Signifies Two cannot offer a credit guarantee for the order amount at this time.

Pillar 2: Order state – The Verification Journey

Initial State: UNVERIFIED

The Goal: Achieving VERIFIED State

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:

1. Create the Order: Submit the order details via the POST v1/order endpoint.
2. Use the payment_url: The API response for a successful order creation will contain a payment_url field. You must redirect the buyer's representative to this Payment URL.

Managing the payment_url

• Activation and Lifespan: The payment_url becomes active once it's first opened and remains valid for 24 hours.
• Expiration: If a buyer attempts to use an opened payment_url after this 24-hour window, the verification will fail, and the order's state will not change.
• Renewal: Should the payment_url expire or if a new one is needed for any reason (e.g., the user closed the page and lost the link), you can obtain a fresh, unactivated payment_url by making a GET v1/order/<order_id> request for that specific order. This new link will also have a 24-hour active window once opened.

Verification Methods Employed by Two

Redirecting the User After Verification (merchant_urls)

• merchant_confirmation_url: After the buyer successfully completes the verification, they are automatically redirected here. Use this to guide them to an appropriate page on your site (e.g., an order confirmation page).
• merchant_cancel_order_url: If the buyer chooses to click a "cancel" action on Two's payment_url page, they will be redirected to this URL.

Handling Buyer-Initiated Cancellation on payment_url Page

Automatic Order Cancellation by Two (Timeout)

• Result: The order's state will change to CANCELLED.
• Consequence: Any subsequent attempts to verify the order using its payment_url will be unsuccessful.
• Confirming Auto-Cancellation: You can confirm this by fetching the order using its global Two order id; the API response will reflect the updated CANCELLED state.

Therefore, it is crucial to ensure that if you intend to progress an order for a credit-approved buyer, they complete the verification process within the 48-hour window following order creation.

Alternative Verification Scenarios (Asynchronous/Remote)

However, some integrations or operational needs may require asynchronous or remote verification. Common examples include:

• Administrator-Initiated Orders: A service administrator creates a Two order on behalf of a buyer. The buyer then needs to receive the verification request and complete it independently.
• In-Store POS Orders: A Two order is created through an in-store Point of Sale (POS) system. The buyer needs to complete the verification on their personal device (e.g., smartphone) to progress the order.

For these asynchronous or remote verification needs, Two provides a dedicated solution:

Using the POST v1/order/<order_id>/notify Endpoint

• How it works: You specify the desired communication channel (SMS or email) in the API request body.
• Outcome: Upon a successful API call, Two issues the notification directly to the buyer.
• Buyer Action: The buyer receives a message containing a unique link. Clicking this link takes them to the Two verification page where they can complete the necessary steps, similar to using the payment_url.

This method allows you to decouple the order creation from the immediate, on-screen verification, providing flexibility for various business workflows.

Pillar 3: Post-Verification Considerations and Actions

Optional Step: The CONFIRMED State

• Purpose: The CONFIRMED state is primarily for your internal tracking and operational workflows. It allows you, as the merchant, to explicitly acknowledge that the order has passed a certain checkpoint in your process post-Two verification (e.g., confirming the buyer successfully landed on your confirmation page).
• Merchant-Driven: Unlike the VERIFIED state, which Two sets automatically upon successful buyer verification, the CONFIRMED state is triggered by you via an API call.
• How to Trigger: To move a VERIFIED order to CONFIRMED, you use the POST v1/order/<order_id>/confirm endpoint. The order must be in a VERIFIED state before you can do this.
• Common Use Case: A typical scenario is to call this endpoint after your system detects that the buyer has successfully reached your merchant_confirmation_url. Since Two only redirects to this URL upon successful verification, a buyer landing there is a strong indicator of a successful Two verification. Using the CONFIRMED state can add an extra layer to your tracking.

Modifying Orders: Pre and Post-Verification

Editing UNVERIFIED Orders

• Flexibility: Before an order is VERIFIED, you have more flexibility to modify its details.
• Credit Re-evaluation: If you change the order amount (either by increasing or decreasing it), Two will re-evaluate the credit status.
  • If the new amount is still within the buyer's credit limit, the status will remain APPROVED.
  • If an increase pushes the order amount beyond the buyer's credit limit, the status may change to REJECTED.

Editing VERIFIED Orders

• Decreasing Order Amount: Generally, you can make changes that decrease the total order amount (e.g., reducing quantity, lowering a price). Such changes usually retain the APPROVED status.
• Increasing Order Amount: It is strongly discouraged to make changes that increase the total order amount on a VERIFIED order. This is highly likely to result in the order's status changing to REJECTED, as the original credit approval did not cover the higher amount.

Best Practice for Order Adjustments:

1. Finalize Before Verification: Aim to finalize all order details (items, quantities, prices) before the buyer completes the verification process and the order becomes VERIFIED.
2. Post-Verification Reductions: If adjustments are needed after verification, limit them to those that reduce the total order value.
3. Post-Verification Increases: If the order amount needs to be increased after verification, the safest approach is to cancel the existing VERIFIED order (if your policy allows and before fulfilment) and create a new order with the correct details. This new order will then go through the standard credit check and verification process.

This approach ensures that you always have a valid credit approval for the order amount you intend to fulfil.

Pillar 4: Order Fulfilment – Completing the Process

What is Fulfilment in Two?

In the Two ecosystem, fulfilment signifies that you are ready to complete the order, which in turn triggers Two to issue the final invoice to the buyer and arrange your payout.

• Two has approved credit for the order amount.
• The buyer's identity has been successfully verified.

However, no invoice has been issued to the buyer, nor has a payout been initiated to you, the merchant.

Triggering Fulfilment

This guide focuses on standard, full fulfilment. For details on fulfilling orders in parts, please refer to our the fulfillments endpoint.

The Fulfilment States: FULFILLING to FULFILLED

1. API Call: When you call the POST v1/order/<order_id>/fulfillments endpoint for a VERIFIED order.
2. Transition to FULFILLING: Upon a successful API call, the order's state transitions to FULFILLING. The API response will include the updated order schema reflecting this.
   • FULFILLING is an interim, transitional state.
3. Automatic Transition to FULFILLED: Two runs a continuous batch job that processes orders in the FULFILLING state. An order in the FULFILLING state is guaranteed to progress to FULFILLED once this batch job processes it.
4. Order Complete (FULFILLED): When the order's state becomes FULFILLED:
   • The order is considered complete from Two's perspective.
   • An automated invoice email, including a PDF invoice, is sent to the buyer representative's email address.
   • Your payout for this invoice amount will be processed according to your agreed payout cycle.
   • The buyer's repayment term window begins.

This completes the "happy path" for an order processed through Two.

Conclusion