Contact
API DOCUMENTATION

Confirm your assigned profile. Draft sections and verification limits are marked.

View open points →

PAYSTAR / DEVELOPER DOCUMENTATION

Verification & open points

Dated test observations, coverage boundaries and the decisions needed before production release.

[01]

Coverage is not universal

Documentation was updated on 10 September 2026. The owner confirmed P2P merchant-side H2H/H2C and a non-null payment-form URL from the same request; customer/browser completion was not tested. The owner also supplied IBAN, account-number and QR response examples. Their exact paths are documented; PhoneNumber mapping, alternative-field nullability and QR encoding details remain pending. No new live verification is claimed for these examples. The scoped currency clarification uses the owner decision and saved 8 September H2H evidence; Balance was retested read-only on 9 September. Other dated observations retain their original coverage limits. This page build did not run new payment tests.

Flow / operationLast supported evidence
P2P H2H/H2CRecorded API create → Success and both status lookups; merchant UI choice confirmed 10 Sep. Hosted-form completion not tested.
ECOM H2HAccepted sandbox request and final status; full request contract and 3DS/customer action not verified.
Hosted H2CValidation and unknown-currency evidence only; happy path incomplete.
PayoutOlder happy-path evidence; later access blocked.
Tokenized / callback / browser redirectDedicated end-to-end fixtures not complete.
Balance9 Sep canonical secure-host retest: missing/empty/RU 400, RUB 200, auth 401; rub/ZZZ policy pending.

[02]

Open review points

Error catalog structureConfirmation / retest required

Evidence: Manager review 15 Sep 2026

Reference lists each scenario once. errors.json and the combined dictionary use businessErrors formatVersion 2 with one items list and ID-only groups. Known wire variants and HTTP scope are retained.

Next step

Update parsers of the previous nested error dictionary. No new API error behavior or payment test is claimed.

Deposit status history and currencyConfirmation / retest required

Evidence: Owner-confirmed 11 Sep 2026

Both deposit lookups require non-empty orderHistory. Success/Failed wire examples include currency; exact history codes and offset-less UTC times are preserved. Earlier empty H2C history observations are historical, not the approved rule.

Next step

Retest the deposit status contract with assigned keys separately; confirm universal currency presence before making that field required. Payout and callback rules are unchanged.

Common unsuccessful-create payloadsConfirmation / retest required

Evidence: Owner examples · 10 Sep; scope and HTTP confirmed 15 Sep 2026

Five common response-body examples are available beside every deposit flow. Payout has those five plus Insufficient balance, which applies only to payouts. Reference and Downloads use the same scope. This is not an exhaustive error catalog. Empty-body authentication responses remain in the HTTP guidance.

Next step

HTTP is shown beside each payload: created Failed 200, routing 423, payout-only insufficient balance 422, limit/duplicate/required-field errors 400. CreatedFailedResponse is a separate HTTP200 schema branch; existing successful-response requirements are preserved. HTTP200 is not payment success. These are owner-confirmed mappings, not new live tests.

P2P correction after FailedConfirmation / retest required

Evidence: Owner-confirmed · 10 Sep 2026

The same P2P order can change Failed 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.

Next step

Do not discard a changed status solely because its order ID was seen. Apply updates idempotently. No live correction/callback delivery was tested; correction deadline, eligible reasons and transport/polling details remain to be agreed.

P2P alternative payment-detail mappingConfirmation / retest required

Evidence: Owner-provided examples · 10 Sep 2026

Recipient phone maps to paymentDetails.number; IBAN maps to paymentDetails.iban; account number maps to paymentDetails.accountNumber. QR content is in paymentDetails.qrUrl and can coexist with accountNumber. method ArsCbu is an example, not a discriminator. No new live test was run.

Next step

Recipient phone maps to paymentDetails.number (owner-confirmed). Alternative-field nullability/absence rules, method catalog and exact QR encoding remain pending. See Deposits → Payment details fields; new OpenAPI properties are annotations without new value constraints.

ECOM H2H contract and sandbox validationConfirmation / retest required

Evidence: 7 Sep 2026

Owner-provided ECOM H2H/H2C request/response examples are now published. H2H uses paymentDetails.formUrl plus flowData; H2C uses root formUrl. The older saved order reached Success, but full schemas, redirect precedence and validation parity remain unconfirmed.

Next step

Confirm the profile-specific contract and use a valid test fixture; a successful sandbox status does not establish customer completion of 3DS.

H2C happy path and hostsConfirmation / retest required

Evidence: 7 Sep 2026

The owner supplied an ECOM H2C example with AZN, PayeerIdentifier and an Init/root-formUrl response. Earlier supplied H2C labels returned missing-FirstName 400. These profile-specific examples do not establish universal required fields or complete live onboarding.

Next step

Confirm required fields and routing markers per profile; verify create, form handoff and both status lookups. Do not make firstName universal.

Payout access and 422 mappingConfirmation / retest required

Evidence: 7 Sep / 24 Aug evidence; scope confirmed 15 Sep 2026

The latest payout status access check returned an empty 403; the cause is unresolved. An older payout test returned 422 with 1-4010 / 1.1.4.3, identified by the owner as insufficient balance. This error applies only to payouts.

Next step

Confirm test-mode payout access before further probes; the body examples do not establish complete live coverage.

Callbacks and operational EventsConfirmation / retest required

