Payment facts
Payment facts tell OrderEx what happened to the money for an order, so it can follow the money alongside the goods. OrderEx records them and never moves money: nothing is sent to a payment provider.
This guide continues the example order: 547.00 SEK is authorized at checkout, the authorization for the cancelled T-shirt is released, the shipped T-shirt and the delivery are captured, and the returned T-shirt is refunded.
The four types
type | What happened at the provider | Example |
|---|---|---|
Authorized | The money was reserved | 54700 at checkout |
Captured | Reserved money was charged | 29800 when the order shipped |
Refunded | Charged money was paid back | 24900 for the returned T-shirt |
AuthorizationReleased | A reservation was released without being charged | 24900 for the cancelled T-shirt |
paymentMethod is one of card, invoice, installment, swish, mobilepay, vipps,
bank_transfer, wallet, gift_card and other. Both fields are written exactly like this.
What you do
Record a capture, split per line
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/payment-facts" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "Captured",
"externalTransactionId": "cap-2026-7781",
"amount": 29800,
"currency": "SEK",
"paymentMethod": "card",
"providerName": "ExamplePay",
"occurredAt": "2026-11-16T14:12:00+01:00",
"allocations": [
{"orderLineId": "'"$TSHIRT_LINE_ID"'", "amount": 24900},
{"orderLineId": "'"$SHIPPING_LINE_ID"'", "amount": 4900}
]
}'
SHIPPING_LINE_ID is the id of the shipping line. OrderEx answers 201 Created with the fact.
amountis a whole number of at least 1, in the minor unit of the order's currency.currencymust be the order's currency, or OrderEx answers 422payment-currency-mismatch.externalTransactionIdis the provider's id of the transaction.
Split the money per line when you can
allocations say which lines the money is for. Each names a line of the order once, shipping and
fee lines included, and together they add up to amount. Otherwise OrderEx answers 422
payment-allocation-invalid, with every reason in reasons:
| Reason | What is wrong |
|---|---|
allocation-sum-mismatch | The allocations do not add up to amount |
allocation-line-not-on-order | A line is not a line of this order |
allocation-line-repeated | A line is named more than once |
Allocations are optional. A fact without them belongs to the order as a whole and is returned with
unallocated: true, as an authorization at checkout often is:
curl -sS -X POST "https://api.orderex.se/api/v1/orders/$ORDER_ID/payment-facts" \
-H "X-Api-Key: $ORDEREX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "Authorized",
"externalTransactionId": "auth-2026-7780",
"amount": 54700,
"currency": "SEK",
"paymentMethod": "card",
"providerName": "ExamplePay",
"occurredAt": "2026-11-14T10:12:00+01:00"
}'
Sending a fact again
A payment fact is identified by its type and externalTransactionId on the order. A capture and a
refund may share a transaction id.
- The same fact again, with the same content, returns
200 OKwith the fact as first recorded, and changes nothing. - The same type and transaction id with other content gives 409
fact-conflict, whoseexistingFactis the fact OrderEx has.
Read what the money adds up to
curl -sS "https://api.orderex.se/api/v1/orders/$ORDER_ID/payment-facts" \
-H "X-Api-Key: $ORDEREX_API_KEY"
The response has every fact and what they add up to:
| Field | What it holds |
|---|---|
totals | The sums of every fact on the order: authorized, captured, refunded and released |
unallocatedTotals | The sums of the facts without allocations |
lines | The sums allocated to each line, for every line of the order |
lines[].paymentKnownPerOrderOnly | true when the order has facts without allocations, so a line's sums are not the whole picture |
inconsistencies | The money that does not add up, on the order and on each line |
facts | Every fact, oldest first |
Money that does not add up is accepted and flagged
OrderEx does not reject a fact because the money does not add up. It records the fact and names the
problem in inconsistencies, so you see it instead of losing it:
| Code | When |
|---|---|
captured_exceeds_authorized | More is captured than authorized. Only on an order with at least one Authorized fact, so a payment without authorization, such as Swish, never gets it |
refunded_exceeds_captured | More is refunded than captured |
released_exceeds_open_authorization | More is released than is still authorized and not captured |
A code never changes a fact, the order status or a line, and it goes away when later facts make the sums add up. A line is judged only when no fact without allocations could belong to it; otherwise only the order is flagged.
Never send card numbers
OrderEx must not hold card numbers. A providerName that looks like a card number gives 400, and so
does such an externalTransactionId for the methods card, wallet and other. The error never
repeats the value.
Next
A reliable integration explains how to retry any of these calls safely.