PAYSTAR / DEVELOPER DOCUMENTATION
Callbacks & events
Payment updates and operational alerts are separate interfaces with different signing inputs.
[01]
Payment callbacks
Receive configured order events on your server. The legacy interface describes an HTTP POST to the configured URL with a Signature header.
P2P correction: Failed → SuccessOwner-confirmed · P2P only
Owner-confirmed on 10 September 2026. The same P2P order can be corrected from Failed to Success, usually after initiation by merchant support. Keep its existing PayStar externalId and merchant externalTransactionId; this is not a new order.
| Stored P2P outcome | Incoming update | Merchant business handling |
|---|---|---|
| Failed | Success | After validating the callback using the agreed profile contract, update the existing order to Success. Do not reject it just because Failed was recorded earlier. |
| Success | Repeated Success | Process idempotently; do not apply the same business effect twice. The reliable delivery/deduplication key still requires agreement. |
| Success | Failed | No reverse business transition needs to be implemented; do not downgrade the stored Success. This does not waive validation or the agreed acknowledgement/handling of unexpected messages. |
Do not deduplicate all callbacks solely by order ID: a changed status for an existing order is not automatically a duplicate. Callback payload, signing, ACK and retry details remain subject to the dedicated notification contract; no new JSON format, HTTP acknowledgement or delivery deadline is defined here.
The owner confirmed the lifecycle and required merchant handling, not a completed live delivery test. Failure reasons eligible for correction and its time window remain unconfirmed. This is not an instruction to poll every Failed order indefinitely.
Configuration & payload fields
Legacy documentation describes both a static callback URL configured with PayStar and a per-order callbackUrl. Confirm precedence and event selection for your profile.
| Field | Legacy meaning |
|---|---|
| externalId | PayStar order ID. |
| status | Order state in this notification. |
| amount / currency | Order amount and currency; signed amount representation requires confirmation. |
| orderType | Deposit or Withdrawal. |
| externalParams / orderHistory | Flow-dependent fields; sensitive data must be restricted and masked. |
This is a guide, not a complete approved payload schema. The old swapped card fields and inconsistent history casing are not reproduced.
Signature verification — legacy algorithm
The described signature concatenates the following values with semicolons, applies SHA-256, then uses hexadecimal encoding:
externalId;status;amount;orderType;privateKeyConfirm the exact value representation and assigned secret against a verified fixture. Preserve signed values; do not substitute another algorithm or assume a numeric serialization.
Acknowledgement, retries & duplicates
The legacy source conflicts between HTTP 200 and any 2xx acknowledgement. Retry timing and a reliable deduplication key still require agreement and a delivery test.
Confirm payload, canonicalization, URL priority, ACK, retry policy and duplicate handling before production use. This documentation does not turn the old retry table into an SLA.
Use the Status API to resolve uncertain creates and verify the order when needed. Open status methods →
[02]
Operational events
Operational alerts report account and platform activity, such as routing changes or stuck orders. They are separate from payment callbacks and use a separate endpoint secret.
Subscription & payload
The legacy guide configures a custom notification endpoint in the account’s notification settings. Confirm current availability, subscription flags and secret rotation with PayStar.
| Field | Meaning |
|---|---|
| id | Alert type ID; not a unique delivery ID. |
| createdAt | Exact timestamp string of the alert. |
| message | Message text, potentially containing HTML and line breaks. |
| fields | Name/Content metadata pairs. |
Render message content safely; do not treat arbitrary notification text as trusted executable markup.
Signature and the integrity boundary
createdAt;message;endpointPrivateKeyThe legacy algorithm uses SHA-256 over UTF-8 followed by hexadecimal encoding. Preserve exact timestamp text, whitespace and line breaks.
In that description, id and fields are not signed. Treat them as advisory metadata, not independently authenticated data. Do not reuse the payment callback signing input.
A current subscription and a verified signature fixture are still required. No fixed replay window is invented here.
Legacy event categories
Payment status changes and stuck orders; limits; merchant and pipeline updates; routing and channels; commission settings; team changes; settlements and issues.
The exact current IDs and subscription availability require confirmation. A category list is not a closed supported-event enum.
[03]
Before enabling notifications
- Confirm the interface and use its own secret and signing inputs.
- Verify a known-good and a tampered fixture.
- Agree duplicate handling, acknowledgement and retry behavior.
- Test a real delivery with the approved non-production setup.
Need the required fields, currencies or limits for your pipeline?
Confirm your profile with Yegor ↗