PAYSTAR / DEVELOPER DOCUMENTATION

Status & balance

Look up orders using either identifier and read balances for the assigned profile.

[01]

Two IDs, one order

Download order statuses only · JSON ↓ · View order statuses in Downloads →

Identifier	Where it comes from	Use
`externalTransactionId`	Your original create request	Merchant-ID lookup; recovery after an uncertain create.
`externalId`	PayStar create response	PayStar-ID lookup for the accepted order.

Status values

Flow	In progress	Outcome / finality
Deposit	Init · Created · Processing	`Success` · `Failed` ⚠️ For P2P deposits, `Failed` may be changed following an appeal.
Payout	Created · Processing	`Success` · `Failed`

[02]

Deposit by merchant ID

GEThttps://secure.paystar.uk/api/v1/integration/deposit-order/{externalTransactionId}/status-by-external-transaction-id

Get the current deposit status using your original externalTransactionId from the create request. Put that merchant order ID in the URL path.

Request & example

Parameter	Presence	Meaning
`externalTransactionId`	Required · path	Merchant-generated external transaction identifier.

cURLSelect text to copy

curl --request GET \
  --url 'https://secure.paystar.uk/api/v1/integration/deposit-order/UNIQUE_MERCHANT_ID/status-by-external-transaction-id' \
  --header 'Authorization: Bearer <PAYSTAR_DEPOSIT_PROFILE_TOKEN>'

Successful response

Field	Presence	Type & meaning
`externalId`	Required	`string`
`orderStatus`	Required	`string · Init / Created / Processing / Success / Failed` Current deposit order state. P2P exception (P2P-STATE-001, owner-confirmed 2026-09-10): Failed is not unconditionally final; the same order with unchanged identifiers can be corrected to Success, usually after initiation by merchant support. The merchant must handle the corresponding callback update. A reverse Success-to-Failed business transition need not be implemented. This does not change other deposit flows, introduce new status values, define callback delivery guarantees or prescribe indefinite polling.
`amount`	Optional	`number` Amount in major currency units. JSON number is normative; quoted numeric strings remain backward-compatible. Normal requests and displayed examples use two decimal places. Flow-specific min/max are routing configuration. exclusiveMinimum: 0 Amount
`externalParams`	Optional	`object` Flow-dependent object; it may be absent or contain null fields. ExternalParams
`currency`	Optional	`string` Currency key of the deposit, for example ARS. The response field is confirmed by owner examples; universal presence is not separately established. No alpha-3-only restriction is imposed. CurrencyCode
`orderHistory`	Required	`array of object` Required non-empty payment history: at least one item in deposit status responses, by merchant ID or PayStar ID (owner-confirmed 2026-09-11). Use orderStatus for the current state. A non-empty history is not a guarantee of a complete trace. minItems: 1 Payment history reference →

Both lookups return the same deposit response structure. The examples below include currency and non-empty history. Times are UTC; the supplied wire values omit the timezone suffix. See timestamp format note.

Success deposit — response exampleOwner-provided · anonymized

JSONSelect text to copy

{
  "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "orderStatus": "Success",
  "externalParams": {
    "cardToken": null,
    "cardStorageToken": null,
    "cardHolder": null,
    "cardNumber": null
  },
  "amount": 10000.00,
  "currency": "ARS",
  "orderHistory": [
    {
      "time": "2026-09-11T10:52:47.141614",
      "action": "1.1.2.0",
      "newCode": "1.1.2.00"
    },
    {
      "time": "2026-09-11T10:52:49.157749",
      "action": "2.1.0.0",
      "newCode": "2.1.1.00"
    },
    {
      "time": "2026-09-11T10:55:05.563194",
      "action": "4.1.0.0",
      "newCode": "4.1.3.XX"
    }
  ]
}

Failed deposit — response exampleOwner-provided · anonymized

JSONSelect text to copy

{
  "externalId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "orderStatus": "Failed",
  "externalParams": {
    "cardToken": null,
    "cardStorageToken": null,
    "cardHolder": null,
    "cardNumber": null
  },
  "amount": 26250.00,
  "currency": "ARS",
  "orderHistory": [
    {
      "time": "2026-09-11T10:30:43.941409",
      "action": "1.2.1.1",
      "newCode": "1.1.4.32"
    }
  ]
}

HTTP outcomes

HTTP	Meaning
`200`	Current order state.
`401`	Missing or invalid Bearer token.
`403`	The key is valid but cannot access this resource.
`404`	Order not found. BusinessError & handling
`500`	Internal server error.

Technical details

Operation ID: getDepositStatusByMerchantId

This is the OpenAPI operation name used by development tools and code generators. It is not an order ID or a request parameter: do not send it in the URL, headers or request body.

[03]

Deposit by PayStar ID

GEThttps://secure.paystar.uk/api/v1/integration/deposit-order/{externalId}/status

