Introduction

Why Use Order Intent?

Key Advantages:

• Enhanced Buyer Experience: By checking credit likelihood upfront, you can conditionally display "Pay by Two." If the intent is not approved, you can hide this option, preventing buyers from selecting a payment method that would ultimately be declined. This avoids a frustrating situation where a buyer completes a checkout, only to have their chosen payment method fail at the final hurdle (the POST /v1/order call).
• Reduced Integration Complexity: If an order_intent is approved: false, you can guide the buyer to alternative payment methods immediately, rather than creating an order that will be REJECTED for credit. As outlined in our Order Creation Path guide, a REJECTED order cannot proceed to verification or fulfilment.
• Optimized API Usage: Avoids unnecessary POST /v1/order calls for buyers who are unlikely to be approved for credit, streamlining your integration.
• Improved Approval Accuracy with Detailed Data: The order_intent schema mirrors the POST /v1/order schema. Providing comprehensive and accurate data—especially detailed line_items, buyer.representative information, and the correct gross_amount—allows Two to perform a more precise assessment, generally leading to more reliable intent responses and higher approval rates for subsequent orders.

Recommended Integration Flow

1. Buyer Finalizes Basket: The buyer assembles their cart or order details.
2. Gather Intent Data: Collect all necessary information for the order_intent call, mirroring what you would send for a POST /v1/order request. This includes full buyer company details, representative information, complete line items, and accurate total amounts.
3. Call POST /v1/order_intent: Send the request to Two.
4. Evaluate Response & See it in Action:
   • If approved: true: Confidently display "Pay by Two" as a payment option. Store the returned tracking_id.

     

   • If approved: false: Hide or disable "Pay by Two" for this transaction and prompt the buyer to select an alternative payment method.

     

5. Proceed to Order Creation (if approved): If the buyer selects "Pay by Two" (after a successful order_intent), proceed to call POST /v1/order. Include the tracking_id from the order_intent response in your POST /v1/order request to link the two.

This flow ensures that an order is only created with Two if there's a high probability of credit approval, leading to a smoother journey for the buyer. This is an example of how to deal with the order intent decision in a standard checkout flow, but this conditional consideration can be extended to however you shape your integration solution.

How to Use the v1/order_intent Endpoint

1. Gather Necessary Information

Key pieces of information include:

• Buyer Details (buyer object):
  • company: company_name, organization_number, country_prefix. (Tip: Use Two's Company API to get verified company details first).
  • representative: first_name, last_name, email, phone_number.
• Order Details:
  • gross_amount: The total amount of the potential order, including all taxes and charges.
  • currency: The currency of the transaction (e.g., "GBP", "USD", "EUR").
  • line_items (Highly Recommended and Crucial for Accuracy): An array of objects, each detailing a product or service. Include fields like name, description, quantity, unit_price, net_amount, tax_amount, tax_rate, and gross_amount for each item.
• Merchant Information:
  • merchant_id: Your unique merchant identifier provided by Two.

2. Make the API Request

Example Request Snippet (Conceptual):

{
    "gross_amount": "120.00",
    "currency": "GBP",
    "buyer": {
        "company": {
            "company_name": "Example Corp Ltd",
            "organization_number": "12345678",
            "country_prefix": "GB"
        },
        "representative": {
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@examplecorp.com",
            "phone_number": "+447123456789"
        }
    },
    "line_items": [
        {
            "name": "Premium Widget",
            "description": "High-quality widget for industrial use",
            "quantity": "2",
            "unit_price": "50.00",
            "net_amount": "100.00",
            "tax_rate": "0.20",
            "tax_amount": "20.00",
            "gross_amount": "120.00",
            "type": "PHYSICAL"
            // ... other line item details as per schema
        }
    ],
    "merchant_id": "your-unique-merchant-id",
    "order_origination": "ONLINE"
}

3. Interpret the Response

• approved: true: Indicates that, based on the provided information, Two is likely to approve a formal order for this buyer and amount. You can confidently display "Pay by Two" as a payment option. The response will also include a tracking_id. It is crucial to store this tracking_id as it should be passed in the subsequent POST /v1/order request.
• approved: false: Suggests that Two is unlikely to approve a formal order under the current conditions. You should hide "Pay by Two" for this transaction and guide the buyer to alternative payment methods.

Example Response Snippet (Conceptual):

{
    "approved": true,
    "tracking_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "decline_reason": null
}

Important Considerations

• Accuracy is Key: The order_intent assessment is only as good as the data provided. Ensure the information, particularly gross_amount, line_items, and buyer details, accurately reflects the intended order. Discrepancies between the order_intent and the actual POST /v1/order can lead to different outcomes.
• Strong Indicator, Not an Absolute Guarantee: While an approved: true from order_intent is a very reliable signal, the final, binding credit decision is made during the POST /v1/order call. Minor shifts in risk assessment or significant differences between the intent and order data could, in rare cases, change the outcome.
• Utilize the tracking_id: Always pass the tracking_id from an approved order_intent response into the corresponding POST /v1/order request. This links the preliminary check to the formal order, aiding Two's processes and providing a better audit trail.
• Session-Based Assessment: The order_intent response is typically valid for the current checkout session. If significant time passes or details change substantially, it's advisable to make a new order_intent call.

Conclusion