Payment history v2 - PayStar API Documentation

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.C.B.RR"
}

time — ISO‑8601 UTC timestamp

action — compact action code in the v2 format described below

v2 action code format

Structure: A.C.B.RR

Segment	Meaning	Allowed values
A	Stage	1=PS (internal), 2=Gateway/Create, 3=Payform/UI, 4=Check (polling GW), 5=GW Callback, 6=Merchant Callback
C	Operation result	0=info, 1=success, 2=failure
B	Payment state	0=init, 1=created, 2=processing, 3=success, 4=failed
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`)

RR	Group	Detail
00	NONE	UNSPECIFIED
11	TECH	TIMEOUT
12	TECH	CONNECTION_FAIL
13	TECH	SERVER_UNAVAILABLE
14	TECH	INVALID_RESPONSE
15	TECH	INVALID_REQUEST
16	TECH	INVALID_SIGNATURE
17	TECH	INVALID_PAYLOAD
21	AUTHZ	401_UNAUTHORIZED
22	AUTHZ	403_FORBIDDEN
31	BUSINESS	BALANCE
32	BUSINESS	LIMIT
33	BUSINESS	CURRENCY
34	BUSINESS	ROUTING_BLOCKED
35	BUSINESS	AMOUNT_UPDATED
41	RISK	ANTIFRAUD_HARD
51	USER	PAGE_VISIT
52	USER	PAGE_LEAVE
53	USER	ENTER_PERSONAL_DATA
54	USER	CLICK_CANCEL
55	USER	CLICK_SUBMIT
56	USER	3DS_FAILED
57	USER	OTP_FAILED
58	USER	LEAVE_ON_CONFIRM
61	ISSUER	CARD_BLOCKED
62	ISSUER	CARD_NOT_SUPPORTED
63	ISSUER	INSUFFICIENT_FUNDS

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

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" },  // PS create → payment created
    { "time": "2025-07-28T09:29:52.012311Z", "action": "2.1.1.00" },  // GW create → payment created
    { "time": "2025-07-28T09:29:58.441902Z", "action": "4.1.3.00" },  // Check → payment success
    { "time": "2025-07-28T09:30:03.127600Z", "action": "5.1.3.00" }   // GW callback → 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)

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

1) PS internal (A=1)

Code	Description
1.0.0.00	Init — INFO \| Payment:init
1.1.1.00	Create — SUCCESS \| Payment:created
1.2.4.31	Pre‑check — FAILURE [BUSINESS.BALANCE] \| Payment:failed
1.2.4.32	Pre‑check — FAILURE [BUSINESS.LIMIT] \| Payment:failed
1.2.4.34	Pre‑check — FAILURE [BUSINESS.ROUTING_BLOCKED] \| Payment:failed

2) Gateway / Create (A=2)

Code	Description
2.1.1.00	Create — SUCCESS \| Payment:created
2.2.4.11	Create — FAILURE [TECH.TIMEOUT] \| Payment:failed
2.2.4.12	Create — FAILURE [TECH.CONNECTION_FAIL] \| Payment:failed
2.2.4.13	Create — FAILURE [TECH.SERVER_UNAVAILABLE] \| Payment:failed
2.2.4.14	Create — FAILURE [TECH.INVALID_RESPONSE] \| Payment:failed
2.2.4.15	Create — FAILURE [TECH.INVALID_REQUEST] \| Payment:failed
2.2.4.21	Create — FAILURE [AUTHZ.401_UNAUTHORIZED] \| Payment:failed
2.2.4.22	Create — FAILURE [AUTHZ.403_FORBIDDEN] \| Payment:failed
2.2.4.31	Create — FAILURE [BUSINESS.BALANCE] \| Payment:failed
2.2.4.32	Create — FAILURE [BUSINESS.LIMIT] \| Payment:failed
2.2.4.33	Create — FAILURE [BUSINESS.CURRENCY] \| Payment:failed

3) Payform / UI (A=3)

Code	Description
3.0.1.00	Present — INFO \| Payment:created
3.0.1.51	Present — INFO [USER.PAGE_VISIT] \| Payment:created
3.0.1.52	Present — INFO [USER.PAGE_LEAVE] \| Payment:created
3.0.1.53	Present — INFO [USER.ENTER_PERSONAL_DATA] \| Payment:created
3.0.4.54	Present — INFO [USER.CLICK_CANCEL] \| Payment:failed
3.1.1.55	Present — SUCCESS [USER.CLICK_SUBMIT] \| Payment:created
3.2.4.56	Confirm — FAILURE [USER.3DS_FAILED] \| Payment:failed
3.2.4.57	Confirm — FAILURE [USER.OTP_FAILED] \| Payment:failed
3.0.1.58	Confirm — INFO [USER.LEAVE_ON_CONFIRM] \| Payment:created

4) Check (polling the gateway) (A=4)

Code	Description
4.2.2.13	Check — FAILURE [TECH.SERVER_UNAVAILABLE] \| Payment:processing
4.2.2.15	Check — FAILURE [TECH.INVALID_REQUEST] \| Payment:processing
4.2.2.21	Check — FAILURE [AUTHZ.401_UNAUTHORIZED] \| Payment:processing
4.2.2.22	Check — FAILURE [AUTHZ.403_FORBIDDEN] \| Payment:processing
4.1.3.00	Check — SUCCESS \| Payment:success
4.1.4.00	Check — SUCCESS \| Payment:failed [UNSPECIFIED]
4.1.4.61	Check — SUCCESS \| Payment:failed [ISSUER.CARD_BLOCKED]
4.1.4.62	Check — SUCCESS \| Payment:failed [ISSUER.CARD_NOT_SUPPORTED]
4.1.4.63	Check — SUCCESS \| Payment:failed [ISSUER.INSUFFICIENT_FUNDS]
4.1.4.41	Check — SUCCESS \| Payment:failed [RISK.ANTIFRAUD_HARD]

5) Gateway Callback (A=5)

Code	Description
5.2.2.16	Callback — FAILURE [TECH.INVALID_SIGNATURE] \| Payment:processing
5.2.2.17	Callback — FAILURE [TECH.INVALID_PAYLOAD] \| Payment:processing
5.1.3.00	Callback — SUCCESS \| Payment:success
5.1.3.35	Callback — SUCCESS [BUSINESS.AMOUNT_UPDATED] \| Payment:success

6) Merchant Callback (A=6)

Code	Description
6.1.1.00	Confirm — SUCCESS \| Payment:created

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>).

Backward compatibility (legacy `X.Y.Z.W`)

If you still ingest the older format please follew next page: https://apidoc.paystar.uk/payment-history-backward-compatibility

FAQ

How do I know a payment is final?

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

# Payment history (v2 Action Codes)

Data model#

v2 action code format#

Reason dictionary (RR)#

Examples#

Success (Deposit)#

Failure (Issuer insufficient funds)#

Action codes reference (by Stage)#

1) PS internal (A=1)#

2) Gateway / Create (A=2)#

3) Payform / UI (A=3)#

4) Check (polling the gateway) (A=4)#

5) Gateway Callback (A=5)#

6) Merchant Callback (A=6)#

Completeness & reliability tips#

Backward compatibility (legacy X.Y.Z.W)#

FAQ#