Get the current deposit status using the PayStar externalId returned when the order was created. Put that PayStar order ID in the URL path.

Request & example

Parameter	Presence	Meaning
`externalId`	Required · path	PayStar order identifier returned by create.

cURLSelect text to copy

curl --request GET \
  --url 'https://secure.paystar.uk/api/v1/integration/deposit-order/PAYSTAR_ORDER_ID/status' \
  --header 'Authorization: Bearer <PAYSTAR_DEPOSIT_PROFILE_TOKEN>'

Successful response

Field	Presence	Type & meaning
`externalId`	Required	`string`
`orderStatus`	Required	`string · Init / Created / Processing / Success / Failed` Current deposit order state. P2P exception (P2P-STATE-001, owner-confirmed 2026-09-10): Failed is not unconditionally final; the same order with unchanged identifiers can be corrected to Success, usually after initiation by merchant support. The merchant must handle the corresponding callback update. A reverse Success-to-Failed business transition need not be implemented. This does not change other deposit flows, introduce new status values, define callback delivery guarantees or prescribe indefinite polling.
`amount`	Optional	`number` Amount in major currency units. JSON number is normative; quoted numeric strings remain backward-compatible. Normal requests and displayed examples use two decimal places. Flow-specific min/max are routing configuration. exclusiveMinimum: 0 Amount
`externalParams`	Optional	`object` Flow-dependent object; it may be absent or contain null fields. ExternalParams
`currency`	Optional	`string` Currency key of the deposit, for example ARS. The response field is confirmed by owner examples; universal presence is not separately established. No alpha-3-only restriction is imposed. CurrencyCode
`orderHistory`	Required	`array of object` Required non-empty payment history: at least one item in deposit status responses, by merchant ID or PayStar ID (owner-confirmed 2026-09-11). Use orderStatus for the current state. A non-empty history is not a guarantee of a complete trace. minItems: 1 Payment history reference →

Success deposit — response exampleOwner-provided · anonymized

JSONSelect text to copy

{
  "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "orderStatus": "Success",
  "externalParams": {
    "cardToken": null,
    "cardStorageToken": null,
    "cardHolder": null,
    "cardNumber": null
  },
  "amount": 10000.00,
  "currency": "ARS",
  "orderHistory": [
    {
      "time": "2026-09-11T10:52:47.141614",
      "action": "1.1.2.0",
      "newCode": "1.1.2.00"
    },
    {
      "time": "2026-09-11T10:52:49.157749",
      "action": "2.1.0.0",
      "newCode": "2.1.1.00"
    },
    {
      "time": "2026-09-11T10:55:05.563194",
      "action": "4.1.0.0",
      "newCode": "4.1.3.XX"
    }
  ]
}

Failed deposit — response exampleOwner-provided · anonymized

JSONSelect text to copy

{
  "externalId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "orderStatus": "Failed",
  "externalParams": {
    "cardToken": null,
    "cardStorageToken": null,
    "cardHolder": null,
    "cardNumber": null
  },
  "amount": 26250.00,
  "currency": "ARS",
  "orderHistory": [
    {
      "time": "2026-09-11T10:30:43.941409",
      "action": "1.2.1.1",
      "newCode": "1.1.4.32"
    }
  ]
}

HTTP outcomes

HTTP	Meaning
`200`	Current order state.
`401`	Missing or invalid Bearer token.
`403`	The key is valid but cannot access this resource.
`404`	Order not found. BusinessError & handling
`500`	Internal server error.

Technical details

Operation ID: getDepositStatusByPayStarId

This is the OpenAPI operation name used by development tools and code generators. It is not an order ID or a request parameter: do not send it in the URL, headers or request body.

[04]

Payout by merchant ID

GEThttps://secure.paystar.uk/api/v1/integration/withdrawal-order/{externalTransactionId}/status-by-external-transaction-id

Get the current payout status using your original externalTransactionId from the create request. Put that merchant order ID in the URL path.

Request & example

Parameter	Presence	Meaning
`externalTransactionId`	Required · path	Merchant-generated external transaction identifier.

cURLSelect text to copy

curl --request GET \
  --url 'https://secure.paystar.uk/api/v1/integration/withdrawal-order/UNIQUE_MERCHANT_ID/status-by-external-transaction-id' \
  --header 'Authorization: Bearer <PAYSTAR_PAYOUT_TOKEN>'

Successful response

Field	Presence	Type & meaning
`externalId`	Required	`string`
`orderStatus`	Required	`string · Created / Processing / Success / Failed`
`amount`	Optional	`number` Amount in major currency units. JSON number is normative; quoted numeric strings remain backward-compatible. Normal requests and displayed examples use two decimal places. Flow-specific min/max are routing configuration. exclusiveMinimum: 0 Amount
`externalParams`	Optional	`object` Flow-dependent object; it may be absent or contain null fields. ExternalParams
`orderHistory`	Optional	`array of object` Not guaranteed to be populated and may be delayed.

