Comprehensive Integration Assessment

Introduction

Welcome to your essential guide for evaluating your integration with Two's B2B payment solutions. This document provides a structured approach to help you meticulously assess your setup, ensuring it's robust, reliable, and offers a seamless purchasing experience for your business customers.

A thorough assessment is paramount for a successful launch and sustained operational excellence. By systematically working through the checkpoints below, you can proactively identify potential issues, confirm critical functionalities, and ensure your integration aligns with Two's best practices. This diligence will lead to greater buyer satisfaction and smoother transactions.

Important Note: This guide offers a comprehensive set of general checkpoints. Depending on the specific Two API endpoints and features you've implemented (e.g., Order API, Trade Account API, Billing Accounts), there may be additional considerations unique to your integration. Always consult the relevant API documentation for detailed specifications and advanced scenarios.

Core Principles for a Successful Integration

Before diving into specific feature checks, keep these overarching principles in mind:

• User Experience (UX): Prioritize a clear, intuitive, and frictionless journey for your B2B buyers at every touchpoint.
• Robust Error Handling: Implement comprehensive error handling that provides clear, actionable feedback to users and logs detailed information for efficient troubleshooting by your development team.
• Data Accuracy & Consistency: Ensure all data exchanged with Two (e.g., order details, company information, amounts, addresses) is precise, correctly formatted, and consistent across systems.
• Security Best Practices: Adhere to all security best practices for API integrations, diligently protecting sensitive data and API credentials.
• Thorough Testing: Test all user flows and system interactions exhaustively, including successful paths ("happy paths"), edge cases, and potential failure points.

Integrating the Two Order API

This section focuses on the core lifecycle of an order when processed through Two's Checkout API. A well-tested Order API integration is fundamental to processing B2B transactions with Two.

1. Presenting Two as a Payment Option

• Conditional Display Logic:
  • Is Two correctly presented as a payment option exclusively to eligible B2B buyers?
  • Consider if this involves checks after successful company identification (e.g., via Company API or your own KYB solution) or credit approval (e.g., after an Order Intent check).
• Clarity of Payment Terms:
  • Does the checkout clearly communicate any relevant payment terms (e.g., "Pay by Invoice," "Net 30 Days") associated with choosing Two?
  • Are these terms dynamically and accurately displayed based on the buyer or order context, if applicable?
• Visual Presentation:
  • Is the Two payment option clearly identifiable and visually consistent with your checkout design?

2. Order Creation & Buyer Verification

• Successful Order Placement (POST /v1/order):
  • Can orders be successfully created with all required fields (e.g., buyer_company, line_items, gross_amount, currency, merchant_urls)?
  • Verify the accuracy and correct formatting of all data sent, including shipping_address, billing_address, buyer.representative, and any metadata.
  • Test with various valid and potentially problematic data inputs (e.g., special characters, different address formats).
• Buyer Verification Flow (Two Hosted Page):
  • Are buyers correctly redirected to Two's payment_url for verification when the order status is APPROVED and state is UNVERIFIED?
  • Does the verification process on Two's hosted page handle both successful and unsuccessful outcomes gracefully?
  • Are buyers correctly redirected back to your specified merchant_urls.confirmation_url upon successful verification?
  • Are buyers correctly redirected back to your specified merchant_urls.cancel_url if they cancel?
  • Is the merchant_urls.error_url correctly utilized for unrecoverable errors during the Two-hosted verification?
