Skip to main content

Payment Allocation

Webhook

Type: order.reconciliation.payment_allocated.v1

Occurs when either:

  1. A payment is made and confirmed as allocated to a specific invoice or statement issued by Two.
  2. A previously matched payment is deallocated, for example when a credit note takes priority over the payment.

It is important to note these webhooks are sent only once the payment has been matched (or unmatched) in Two's system to a specific invoice or statement, so there may be a delay between the buyer making the payment and Two being able to match that payment to an invoice/statement.

As an example, the following sequence of events show when this webhook may be issued:

  • A buyer is issued with an invoice of 1000 GBP (Two issues an Order Invoiced webhook).
  • The buyer later pays 400 GBP to Two using the reference provided on the invoice.
  • Two will match that payment to the invoice: a Payment Allocation webhook is issued.
    • The webhook payload will contain the invoice or statement reference Two matched the buyer's payment with (in the matched_reference attribute) as well as some details of the original payment made by the buyer in the payment object.
  • The buyer later makes another payment of 600 GBP to Two with the same reference (600 being the remaining balance to pay for that invoice).
  • Two matches the second incoming payment of 600 GBP to the same invoice: another Payment Allocation webhook is issued.
    • This webhook will have the same matched_reference value, but the details in the payment object will be different because it is a distinct payment from the original 400 GBP payment.
  • A credit note is issued against the original invoice of 300 GBP (Two issues a Order Credited webhook).
    • One of the payments Two previously matched will be "unmatched" because the refund of 300 GBP against specific invoices has a higher priority than payments. Two issues another Payment Allocation webhook, but the amount will be negative.

Payload​

The data object in the payload contains IDs that indicate the order and invoice the payment has been allocated to. Also note the following within the payload:

  • amount: The amount for this event represents the amount of the buyer's payment that has been used by this allocation. For payments to Two that are allocated to invoices, this amount will be negative. For deallocation events (for example, where a credit note has a higher priority than an already-reconciled payment and causes us to deallocate an existing allocation), the amount will be positive. A deallocation event would typically result in a later payment_allocated event where all or part of the same payment previously allocated is re-allocated against a different invoice; in this situation another payment allocation event will be sent.
  • payment: Contains data about the actual transaction Two received from the buyer that has been used in this payment allocation. See the schema description of this child object for details of each field.

Example​

{
    "specversion": "1.0",
    "id": "01FBJ0PYJ7931K0CJ6GMP8N3WG",
        "type": "order.reconciliation.payment_allocated.v1",
    "time": "2023-06-21T12:34:56.123456Z",
    "source": "https://api.two.inc",
    "subject": "order/a9f5d2d3-5d6d-4e2a-a4b4-6c7f8a9d0f1e",
    "twomerchantid":"b6b9d5d1-f6b7-4e15-9703-9c32c6e5c1c2",
    "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": "-123.45",
        "currency": "GBP",
        "matched_reference": "ACB12345",
        "payment": {
            "payment_id": "1346ef4c-fae1-43a2-b637-24e0c756d4ce",
            "payment_reference": "ABC12345",
            "booked_at": "2023-06-21T12:30:12.012345Z",
            "payment_amount": "500.05",
            "currency": "GBP"
        }
    }
}

Triggering in sandbox​

  1. Create and fulfil a new order (see the order.reconciliation.invoiced.v1 webhook description for how to do this) or use an existing order ID for the following steps.
  2. Use the "Simulate pay in" endpoint provided in the Two webhooks Postman collection.
  3. Once the simulated payment to us has been received the payment allocation webhook will be sent to any endpoints subscribed to this event.

Alternatively:

  1. Refund an order either fully or partially.
  2. A payment allocation webhook will be sent indicating an existing payment has been deallocated for this order to any endpoints subscribed to this event.

Request​

Responses​

Successful Response