JSONSelect text to copy

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Success",
  "amount": 100,
  "orderHistory": []
}

For orderHistory fields and history codes, see Payment history reference →.

HTTP outcomes

HTTP	Meaning
`200`	Current order state.
`401`	Missing or invalid Bearer token.
`403`	The key is valid but cannot access this resource.
`404`	Order not found. BusinessError & handling
`500`	Internal server error.

Technical details

Operation ID: getPayoutStatusByMerchantId

This is the OpenAPI operation name used by development tools and code generators. It is not an order ID or a request parameter: do not send it in the URL, headers or request body.

[05]

Payout by PayStar ID

GEThttps://secure.paystar.uk/api/v1/integration/withdrawal-order/{externalId}/status

Get the current payout status using the PayStar externalId returned when the order was created. Put that PayStar order ID in the URL path.

Request & example

Parameter	Presence	Meaning
`externalId`	Required · path	PayStar order identifier returned by create.

cURLSelect text to copy

curl --request GET \
  --url 'https://secure.paystar.uk/api/v1/integration/withdrawal-order/PAYSTAR_ORDER_ID/status' \
  --header 'Authorization: Bearer <PAYSTAR_PAYOUT_TOKEN>'

Successful response

Field	Presence	Type & meaning
`externalId`	Required	`string`
`orderStatus`	Required	`string · Created / Processing / Success / Failed`
`amount`	Optional	`number` Amount in major currency units. JSON number is normative; quoted numeric strings remain backward-compatible. Normal requests and displayed examples use two decimal places. Flow-specific min/max are routing configuration. exclusiveMinimum: 0 Amount
`externalParams`	Optional	`object` Flow-dependent object; it may be absent or contain null fields. ExternalParams
`orderHistory`	Optional	`array of object` Not guaranteed to be populated and may be delayed.

JSONSelect text to copy

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Success",
  "amount": 100,
  "orderHistory": []
}

For orderHistory fields and history codes, see Payment history reference →.

HTTP outcomes

HTTP	Meaning
`200`	Current order state.
`401`	Missing or invalid Bearer token.
`403`	The key is valid but cannot access this resource.
`404`	Order not found. BusinessError & handling
`500`	Internal server error.

Technical details

Operation ID: getPayoutStatusByPayStarId

This is the OpenAPI operation name used by development tools and code generators. It is not an order ID or a request parameter: do not send it in the URL, headers or request body.

[06]

Merchant & pipeline balance

GEThttps://secure.paystar.uk/api/v1/balance/merchant?currency={currency}

currency is a required string query parameter, without an alpha-3 length or pattern restriction. Balance is a read-only lookup, not payment routing. Use the canonical secure.paystar.uk host and a profile with balance access.

Request & example

cURLSelect text to copy

curl --request GET \
  --url 'https://secure.paystar.uk/api/v1/balance/merchant?currency=RUB' \
  --header 'Authorization: Bearer <PAYSTAR_PROFILE_TOKEN>'

Response fields

Field	Presence	Type & meaning
`currency`	Required	`string`
`merchantBalance`	Required	`number`
`merchantOverdraft`	Required	`number`
`pipelineBalance`	Required	`number`
`pipelineAvailableBalance`	Required	`number`
`pipelineProcessingOrdersDeposit`	Required	`number`
`pipelineProcessingOrdersWithdrawals`	Required	`number`

HTTP outcomes

HTTP	Meaning
`200`	Balance data.
`400`	Missing or malformed currency. BusinessError & handling
`401`	Missing or invalid Bearer token.
`403`	The key is valid but cannot access balance.

[07]

Read history without guessing

History items may include time, action and newCode. Preserve unknown codes; do not infer their meaning from neighboring values.

Order history timestamps are in UTC. In deposit and payout status responses, interpret orderHistory[].time as UTC even when the value has no Z or numeric offset. Do not interpret it as your local timezone.

History item schema

Field	Presence	Type & meaning
`time`	Optional	`string · date-time` History record time in UTC for deposit and payout status responses. If returned without Z or an offset, interpret this field as UTC, not local time (owner-confirmed 2026-09-08). The missing suffix remains a date-time wire-format discrepancy; this clarification does not relax the schema.
`action`	Optional	`string \| null` Payment History action code.
`newCode`	Optional	`string \| null` Additional Payment History code returned by the current API.

Sensitive externalParams

Field	Presence	Type & meaning
`cardToken`	Optional	`string \| null` Sensitive; access and logging must be restricted.
`cardStorageToken`	Optional	`string \| null` Sensitive; access and logging must be restricted.
`cardHolder`	Optional	`string \| null`
`cardNumber`	Optional	`string \| null` Must be masked when returned.

Payment history reference → Polling & recovery →

Need the required fields, currencies or limits for your pipeline?

Confirm your profile with Yegor ↗