Order and transaction status

Find out whether you've been paid. Learn which status to check, when to check it, and what every order and transaction status means.

Every payment you create with Paytrim is an order with one or more transactions. The order stands for what your customer buys: their order or shopping basket. A transaction is a payment attempt for that order, with a specific payment method. Both have a status, and you base your business logic on one of them.

Which status to check

Integration	Check	Why
Hosted payment page and payment links	Order `status`	Your customer can try several payment methods, so an order can have several transactions. The order status sums them up.

When to check

Retrieve the order with GET /v1/orders/{order_id}/ to get the latest status at any moment. To make sure you never miss a status change, combine these three mechanisms:

When your customer returns. Retrieve the order as soon as your customer lands on your return_url, and show the result.
Periodically. Retrieve every order that isn't final yet (new or processing) at a regular interval. Pick an interval that suits your business: if you reserve concert tickets for 15 minutes, check within those 15 minutes.
On a webhook. Retrieve the order when you receive a webhook. Webhooks are fast, but can be delayed or lost because of network problems, so don't rely on them alone.

Don't trust the redirect

Your customer can close the browser before they're redirected, and anyone can open your return_url. Always retrieve the order from your server before you confirm the payment or deliver.

Retrieve an order

curl https://api.pay.paytrim.com/v1/orders/4c6afd74-a840-4aab-b411-1e6e0636d341/ \
  --user "$API_KEY:"

The response contains the order and all of its transactions. This example shows a completed card payment (shortened):

{
  "id": "4c6afd74-a840-4aab-b411-1e6e0636d341",
  "amount": 100,
  "currency": "EUR",
  "description": "Example order #1",
  "merchant_order_id": "EXAMPLE001",
  "return_url": "https://www.example.com/order/EXAMPLE001",
  "created": "2026-09-20T08:51:10.078503+00:00",
  "completed": "2026-09-20T08:52:02.357623+00:00",
  "status": "completed",
  "transactions": [
    {
      "id": "6a0bdf56-53c3-4ce3-8189-4a73d775ac66",
      "amount": 100,
      "currency": "EUR",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "truncated_pan": "414141******4141",
        "vault_token": "e3ed069e-c931-40ae-8035-e022e8a4e5e7"
      },
      "events": [
        {
          "event": "new",
          "id": "3cb2259b-a3f9-4908-bb98-eb51c773fc70",
          "occurred": "2026-09-20T08:51:10.091203+00:00",
          "source": "set_status"
        }
      ],
      "status": "accepted"
    }
  ]
}

Order statuses

Status	Meaning	Final
`new`	The order has been created.	No
`processing`	All transactions of the order are pending or processing.	No
`completed`	All transactions of the order are accepted or completed. You can deliver.	Yes
`cancelled`	All transactions of the order are cancelled.	Yes
`expired`	The order expired, for example because your customer didn't pay in time.	Yes
`error`	The order failed, because a transaction was declined or for technical reasons.	Yes
`see-transactions`	The transactions of the order have different statuses. Don't take automatic action: check the individual transactions.	No

A typical order goes through these statuses:

Paid: new → processing → completed
Not paid: new → processing → cancelled, expired or error
Abandoned: new → expired, when your customer never starts a payment

Transaction statuses

Status	Meaning
`new`	The transaction has been created.
`pending`	The transaction has started and waits for an action, for example your customer completing 3-D Secure authentication.
`processing`	The transaction is being processed.
`accepted`	The payment succeeded.
`cancelled`	Your customer cancelled the payment before it was completed.
`expired`	The transaction expired before it was completed.
`error`	The payment was declined, or failed for technical reasons. The transaction has a `reason` field: see Error reasons.

Transaction events

Every transaction keeps a log of what happened to it in the events array. Each event has a type (event), the moment it happened (occurred) and the moment Paytrim registered it (noticed).

When you refund a payment, partially or in full, the original transaction gets a refunded event. The refund itself is a new order with its own transaction, linked to the original through refund_of_order_id and refund_of_transaction_id.

Order and transaction status

Which status to checkCopy Anchor Link

When to checkCopy Anchor Link

Retrieve an orderCopy Anchor Link

Order statusesCopy Anchor Link

Transaction statusesCopy Anchor Link