Payment histiry | API PayStar.uk

Payment history is a chronological timeline of key events in a transaction’s lifecycle—internal PS decisions, gateway requests/replies, user actions (UI/3DS/OTP), and callbacks. It helps you explain declines, debug routing/cascades, and understand user behavior. The array is returned by status endpoints and may be appended shortly after a final status due to asynchronous retries/logs. For full completeness, re‑query the status a bit later (see “Completeness tips” below).

Where you get orderHistory

orderHistory appears in responses of these status methods:

GET /deposit-order/{externalId}/status

GET /deposit-order/{externalTransactionId}/status-by-external-transaction-id

GET /withdrawal-order/{externalId}/status

GET /withdrawal-order/{externalTransactionId}/status-by-external-transaction-id

Callbacks & verification: You will also receive status via provider callbacks; verify the Signature header as described in Callbacks, and (recommended) confirm by calling the status endpoint.

Data model

Each history item is a minimal record:

{
  "time": "2025-07-28T09:29:51.339832Z",
  "action": "A.B.C.RR"
}

time — ISO‑8601 UTC timestamp

action — compact action code in the v2 format described below

Action code format

Structure: A.B.C.RR

Segment	Meaning	Allowed values
A	Stage	`1.PayStar` `2. Gateway: сreate` `3. HPP` `4. Polling gateway`
B	Operation result	`0.Info` `1. Success` `2. failed`
C	Payment state	`0. Init` `1. Created` `2 Pprocessing` `3. Success` `4. Failed` `5. Unchanged`
RR	Reason (group + detail)	`00 (none)`, `11..19 TECH`, `21..29 AUTHZ`, `31..39 BUSINESS`, `41..49 RISK`, `51..59 USER`, `61..69 ISSUER`

Reason dictionary (`RR`)

Channel note: payment channel (e.g., internal widget, P2P, SBP) is not encoded in the action code; handle it as a separate field/tag in your UI logs.

Examples

Example of orderHistory in callback or polling body

Success (Deposit)

{
  "externalId": "7b1f3c5a-96ab-4b77-8c8a-0f7b22c9fd01",
  "orderStatus": "Success",
  "amount": 2600.0,
  "orderHistory": [
    { "time": "2025-07-28T09:29:51.339832Z", "action": "1.1.1.00" },  // PayStar: payment created
    { "time": "2025-07-28T09:29:52.012311Z", "action": "2.1.1.00" },  // Gateway: payment created
    { "time": "2025-07-28T09:29:58.441902Z", "action": "4.1.3.00" },  // Gateway: payment success
 
  ]
}

Failure (Issuer insufficient funds)

{
  "externalId": "c4c1d7b0-5b6e-4aaf-9bc2-7c1a3c7a39b2",
  "orderStatus": "Failed",
  "amount": 2600.0,
  "orderHistory": [
    { "time": "2025-07-28T11:00:01Z", "action": "1.1.1.00" },
    { "time": "2025-07-28T11:00:02Z", "action": "2.1.1.00" },
    { "time": "2025-07-28T11:00:05Z", "action": "4.1.4.63" }  // payment failed, ISSUER.INSUFFICIENT_FUNDS
  ]
}

Action codes reference (by Stage)

DOWNLOAD

Codes_and_descriptions.json — download the full list of order history codes as a single JSON file.

This catalog lists typical events using the new A.B.C.RR semantics. (Not all flows will emit all events.)

1.1 PayStar: configuration issue (1.2.4.18.X)

A: 1.2.4.18 = PayStar

B: 1.2.4.18 = Operation failed

C: 1.2.4.18 = Order failed

RR: 1.2.4.18 = 18. CONFIG_ERROR

`HTTP`	`new_code`	Legacy error code	description
`500`	`1.2.4.18.1`	`1200-1-1`	Configuration issue — pipeline config is missing the payment form URL (formUrl)
`500`	`1.2.4.18.2`	`0000-911`	Configuration issue — endpoint has no pipeline configured (empty pipeline, no routes)
`500`	`1.2.4.18.3`	`0000-2`	Configuration issue — pipeline has no channel configured (empty pipeline, no channels)
`500`	`1.2.4.18.4`	`0000-180924`	Configuration issue — gateway integration config is invalid (wrong credentials or fields)
`500`	`1.2.4.18.5`	`0000-4`	Configuration issue — gateway implementation config is invalid (wrong fields)

1.2 PayStar: Request error (1.2.4.XX)

1.3 PayStar: Already exists (1.2.5.XX)

1.4 PayStar: processing (1.X.X.XX)

2.1 Gateway: processing (2.X.X.XX)

3.1 User: Hosted Payment Page (3.0.2.XX)

4.1 Check (polling the gateway) (4.X.X.XX)

Completeness & reliability tips

Asynchronous enrichment: The history may be updated shortly after you receive a final result. If you need a complete trace (including retries/callbacks), perform an additional status check later (e.g., ~10 minutes). ([apidoc.paystar.uk][1])

Callbacks + polling: Validate the callback Signature and still confirm with a status read for consistency. ([apidoc.paystar.uk][2])

Display labels: Keep the numeric code as the single source of truth. For user‑friendly UI, map codes to labels via i18n (e.g., Actor | Operation — Result [Reason] | Payment:<State>).

FAQ

How do I know a payment is final?

Why did new entries appear after I already got a final status?

Payment history

Data model#

Action code format#

Examples#

Success (Deposit)#

Failure (Issuer insufficient funds)#

Action codes reference (by Stage)#

Completeness & reliability tips#

FAQ#