• Handling API Responses:
  • Does your system correctly interpret and act upon all relevant HTTP status codes and response bodies from the Order API?
  • Are validation error messages (e.g., for missing or malformed fields) handled appropriately, potentially with user-friendly feedback?
  • Is the id (Two's order ID) from the response correctly stored in your system?

3. Order Confirmation

• Internal Order State Update:
  • Is your internal order status correctly updated (e.g., to CONFIRMED, AWAITING_FULFILMENT) after successful order placement and buyer verification with Two? (Note: Two's order STATE becomes VERIFIED after buyer verification, and you can then call POST /v1/order/<order_id>/confirm to move it to CONFIRMED).
• Buyer Communication:
  • Does the buyer receive an appropriate and timely order confirmation from your system (e.g., email, on-screen message) detailing the successful order and next steps?
  • Ensure this confirmation aligns with the information processed by Two.

4. Order Fulfilment

• Triggering Invoicing (POST /v1/order/<order_id>/fulfillments):
  • When an order is marked as fulfilled in your system, is the fulfilment correctly communicated to Two using the fulfillments endpoint?
  • Is the invoicing process by Two initiated correctly upon successful fulfilment?
• Fulfilment Data Accuracy:
  • Are all necessary and accurate fulfilment details (e.g., fulfilled_line_items, tracking_info, terms.duration_days if applicable) sent to Two?
  • Test partial vs. full fulfilments if your business logic supports them.
• Fulfilment Confirmation:
  • Does your system correctly handle the response from the fulfillments endpoint?
  • Is the order STATE in Two correctly updated to FULFILLED?

5. Order Modifications & Cancellations

• Order Editing (Before Fulfilment):
  • If your integration supports order edits (e.g., changing quantities, items, amounts) before fulfilment, are these changes correctly communicated and reflected in Two using the PUT /v1/order/<order_id> endpoint?
  • Verify that changes in amounts or line items are accurately updated.
• Order Cancellation (POST /v1/order/<order_id>/cancel):
  • Can orders be successfully cancelled via the cancel endpoint before fulfilment?
  • Is the order STATE updated appropriately to CANCELLED in both your system and Two?
  • What happens if you attempt to cancel an already fulfilled or invoiced order? (This should typically be disallowed or handled as a refund).

6. Refund Processing

• Full Refunds (POST /v1/order/<order_id>/refund):
  • Can you successfully process full refunds for orders paid via Two?
  • Ensure the reason and refunded_line_items (if applicable) are correctly sent.
• Partial Refunds:
  • Can you successfully process partial refunds (e.g., for specific line items or a custom amount)?
  • Verify that the refunded amounts and items are accurate.
• Refund Status & Communication:
  • Is the refund status correctly tracked in your system and reconciled with Two?
  • Does Two issue a credit note to the buyer upon successful refund processing?
  • Is the order STATE (or a representation of it) updated to REFUNDED or PARTIALLY_REFUNDED as appropriate?

7. Data Accuracy in Orders & Invoices

• Amounts & Calculations:
  • Are gross amounts, net amounts, tax amounts, and any discounts calculated correctly and consistently between your system, the data sent to Two, and the final Two invoice/credit note?
  • Verify handling of shipping fees and other charges.
• Line Item Details:
  • Do line item descriptions, SKUs, quantities, unit prices, and total prices match on the order, the data sent to Two, and the subsequent invoice?
• Company and Address Information:
  • Is the buyer's company name, registration number, billing address, and shipping address accurately reflected on Two's invoices?

8. Webhooks (Optional but Recommended)

• Webhook Subscription: If using Order Webhooks, have you correctly subscribed to relevant events (e.g., invoice.issued, invoice.credited, payment.received)?
• Endpoint Handling:
  • Can your webhook endpoint reliably receive and process notifications from Two?
  • Is signature verification implemented to ensure webhook authenticity?
• Data Reconciliation:
  • Are you using webhook data to keep your internal systems synchronized with Two's order and payment statuses?

Integrating Trade Accounts (Trade Account API)

If you are enabling buyers to create and use trade accounts for a more streamlined B2B purchasing experience, thorough testing of the Trade Account API is crucial.

1. Company Account Creation & Management

• Creating a Trade Account (POST /v2/merchant/<merchant_id>/customer):
  • Can you successfully create a new trade account (company customer) with all required information (e.g., merchant_customer_id, legal_name, organization_id, country_prefix, official_address)?
  • Verify the handling of optional fields like email_domain and billing_email_address.
  • Does the API response correctly indicate approved_for_credit status and provide credit limit details?
  • How does your system handle scenarios where a company already exists (e.g., 409 Conflict)? Do you use the GET /v2/merchant/<merchant_id>/customer_lookup/<merchant_customer_id> endpoint to retrieve existing details?
• Updating a Trade Account (PUT /v2/merchant/<merchant_id>/customer/<customer_id>):
  • Can you successfully update existing trade account details?

2. User Registration & Verification under a Trade Account

• Registering a User (POST /v2/merchant/<merchant_id>/customer/<customer_id>/user):
  • Can individual buyer representatives be successfully registered under an existing trade account with required details (merchant_user_id, email, first_name, last_name, verification_success_redirect_url)?
  • Is the user_verification_url from the response correctly captured and presented to the user?
• User Verification Flow:
  • Does redirecting the user to the user_verification_url lead to Two's verification page?
  • Upon successful user verification, are they correctly redirected to your verification_success_redirect_url?
  • Can you check a user's verification status using GET /v2/merchant/<merchant_id>/customer/<customer_id>/user/<user_id> and confirm the verified field is true?
• Notifying Users for Verification (POST /v2/merchant/<merchant_id>/customer/<customer_id>/user/<user_id>/notify):
  • If using the notify endpoint, does it successfully trigger a verification notification (e.g., email) to the user?

3. Leveraging Verified Trade Accounts in Orders

• Associating Orders with Verified Users:
  • When creating an order (POST /v1/order), if you include the merchant_user_id (in the root of the request) of a verified: true user, does this lead to a more streamlined checkout experience (e.g., potentially skipping some verification steps normally handled by the payment_url)?
  • Confirm that the order is correctly associated with the trade account user.

4. Handling API Responses & Errors

• Response Interpretation:
  • Does your system correctly interpret success and error responses from all used Trade Account API endpoints?
  • Are user-facing messages clear if an issue occurs during trade account creation or user registration?

Going Live with a Plugin

Two's e-commerce plugins (e.g., for Shopify, WooCommerce, Magento) are designed for quick setup and are rigorously tested. However, to ensure a smooth transition to live operations, we strongly recommend the following steps:

1. Sandbox Testing (Crucial):
   • Obtain Sandbox Keys: First, ensure you have your sandbox API keys from the Two Merchant Portal. Refer to our guide on Getting API Keys if needed.
   • Configure Plugin in Sandbox Mode: Set up the Two plugin in your e-commerce platform's staging or development environment using these sandbox keys.
   • Place Test Orders: Conduct several test orders covering various scenarios:
     • Successful order placement by a new B2B customer.
     • Successful order placement by an existing/returning B2B customer.
     • Orders with different product types or values.
     • Attempted orders that might be declined (if possible to simulate).
     • Order fulfilment.
     • Order cancellation (if supported by the plugin before fulfilment).
     • Processing refunds (full and partial).
   • Verify Data Flow: Check that order details, customer information, and amounts are correctly captured by the plugin and reflected in your Two Merchant Portal (sandbox view).
   • Rule out Conflicts: This testing helps identify any potential conflicts with other plugins or custom themes in your e-commerce setup.
   • Familiarize with Order Flow: Understand how Two orders appear and are managed within your e-commerce platform's admin panel.
2. Review Plugin Configuration:
   • Double-check all plugin settings to ensure they match your business requirements (e.g., payment method display name, any specific terms or conditions).
3. Contact Two for Production Access:
   • Once you are satisfied with sandbox testing and confident that everything works as expected, get in touch with your Two contact point or our support team (support@two.inc).
   • We will assist you in switching your Merchant Portal account to production mode, allowing you to obtain your live API keys.
4. Switch to Production Keys:
   • Replace the sandbox API keys in your plugin configuration with your new production API keys.

By following these steps, you can confidently go live with a Two plugin, minimizing unforeseen issues and ensuring a positive experience for your B2B customers.

Automated Integration Assessment Tool

Two provides an automated tool within the Merchant Portal designed to help you track your integration progress against common milestones.

1. Access the Portal: Navigate to the Integration Progress tab in the Two Merchant Portal and log in with your merchant credentials.
2. Review Checklist: The portal presents a checklist of key integration points. As you implement and test these features in your integration, you can see your progress visually reflected.

Example: Integration Progress view in the Two Merchant Portal.

Important Considerations for the Automated Assessment:

• Guidance, Not Exhaustive: This automated tool is a valuable supplementary resource that provides a dynamic overview of your testing and assessment milestones. However, it is not exhaustive and may not cover every specific requirement of your unique integration or all API endpoints you might be using (e.g., advanced features or specific regional configurations).
• Supplement to Manual Checks: We strongly recommend using this tool in conjunction with the detailed manual checks outlined in this comprehensive guide and your own rigorous internal testing procedures. It should not replace thorough manual validation.
• Not Strictly Required for All Integrations: Depending on your specific integration needs (e.g., if you are only using a subset of Two's APIs or a specific plugin), not all items in the automated checklist may be applicable or necessary for your go-live. Focus on the aspects relevant to your implementation.

If you have any questions about your specific integration progress or the automated assessment tool, please reach out to our integration team at integration@two.inc.

General Integration Health Checks

Beyond specific API functionalities, consider these general aspects for a high-quality, resilient integration:

• Comprehensive Error Handling & Logging:
  • Are user-facing error messages clear, concise, helpful, and do they guide the user on what to do next (without exposing sensitive system details)?
  • Does your system log detailed error information from API responses (including request IDs, timestamps, and full error messages from Two) for effective troubleshooting and support?
• Regional & Localization Testing:
  • If you operate in multiple regions or support multiple languages:
    • Have you tested the entire checkout and order management flow for each region, considering local company data formats, currencies, and tax regulations?
    • Are all user-facing texts (including those related to Two payments) correctly localized?
• User Experience (UX) Consistency:
  • Is the checkout experience consistent for new B2B buyers versus returning or logged-in buyers?
  • Is the Two payment flow seamlessly integrated into your existing website design and user journey, providing a cohesive experience?
• Compatibility with Other Systems/Plugins:
  • If Two is offered alongside other payment methods or integrated with other backend systems (ERP, CRM), ensure there are no conflicts and the selection/data flow process is clear and reliable.
• Performance & Scalability:
  • Monitor the performance of API calls to Two. Ensure that the integration does not introduce unnecessary delays to the checkout process or other critical user interactions.
  • Consider if your integration can handle peak load scenarios.
• Security of Credentials:
  • Are your Two API keys stored securely and not exposed in client-side code or version control?
• Documentation & Training:
  • Have you documented your Two integration details internally for your support and development teams?
  • Are relevant staff members trained on how to manage Two orders and handle related customer inquiries?

Conclusion

Thoroughly assessing your Two integration is a critical investment towards providing a seamless, reliable, and professional B2B purchasing experience. By methodically working through these checkpoints—covering the Order API, Trade Account functionalities, utilizing the automated assessment tool wisely, preparing for plugin go-lives, and performing general health checks—you can launch with confidence and build lasting trust with your business customers.

Remember, a well-tested integration minimizes potential issues, reduces support overhead, and sets the stage for smooth, scalable B2B operations with Two.

Should you have any questions or require assistance during your assessment, please do not hesitate to contact your Two representative or our dedicated support team at integration@two.inc. We are here to help you succeed!