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,occurredAtandrecordedAtin UTC with microseconds,sourceapi,unallocatedandallocations. typeisAuthorized,Captured,RefundedorAuthorizationReleased, andpaymentMethodone ofcard,invoice,installment,swish,mobilepay,vipps,bank_transfer,wallet,gift_cardandother, both in exactly that case; any other value gives 422https://orderex.io/problems/unknown-payment-fact-typeorhttps://orderex.io/problems/unknown-payment-methodwithallowed.- 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-amountwitherrors). currencymust be the order's, in any letter case (else 422https://orderex.io/problems/payment-currency-mismatchwithorderCurrency).- The optional
allocationsname each line of the order at most once, shipping and fee lines included, and add up toamount(else 422https://orderex.io/problems/payment-allocation-invalidwith every reason inreasonsand the lines inorderLineIds); without them the fact isunallocated. - No card numbers: a
providerNamethat 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 anexternalTransactionIdforcard,walletandother; for the other methods it is accepted, since OCR and KID references use the same check digit. - The same
typeandexternalTransactionIdwith the same content returns 200 with the fact as first recorded, with other content 409https://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-amountfrom binding, 400, 422 for an unknown type or method or an amount below 1, 422occurred-at-in-future, theIdempotency-Key, 404order-not-found, the transaction id (200 or 409fact-conflict), 422payment-currency-mismatch, 422payment-allocation-invalid, 422invalid-amountfor the order's sum of the type, 201. - The order timeline gets
orders.payment_fact_recorded.v1onfactOccurredAt; it is not a webhook.
Affected operations
POST /api/v1/orders/{id}/payment-facts, newGET /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.