Skip to main content

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​

typeWhat happened at the providerExample
AuthorizedThe money was reserved54700 at checkout
CapturedReserved money was charged29800 when the order shipped
RefundedCharged money was paid back24900 for the returned T-shirt
AuthorizationReleasedA reservation was released without being charged24900 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.

  • amount is a whole number of at least 1, in the minor unit of the order's currency.
  • currency must be the order's currency, or OrderEx answers 422 payment-currency-mismatch.
  • externalTransactionId is 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:

ReasonWhat is wrong
allocation-sum-mismatchThe allocations do not add up to amount
allocation-line-not-on-orderA line is not a line of this order
allocation-line-repeatedA 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 OK with the fact as first recorded, and changes nothing.
  • The same type and transaction id with other content gives 409 fact-conflict, whose existingFact is 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:

FieldWhat it holds
totalsThe sums of every fact on the order: authorized, captured, refunded and released
unallocatedTotalsThe sums of the facts without allocations
linesThe sums allocated to each line, for every line of the order
lines[].paymentKnownPerOrderOnlytrue when the order has facts without allocations, so a line's sums are not the whole picture
inconsistenciesThe money that does not add up, on the order and on each line
factsEvery 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:

CodeWhen
captured_exceeds_authorizedMore 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_capturedMore is refunded than captured
released_exceeds_open_authorizationMore 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.