PAYSTAR / DEVELOPER DOCUMENTATION

Quick start & access

Prepare the correct credentials, send a safe first request and resolve an uncertain outcome.

[01]

Confirm the integration profile

Select the exact flow: P2P, ECOM H2H, hosted H2C, tokenized deposit or payout.
Confirm test mode, allowed hosts, server IP, enabled currencies and limits.
Obtain the required additionalFields for that pipeline, plus approved test fixtures.
Confirm callback and customer redirect configuration before sending a create.

[02]

Authentication

Send the assigned Bearer key on every protected request. Each pipeline uses a separate key: two deposit pipelines have different keys, and deposit and payout never share a pipeline key.

HTTP headerSelect text to copy

Authorization: Bearer <PIPELINE_SPECIFIC_KEY>

Obtaining and replacing credentials

Request credentials for the assigned pipeline and environment from PayStar. Keep keys server-side, outside URLs, repositories, browser code and logs. Ask for replacement immediately if exposure is suspected.

The legacy guide supports a ready-made Bearer token or an approved public/private key pair. Confirm the supported issuance and revocation process for your account.

JWT generation — legacy onboarding guideAdvanced

Legacy guide · confirm issuance

The legacy mechanism uses JWT with HS256, with publicKey in the payload and the private key used only for signing. Do not include the private key in the payload.

JWT payload shapeSelect text to copy

{
  "publicKey": "<PUBLIC_KEY>"
}

Token lifetime and additional claims are not established by the verified material. Obtain a validated signing example from PayStar for your onboarding arrangement.

[03]

Create, keep IDs, then check

01
Create the order
Use a JSON number in major currency units and a unique externalTransactionId. Follow the selected flow schema.
02
Store both identifiers
Keep your original merchant ID and the returned PayStar externalId.
03
Read the current state
Use orderStatus. Deposit status includes non-empty history; payout history may be empty or delayed.

Open deposit request templates → Open payout guide →

Amounts, currency and backward compatibility

Use a number, for example 100.00, in major units. Numeric strings remain backward-compatible only.
Owner-approved P2P half-up rounding: 100.124 → 100.12, 100.125 → 100.13, 100.126 → 100.13. Do not extrapolate to an unverified flow.
Currency is a string key without lexical length or pattern validation. For payment creation, internal currency dictionary lookup precedes pipeline route lookup. See currency keys and crypto examples.
New examples use lowerCamelCase additional-field keys. Legacy PascalCase is accepted for compatibility.
Required additional fields and min/max amounts are profile-specific.

[04]

Resolve uncertainty before retrying

After a create timeout, broken connection, missing response or HTTP 5xx, query status using the same original merchant ID before retrying or cascading to another create.

Status lookup by merchant ID →

Polling and final statesPolicy confirmation required

For P2P deposits, Failed is a failure outcome that can later be corrected to Success on the same order, usually after initiation by merchant support. Keep the existing IDs and handle the authenticated correction callback. A reverse Success → Failed business transition need not be implemented. This does not change the other flow classifications or require indefinite polling. The polling interval, stop conditions, backoff and escalation must be agreed with PayStar.

The legacy pages disagree between two and five minutes; this preview does not silently choose one. Callback receipt does not replace recovery for an uncertain create. See P2P correction callbacks.

[05]

Sandbox outcomes

Use only capabilities explicitly assigned to the test profile. Track every accepted create, including negative tests that unexpectedly succeed.

Success and failure controls from the legacy guide

Legacy-documented · not live-verified

The legacy guide describes the additional-field key ExpectedResult with these values:

Value	Intended simulated outcome
`status=success`	Successful payment
`status=failed`	Failed payment

The old text also uses expectedResult. Confirm canonical casing, accepted aliases and applicability to your profile before use.

What a successful sandbox status does not prove

A sandbox Success does not by itself prove customer completion of 3DS, real callback delivery, correct browser redirects or identical validation in production. Ask for dedicated fixtures for these checks.

See the dated coverage matrix →

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

Confirm your profile with Yegor ↗