Evidence: No complete live delivery fixture

Legacy guidance contains conflicting callback ACK descriptions; signature, retry behavior and current alert support lack dedicated verified fixtures.

Next step

Confirm the contract, signed values, secrets, ACK and retries; test delivery and duplicates before production.

History timestamp serializationConfirmation / retest required

Evidence: UTC confirmed 8 Sep 2026; offset-less status wire observed 8 Sep 2026

The owner confirmed that orderHistory[].time in deposit and payout status responses is UTC. Interpret an offset-less value as UTC, not local time. The schema still declares date-time, and the missing suffix remains a serialization discrepancy.

Next step

Retain UTC semantics and agree a compatible explicit timezone suffix in the API response. Do not relax the schema or apply this rule to callbacks or Events createdAt.

Status authentication responsesConfirmation / retest required

Evidence: 25 Aug 2026

Twelve missing/invalid/Bearer-scheme cases across four status operations returned empty 500 responses rather than the expected 401.

Next step

Retest and fix auth handling before order lookup; a valid wrong-capability key needs a separate approved control.

Deposit unknown currency versus routingConfirmation / retest required

Evidence: Owner decision 9 Sep 2026; H2H routing evidence 8 Sep 2026

CUR-002 confirms 423 for the discussed unrecognized RU and ZZZ values in Deposit H2H/H2C, with statusDescrption 2-00100-2 and code 1.2.4.9. The approved message template is Currency value "{currencyKey}" is unknown; that refined message is not yet live-verified. A separate H2H EUR case returned 423 / 0000-2 / 1.2.4.3.

Next step

CUR-CRYPTO-001 (10 Sep 2026) removes the inferred alpha-3 format check: currency is a string key. Payment creation first looks up the currency in the internal dictionary, then finds a route by pipeline conditions. USDT_TRC20 is an illustrative input, not a guarantee of enabled support. RU and ZZZ are unknown-currency evidence, not independent routing coverage. CREATE-HTTP-001 confirms HTTP423 for the common no-matching-route response (15 Sep 2026). Profile support and live coverage remain separate open points.

Additional-field and URL validationConfirmation / retest required

Evidence: 23–24 Aug 2026

Malformed additionalFields produced 500 in historical tests; a missing value and malformed URLs were accepted in some cases.

Next step

Confirm URL policy and retest field validation. Accepted negative cases must be journaled and followed by status.

Balance validation fixed; lowercase and no-balance policy pendingConfirmation / retest required

Evidence: 9 Sep 2026 · secure.paystar.uk

A read-only retest with one confirmed test profile returned 400 BusinessError for missing, empty and RU currency, 200 Balance for both RUB controls, and 401 for missing/invalid authorization. Seven HTTP expectations and seven JSON schemas matched. rub and ZZZ changed from 204 to 400 and remain separate configuration observations.

Next step

Treat missing/empty/RU as fixed for this tested profile and host. Confirm lowercase and no-balance policy before changing the Balance contract. Deposit 423 handling does not apply here.

Tokenized flow and sensitive response fieldsConfirmation / retest required

Evidence: Dedicated onboarding pending

No dedicated tokenized happy path or current callback fixture is available. cardMask semantics/nullability remain unconfirmed.

Next step

Confirm token issuance, reuse and customer steps; agree response fields without inferring a closed schema from one sample.

[03]

Rules already agreed

Do not reopen these as defects merely because old examples differ:

  • JSON-number amounts in major units; numeric strings remain compatible.
  • P2P half-up rounding and three required redirects; payout has no deposit redirects.
  • P2P with an H2H gateway integration returns payment instructions and a non-null PayStar form URL in one response. The merchant chooses H2H or H2C presentation using the same request/order (confirmed 10 September 2026).
  • LowerCamelCase documentation with PascalCase compatibility.
  • Required additional fields are profile-specific.
  • Deposit status by either ID includes a required, non-empty orderHistory and the currency response field (owner-confirmed 11 September 2026); currency requiredness is not separately established. Payout history rules are unchanged. Use orderStatus for current state; non-empty history does not guarantee an exhaustive trace.
  • For P2P only, the same order can be corrected from Failed to Success, usually after initiation by merchant support. Handle the correction callback; no reverse Success-to-Failed business transition is required. This does not establish a callback delivery SLA or indefinite polling (confirmed 10 September 2026).
  • Order history time in deposit and payout status responses is UTC, including current offset-less values (confirmed 8 September 2026). The missing suffix remains a separate serialization issue.
  • For Deposit H2H/H2C, discussed unrecognized RU/ZZZ return 423 with statusDescrption 2-00100-2 and code 1.2.4.9. The approved message is Currency value "{currencyKey}" is unknown. The routing body 0000-2 / 1.2.4.3 is owner-confirmed as a common create error; HTTP423 for this common routing response was subsequently confirmed under CREATE-HTTP-001 on 15 September 2026. The same decision confirms HTTP200 for an order created with orderStatus Failed, 422 for payout-only insufficient balance, and 400 for configured limit, duplicate merchant ID and missing required-field examples. HTTP200 does not mean payment success.
  • Keep the compatible wire spelling statusDescrption.

Changed requiredness, types, security behavior, status mappings, callback rules and retry policy still require explicit approval before a production contract update.

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

Confirm your profile with Yegor ↗