Skip to main content

Payment facts

2026-11-15 · Not breaking · Upcoming: not yet in production

Payment facts: POST /api/v1/orders/{id}/payment-facts records an authorization, capture, refund or released authorization once, split per order line when you have the split. OrderEx records payment facts and never moves money: nothing is sent to a payment provider.

What changed

  • For example {"type": "Captured", "amount": 29800, "currency": "SEK", "paymentMethod": "card", "providerName": "ExamplePay", "externalTransactionId": "cap-2026-7781", "occurredAt": "2026-11-16T14:12:00+01:00", "allocations": [{"orderLineId": "...", "amount": 24900}, {"orderLineId": "...", "amount": 4900}]} gives 201 with the fact: id, orderId, the fields sent, occurredAt and recordedAt in UTC with microseconds, source api, unallocated and allocations.
  • type is Authorized, Captured, Refunded or AuthorizationReleased, and paymentMethod one of card, invoice, installment, swish, mobilepay, vipps, bank_transfer, wallet, gift_card and other, both in exactly that case; any other value gives 422 https://orderex.io/problems/unknown-payment-fact-type or https://orderex.io/problems/unknown-payment-method with allowed.
  • Amounts are whole numbers of at least 1 in the minor unit, as in change 9, and are never rounded (else 422 https://orderex.io/problems/invalid-amount with errors).
  • currency must be the order's, in any letter case (else 422 https://orderex.io/problems/payment-currency-mismatch with orderCurrency).
  • The optional allocations name each line of the order at most once, shipping and fee lines included, and add up to amount (else 422 https://orderex.io/problems/payment-allocation-invalid with every reason in reasons and the lines in orderLineIds); without them the fact is unallocated.
  • No card numbers: a providerName that looks like one (13 to 19 digits passing the Luhn check, spaces and hyphens ignored) is a 400 for every method, and so is such an externalTransactionId for card, wallet and other; for the other methods it is accepted, since OCR and KID references use the same check digit.
  • The same type and externalTransactionId with the same content returns 200 with the fact as first recorded, with other content 409 https://orderex.io/problems/fact-conflict.
  • A fact is accepted in every order status and changes neither the status nor a line, and money that does not add up, such as refunded above captured, is accepted.
  • The checks run in this order: 422 invalid-amount from binding, 400, 422 for an unknown type or method or an amount below 1, 422 occurred-at-in-future, the Idempotency-Key, 404 order-not-found, the transaction id (200 or 409 fact-conflict), 422 payment-currency-mismatch, 422 payment-allocation-invalid, 422 invalid-amount for the order's sum of the type, 201.
  • The order timeline gets orders.payment_fact_recorded.v1 on factOccurredAt; it is not a webhook.

Affected operations

  • POST /api/v1/orders/{id}/payment-facts, new
  • GET /api/v1/orders/{id}/timeline

What you do

  • Nothing, unless you want to record payment facts: then send each authorization, capture, refund and released authorization once, with the provider's transaction id.