Ask whether the account owner has approved a frozen operation yet

A state and a clock, for the app that is waiting.

GET /connect/approvals/{ref}

Ask whether the account owner has approved a frozen operation yet

cURL

curl --request GET \
  --url https://api.paygent.payman.ai/connect/approvals/{ref} \
  --header 'x-paygent-connect-app-key: <api-key>' \
  --header 'x-paygent-connect-grant: <api-key>'

200

{
  "ref": "pgtk_9Qv2mB7fJ0xkLpR4sTuVwXyZa1b2c3d4e5f6g7h8i9j",
  "state": "pending",
  "expiresAt": "<string>",
  "approvalUrl": "<string>",
  "executable": true,
  "executionStatus": "succeeded",
  "providerTransactionId": "<string>",
  "executedAt": "<string>"
}

Authorizations

x-paygent-connect-app-key · string · header · required

A Connect app key (pgc_app_…), identifying the registered third-party app. Always presented together with connectGrant — the pair is one credential, and either half alone is refused. Accepted on the /connect/* surface only.

x-paygent-connect-grant · string · header · required

A Connect grant token (pgc_grant_…): one user's consent for the presenting app to reach one deployment. Every failure mode — missing, malformed, revoked, expired, or paired with the wrong app key — answers the same 401 invalid_connect_credentials.

Path Parameters

ref · string · required

The frozen operation's handle, as the runtime minted it. An approval ticket's public handle: pgtk_ and 43 characters of unpadded base64url — 32 bytes of CSPRNG, minted by the runtime and by nothing else.

Required string length: 48

Pattern: ^pgtk_[A-Za-z0-9_-]{43}$

Example:

"pgtk_9Qv2mB7fJ0xkLpR4sTuVwXyZa1b2c3d4e5f6g7h8i9j"

Response

200

application/json

The ticket's state

The app-facing view of a ticket: a state and a clock. Deliberately carries no operation detail at all — see getConnectApproval.

ref · string · required

An approval ticket's public handle: pgtk_ and 43 characters of unpadded base64url — 32 bytes of CSPRNG, minted by the runtime and by nothing else.

Required string length: 48

Pattern: ^pgtk_[A-Za-z0-9_-]{43}$

Example:

"pgtk_9Qv2mB7fJ0xkLpR4sTuVwXyZa1b2c3d4e5f6g7h8i9j"

state · enum<string> · required

What an app may learn about a ticket. Five values, and nothing else.

Available options: pending, approved, declined, expired, consumed

expiresAt · string | null · required

When the ticket lapses. ISO-8601 UTC, Z-suffixed.

approvalUrl · string

Payman's approval page for this ticket, on the console origin. Present only while state is pending — a link to a page that can only say "this is over" is worse than no link — and absent on a deployment with no CONSUMER_CONSOLE_URL, which degrades to an approval with no button rather than to a failed request.

executable · boolean

Whether approval executes the payment server-side, fixed when the ticket was frozen. false means executionStatus will never appear on this ticket — completion arrives through the resumed conversation (or your replay), so stop polling for a receipt and say the agent behind the connection is completing it.

executionStatus · enum<string>

The receipt, once the bank has answered. Absent while the submission is in flight — and forever, when executable is false.

Available options: succeeded, failed, unknown

providerTransactionId · string

The provider's opaque reference. Only beside an outcome.

executedAt · string

When the bank answered. ISO-8601 UTC.