Webhooks portal

The Checkout API Order Webhooks allow merchants to gain visibility into how we reconcile incoming payments for the orders placed through our Two Checkout API service. This feature serves two purposes: first, it enables you to keep your internal records up to date and respond to queries, and secondly, it allows you to directly expose this information to your buyers.

We facilitate webhook consumption using the SVIX portal. To learn how to start consuming webhooks through the portal, please refer to the SVIX documentation.

Webhook postman collection

You can download our webhook simulation postman collection here to get started

Step 1: Prerequisite Conditions

Before accessing the Order API (our Checkout API), please send a request to webhooks@two.inc with the subject "API Access to CK-API for Webhook Testing."

Step 2: Type of webhook events and how to trigger them

The Order API Webhooks offer the following events:

  • reconciliation-invoiced
  • reconciliation-payment-allocated (dealocated)
  • reconciliation-payment-credited
  • reconciliation-recoursed
  • reconciliation-collected
  • credit-limit-change
  • billing-statement-issued

For these reconciliation events, we use common attributes across all the order.reconciliation event types. An example of these attributes is provided below, along with a description of each field:

Copy
Copied
{
    "data": {
        "root_order_id": "652a57e2-c2de-437b-96a7-2eeac0a37814",
        "order_id": "a9f5d2d3-5d6d-4e2a-a4b4-6c7f8a9d0f1e",
        "invoice_id": "7a5a7b9b-7d9e-4e9e-b9b1-2d7c658e1a4d",
        "merchant_id": "b6b9d5d1-f6b7-4e15-9703-9c32c6e5c1c2",
        "billing_period_id": "175bda61-c6f2-4b9d-a429-5f31c83ecc10",
        "amount": "100.00",
        "currency": "GBP"
    }
}
  • root_order_id: The original order ID this order stems from. This is only useful for orders that are partially fulfilled, where the order_id will be a child or descendant of the root order.
  • order_id: A unique identifier for the order. For non-partial fulfilments this will match the root_order_id. If the event relates to a child order arising from partial fulfilment, this order_id will be different from the root_order_id.
  • invoice_id: A unique identifier for the invoice as represented in Two's system.
  • billing_account_id: A unique identifier representing the buyer's billing account (which describes how the buyer is to be invoiced for this order). If not associated with a billing account, will be null.
  • merchant_id: A unique identifier for the merchant in Two's system. Will typically match the twomerchantid in the top level of the event.
  • billing_period_id: A unique identifier for the statement/grouping this order will be included in, if any. If the order is not included in a statement, will be null.
  • amount: The financial amount associated with this event. For invoices this will be negative. For payments to Two or other reductions in the debt owed by the buyer this will be positive.
  • currency: An ISO 4217 alphabetic currency code representing the currency of the amount.

Invoice issued event

  • To initiate testing of the webhooks, you must first create an order through the checkout API service in your sandbox environment. Please refer to the linked endpoint to learn how to create a Two order
  • After successfully creating an order, capture the globally unique id generated in the CREATE ORDER response. You can directly reference this id field in the documentation response schema here
  • Continue with the normal order flow by verifying the order. Visit the payment_url link provided in the CREATE ORDER response. This action will transition the order state from UNVERIFIED to VERIFIED assuming successful verification. To mark the order as FULFILLED, make use of the fulfil order endpoint
  • While awaiting completion of the fulfilment process, the order state will progress from FULFILLING to FULFILLED. Upon successful fulfilment, a webhook event will be delivered to any subscribed endpoint. The event will also be visible in the Svix app portal. Simultaneously, the email address set in buyer.representative.email while creating the order will receive an invoice email from Two. Note that if the billing_account_id field was set while creating the order, this email will not be sent, instead the representative will receive an email when the periodical grouped payment statement is generated. This coincides with the billing statement created webhook event.

Invoice credited event

  • After successfully creating an order and fulfilling, you may proceed to refund the same order by using the REFUND order endpoint. Once the refund process is completed, you will receive a <credited_event> webhook event.

Step 3: How to emit fake webhooks based on schemas

First open your application through the SVIX portal.

Select the webhook subscription that you have created

Now that you have chosen your subscription, you can select the testing tab. To begin sending example webhook events.

You can select an event type from the drop-down options right here. In this example, we have chosen the "Order Invoice Issued Reconciliation Event." When you click the "Send Example" button on this portal view, you'll be able to see a mocked webhook response of what the subscriber will receive for the selected event.

There is an additional view in the SVIX play window. This can be accessed by clicking the three vertical dots menu in the top right corner and selecting "View in SVIX Play".

See the image below for a view of the SVIX play portal and what the subscriber sees.