{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "PayStar Merchant API", "version": "2026-08-25.9-dev.20260915.5", "description": "Public integration baseline for PayStar merchant balances, deposits, payouts, and status operations. Available capabilities, credentials, limits, currencies, and routes are confirmed during merchant onboarding. Documentation artifact with explicitly marked verification limits. Owner-approved P2P response constraints (P2P-FORM-001) and removal of inferred currency lexical restrictions (CUR-CRYPTO-001) update the earlier baseline; alternative payment-detail paths/examples are owner-provided annotations without new value constraints (P2P-DETAILS-001); P2P Failed-to-Success correction and callback handling are owner-confirmed lifecycle semantics without new enum values (P2P-STATE-001); common unsuccessful-create examples have owner-approved HTTP mappings, including a distinct CreatedFailedResponse HTTP200 branch without relaxing successful-response schemas (CREATE-ERRORS-001, CREATE-HTTP-001); owner-provided ECOM H2H/H2C samples are examples without new normative schema constraints (ECOM-EXAMPLES-001); deposit status requires non-empty history and documents currency (DEP-STATUS-001); its owner wire examples preserve the known offset-less timestamp discrepancy; draft ECOM and notification sections are not approved schemas. See the verification notes before production use.", "contact": { "name": "PayStar integration manager" } }, "servers": [ { "url": "https://secure.paystar.uk", "description": "Core API host for deposits, balances, payouts, and status operations" } ], "tags": [ { "name": "Balance", "description": "Merchant and pipeline balance." }, { "name": "Deposits", "description": "H2H P2P, H2C, and tokenized deposit creation." }, { "name": "Deposit status", "description": "Deposit lookup by PayStar or merchant identifier." }, { "name": "Payouts", "description": "H2H payout creation." }, { "name": "Payout status", "description": "Payout lookup by PayStar or merchant identifier." } ], "paths": { "/api/v1/balance/merchant": { "get": { "operationId": "getMerchantBalance", "summary": "Get merchant and pipeline balance", "tags": [ "Balance" ], "servers": [ { "url": "https://secure.paystar.uk" } ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "currency", "in": "query", "required": true, "description": "Required currency key as a string; no alpha-3 length or pattern restriction. Balance is a read-only lookup, not a payment-routing operation. A submitted key is not a guarantee of an available balance. Dictionary casing/alias and no-balance policy remain separate open points.", "schema": { "$ref": "#/components/schemas/CurrencyCode" }, "example": "RUB" } ], "responses": { "200": { "description": "Balance data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Missing or malformed currency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" } } } }, "401": { "description": "Missing or invalid Bearer token." }, "403": { "description": "The key is valid but cannot access balance." } } } }, "/api/v1/integration/deposit-order/": { "post": { "operationId": "createDeposit", "summary": "Create a deposit", "description": "Select the assigned integration profile as well as its host. This baseline models P2P merchant-side H2H/H2C from the same request, plus separate hosted-card H2C and tokenized profiles. Direct ECOM H2H can share the secure host but its dedicated request/response contract is still under review; do not substitute the P2P schema.", "tags": [ "Deposits" ], "servers": [ { "url": "https://secure.paystar.uk", "description": "Core API host; this operation creates a direct H2H deposit, including the P2P flow" }, { "url": "https://init.paystar.uk", "description": "Hosted card collection that keeps card entry outside the merchant page and can reduce PCI DSS scope" }, { "url": "https://token.paystar.uk", "description": "Deposit using a token assigned to an approved merchant tokenized flow" } ], "security": [ { "bearerAuth": [] } ], "x-paystar-flow-variants": [ { "id": "deposit-p2p-h2h", "server": "https://secure.paystar.uk", "requestSchema": "#/components/schemas/P2PDepositRequest" }, { "id": "deposit-h2c", "server": "https://init.paystar.uk", "requestSchema": "#/components/schemas/H2CDepositRequest", "description": "Hosted card collection that keeps card entry outside the merchant page and can reduce PCI DSS scope." }, { "id": "deposit-tokenized-h2h", "server": "https://token.paystar.uk", "requestSchema": "#/components/schemas/TokenDepositRequest" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/P2PDepositRequest" }, { "$ref": "#/components/schemas/H2CDepositRequest" }, { "$ref": "#/components/schemas/TokenDepositRequest" } ] }, "examples": { "p2p": { "$ref": "#/components/examples/P2PDepositRequest" }, "h2c": { "$ref": "#/components/examples/H2CDepositRequest" }, "tokenized": { "$ref": "#/components/examples/TokenDepositRequest" } } } } }, "responses": { "200": { "description": "Deposit order created. Inspect orderStatus: HTTP 200 can include a Failed processing outcome and does not mean payment success.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/P2PDepositCreateResponse" }, { "$ref": "#/components/schemas/H2CDepositCreateResponse" }, { "$ref": "#/components/schemas/TokenDepositCreateResponse" }, { "$ref": "#/components/schemas/CreatedFailedResponse" } ] }, "examples": { "created_failed": { "summary": "HTTP 200 · Order created, processing failed", "value": { "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "orderStatus": "Failed" } } } } } }, "400": { "description": "Request validation failed, a configured limit was reached, or the merchant order ID already exists. These common examples use owner-confirmed HTTP 400. Deposit H2H/H2C unknown currency remains the separate HTTP 423 response under CUR-002.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "limit_reached": { "summary": "HTTP 400 · Configured limit reached", "value": { "label": "LIMITS_ERROR", "message": "Limit id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa was reached", "statusDescrption": "0001-0", "externalTransactionId": null } }, "duplicate_merchant_id": { "summary": "HTTP 400 · Duplicate merchant order ID", "value": { "label": "VALIDATION_ERROR", "message": "Order with this external_transaction_id already exist", "statusDescrption": "1-4007", "externalTransactionId": null, "code": "1.1.5.1" } }, "required_field_missing": { "summary": "HTTP 400 · Required parameter missing", "value": { "label": "VALIDATION_ERROR", "message": "additionalField BankAccount not found in request data. Description: Beneficiary’s bank account number, e.g. 1234567890", "statusDescrption": "0000-0", "externalTransactionId": null, "code": "1.2.4.8" } } } } } }, "401": { "description": "Missing or invalid deposit Bearer token." }, "403": { "description": "The key is valid but cannot use this deposit capability." }, "415": { "description": "Unsupported media type. Framework-level error raised before PayStar business processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails415" } } } }, "423": { "description": "Business error: Deposit H2H/H2C unknown currency retains statusDescrption 2-00100-2, code 1.2.4.9 and the owner-approved message Currency value \"{currencyKey}\" is unknown. The distinct common routing error uses HTTP 423, statusDescrption 0000-2 and code 1.2.4.3, confirmed in CREATE-HTTP-001. See x-paystar-create-payload-examples and x-paystar-deposit-currency-errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "unknownCurrency": { "summary": "Owner-confirmed unknown currency: RU (refined message not yet live-verified)", "value": { "label": "TEMPORARY_ERROR", "message": "Currency value \"RU\" is unknown", "statusDescrption": "2-00100-2", "externalTransactionId": null, "code": "1.2.4.9" } }, "observedH2hRouting": { "summary": "Historical H2H EUR routing response, 8 Sep 2026; HTTP 423 subsequently owner-confirmed for the common routing error", "value": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "0000-2", "externalTransactionId": null, "code": "1.2.4.3" } }, "channel_not_found": { "summary": "HTTP 423 · No matching channel or route", "value": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "0000-2", "externalTransactionId": null, "code": "1.2.4.3" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" } } } } }, "x-paystar-retry-rule": "After timeout, broken connection, missing response, or HTTP 5xx, query status using the same externalTransactionId before any retry or cascade.", "x-paystar-deposit-currency-errors": { "decision": "CUR-002", "approvedAt": "2026-09-09", "scope": [ "Deposit H2H", "Deposit H2C" ], "unknownCurrency": { "status": "owner-confirmed; refined message not yet live-verified", "http": 423, "discussedValues": [ "RU", "ZZZ" ], "messageTemplate": "Currency value \"{currencyKey}\" is unknown", "example": { "label": "TEMPORARY_ERROR", "message": "Currency value \"RU\" is unknown", "statusDescrption": "2-00100-2", "externalTransactionId": null, "code": "1.2.4.9" } }, "routingObservation": { "status": "Historical H2H HTTP observation; the response body and HTTP 423 were subsequently owner-confirmed for the common deposit/payout routing error. This does not claim live verification of every flow.", "flow": "Deposit H2H", "currency": "EUR", "http": 423, "observedAtUtc": "2026-09-08T10:16:16.62731Z", "evidence": "20260908T101615299Z-currency-three-cases.json#/results/4", "example": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "0000-2", "externalTransactionId": null, "code": "1.2.4.3" }, "universalCodeConfirmed": true, "h2cMappingConfirmed": true, "codeConfirmationDecision": "CREATE-ERRORS-001", "httpConfirmationDecision": "CREATE-HTTP-001", "httpConfirmedAt": "2026-09-15" }, "excluded": [ "Balance", "payout", "missing/null/empty currency", "lowercase policy", "retry policy", "request schema relaxation (separately approved by CUR-CRYPTO-001)" ], "routingPayloadApproval": { "decision": "CREATE-ERRORS-001", "approvedAt": "2026-09-10", "scope": "Common create response body for deposits and payouts", "code": "1.2.4.3", "http": 423, "httpDecision": "CREATE-HTTP-001", "httpApprovedAt": "2026-09-15", "httpMappingConfirmedForAllFlows": true } }, "x-paystar-p2p-presentation": { "decision": "P2P-FORM-001", "approvedAt": "2026-09-10", "scope": "P2P with H2H gateway integration", "merchantOptions": [ "H2H", "H2C" ], "sameRequest": true, "formUrlRequired": true, "exampleIsIllustrative": true } } }, "/api/v1/integration/deposit-order/{externalId}/status": { "get": { "operationId": "getDepositStatusByPayStarId", "summary": "Get deposit status by PayStar ID", "tags": [ "Deposit status" ], "servers": [ { "url": "https://secure.paystar.uk" } ], "security": [ { "bearerAuth": [] } ], "x-paystar-key-capability": "deposit", "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "PayStar order identifier returned by create.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Current order state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositStatusResponse" } } } }, "401": { "description": "Missing or invalid Bearer token." }, "403": { "description": "The key is valid but cannot access this resource." }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" } } } }, "500": { "description": "Internal server error." } } } }, "/api/v1/integration/deposit-order/{externalTransactionId}/status-by-external-transaction-id": { "get": { "operationId": "getDepositStatusByMerchantId", "summary": "Get deposit status by merchant ID", "tags": [ "Deposit status" ], "servers": [ { "url": "https://secure.paystar.uk" } ], "security": [ { "bearerAuth": [] } ], "x-paystar-key-capability": "deposit", "parameters": [ { "name": "externalTransactionId", "in": "path", "required": true, "description": "Merchant-generated external transaction identifier.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Current order state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositStatusResponse" } } } }, "401": { "description": "Missing or invalid Bearer token." }, "403": { "description": "The key is valid but cannot access this resource." }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" } } } }, "500": { "description": "Internal server error." } } } }, "/api/v1/integration/withdrawal-order/": { "post": { "operationId": "createPayout", "summary": "Create an H2H payout", "tags": [ "Payouts" ], "servers": [ { "url": "https://secure.paystar.uk" } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" }, "examples": { "card": { "$ref": "#/components/examples/CardPayoutRequest" } } } } }, "responses": { "200": { "description": "Payout order created. Inspect orderStatus: HTTP 200 can include a Failed processing outcome and does not mean payment success.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PayoutCreateResponse" }, { "$ref": "#/components/schemas/CreatedFailedResponse" } ] }, "examples": { "created_failed": { "summary": "HTTP 200 · Order created, processing failed", "value": { "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "orderStatus": "Failed" } } } } } }, "400": { "description": "Request validation failed, a configured limit was reached, or the merchant order ID already exists. These common examples use owner-confirmed HTTP 400. Currency has no lexical length or pattern validation; this response does not define an alpha-3 mask.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "limit_reached": { "summary": "HTTP 400 · Configured limit reached", "value": { "label": "LIMITS_ERROR", "message": "Limit id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa was reached", "statusDescrption": "0001-0", "externalTransactionId": null } }, "duplicate_merchant_id": { "summary": "HTTP 400 · Duplicate merchant order ID", "value": { "label": "VALIDATION_ERROR", "message": "Order with this external_transaction_id already exist", "statusDescrption": "1-4007", "externalTransactionId": null, "code": "1.1.5.1" } }, "required_field_missing": { "summary": "HTTP 400 · Required parameter missing", "value": { "label": "VALIDATION_ERROR", "message": "additionalField BankAccount not found in request data. Description: Beneficiary’s bank account number, e.g. 1234567890", "statusDescrption": "0000-0", "externalTransactionId": null, "code": "1.2.4.8" } } } } } }, "401": { "description": "Missing or invalid payout Bearer token." }, "403": { "description": "The key is valid but cannot use this payout capability." }, "415": { "description": "Unsupported media type. Framework-level error raised before PayStar business processing.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails415" } } } }, "422": { "description": "Insufficient balance to create the payout. No order is created. HTTP 422 is owner-confirmed in CREATE-HTTP-001; this error applies only to payout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "insufficient_balance": { "summary": "HTTP 422 · Insufficient balance", "value": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "1-4010", "externalTransactionId": null, "code": "1.1.4.3" } } } } } }, "423": { "description": "The currency, amount, or other request parameters do not match available routing conditions for this pipeline. No order is created. HTTP 423 is owner-confirmed in CREATE-HTTP-001.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" }, "examples": { "channel_not_found": { "summary": "HTTP 423 · No matching channel or route", "value": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "0000-2", "externalTransactionId": null, "code": "1.2.4.3" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" } } } } }, "x-paystar-retry-rule": "After timeout, broken connection, missing response, or HTTP 5xx, query status using the same externalTransactionId before retrying." } }, "/api/v1/integration/withdrawal-order/{externalId}/status": { "get": { "operationId": "getPayoutStatusByPayStarId", "summary": "Get payout status by PayStar ID", "tags": [ "Payout status" ], "servers": [ { "url": "https://secure.paystar.uk" } ], "security": [ { "bearerAuth": [] } ], "x-paystar-key-capability": "payout", "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "PayStar order identifier returned by create.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Current order state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutStatusResponse" } } } }, "401": { "description": "Missing or invalid Bearer token." }, "403": { "description": "The key is valid but cannot access this resource." }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" } } } }, "500": { "description": "Internal server error." } } } }, "/api/v1/integration/withdrawal-order/{externalTransactionId}/status-by-external-transaction-id": { "get": { "operationId": "getPayoutStatusByMerchantId", "summary": "Get payout status by merchant ID", "tags": [ "Payout status" ], "servers": [ { "url": "https://secure.paystar.uk" } ], "security": [ { "bearerAuth": [] } ], "x-paystar-key-capability": "payout", "parameters": [ { "name": "externalTransactionId", "in": "path", "required": true, "description": "Merchant-generated external transaction identifier.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Current order state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutStatusResponse" } } } }, "401": { "description": "Missing or invalid Bearer token." }, "403": { "description": "The key is valid but cannot access this resource." }, "404": { "description": "Order not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessError" } } } }, "500": { "description": "Internal server error." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Use the PayStar key assigned to this specific pipeline. Every pipeline has a distinct key, including multiple deposit pipelines. Deposit and payout pipelines never share a key." } }, "schemas": { "CurrencyCode": { "type": "string", "example": "RUB", "description": "Currency key as a string, with no lexical length or pattern validation. Values such as USDT_TRC20 can be submitted; this does not guarantee that a value is known or enabled. For payment creation, PayStar first looks up the exact submitted value in its internal currency dictionary, then searches for a route matching the pipeline conditions. Use the currency key provided for your integration. Fiat commonly uses ISO 4217 alpha-3 codes; crypto may use an asset/network key. Requiredness and operation-specific business errors remain unchanged.", "x-paystar-owner-confirmed": true, "x-paystar-currency-key": { "decision": "CUR-CRYPTO-001", "approvedAt": "2026-09-10", "lexicalFormatValidation": false, "paymentCreationProcessingOrder": [ "internal currency dictionary lookup", "route lookup using pipeline conditions" ], "illustrativeInput": "USDT_TRC20", "illustrativeInputGuaranteesSupport": false, "catalogScope": "Published ISO-style reference only; not an exhaustive internal currency dictionary or an enabled-currency list.", "unchanged": [ "string type", "field requiredness", "operation-specific HTTP outcomes", "amount rules" ], "unconfirmed": [ "crypto catalog and profile support", "dictionary casing and alias matching", "missing/null/empty business behavior" ], "balanceScope": "Shared lexical schema only; no order creation or route lookup is asserted for Balance." } }, "Amount": { "type": "number", "exclusiveMinimum": 0, "example": 100, "description": "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.", "x-paystar-normal-decimal-places": 2, "x-paystar-display-format": "0.00", "x-paystar-string-compatibility": true }, "ExternalTransactionId": { "type": "string", "minLength": 1, "description": "Unique merchant-generated identifier used for status lookup and safe retry resolution." }, "AdditionalFieldValue": { "description": "Flow-specific scalar. Presence and non-null value are normative; formats and ranges belong to the selected flow schema.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "AdditionalField": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "minLength": 1, "description": "Canonical documented casing is lowerCamelCase." }, "value": { "$ref": "#/components/schemas/AdditionalFieldValue" } } }, "BaseDepositRequest": { "type": "object", "required": [ "amount", "currency", "externalTransactionId" ], "properties": { "amount": { "allOf": [ { "$ref": "#/components/schemas/Amount" } ], "x-paystar-p2p-rounding": { "mode": "half-up", "decimalPlaces": 2, "examples": { "100.124": 100.12, "100.125": 100.13, "100.126": 100.13 } } }, "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "externalTransactionId": { "$ref": "#/components/schemas/ExternalTransactionId" }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL." }, "processingRedirectUrl": { "type": "string", "format": "uri" }, "failedRedirectUrl": { "type": "string", "format": "uri" }, "successRedirectUrl": { "type": "string", "format": "uri" }, "additionalFields": { "type": "array", "items": { "$ref": "#/components/schemas/AdditionalField" }, "description": "Array of objects with key and value. The required field set depends on the individual configuration of each terminal (pipeline). Ask your integration manager for the current required fields before sending a request. A catalog entry is not automatically required or supported for every terminal." } } }, "P2PDepositRequest": { "title": "P2P H2H deposit request", "allOf": [ { "$ref": "#/components/schemas/BaseDepositRequest" }, { "type": "object", "required": [ "processingRedirectUrl", "failedRedirectUrl", "successRedirectUrl" ] } ] }, "H2CDepositRequest": { "title": "H2C hosted-form deposit request", "allOf": [ { "$ref": "#/components/schemas/BaseDepositRequest" } ], "x-paystar-pci-rule": "Merchant must not collect card data." }, "TokenDepositRequest": { "title": "Tokenized H2H deposit request", "allOf": [ { "$ref": "#/components/schemas/BaseDepositRequest" }, { "type": "object", "required": [ "additionalFields" ], "properties": { "additionalFields": { "type": "array", "minContains": 1, "contains": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "const": "cardStorageToken" } } }, "items": { "$ref": "#/components/schemas/AdditionalField" } } } } ] }, "PayoutRequest": { "type": "object", "required": [ "amount", "currency", "externalTransactionId" ], "properties": { "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "$ref": "#/components/schemas/CurrencyCode" }, "externalTransactionId": { "$ref": "#/components/schemas/ExternalTransactionId" }, "callbackUrl": { "type": "string", "format": "uri" }, "additionalFields": { "type": "array", "items": { "$ref": "#/components/schemas/AdditionalField" }, "description": "Required key set is merchant- and flow-configured. Confirm it with the PayStar manager.", "x-paystar-requiredness": "flow-specific" } }, "description": "Deposit redirect fields are not payout request fields and must not be added to canonical payout examples." }, "P2PPaymentDetails": { "type": "object", "properties": { "card": { "type": [ "string", "null" ], "description": "Sensitive payment detail; redact in stored evidence." }, "fio": { "type": [ "string", "null" ] }, "bank": { "type": [ "string", "null" ] }, "formUrl": { "type": "string", "format": "uri", "description": "Required non-null PayStar payment-form URI in a valid accepted P2P response. The merchant may use this H2C presentation instead of displaying the returned payment instructions itself. Use the full returned URL, not this illustrative EXAMPLE_ONLY query. Never log one-time query tokens.", "example": "https://p2p.paystar.uk/?EXAMPLE_ONLY" }, "number": { "description": "Recipient phone payment instruction at paymentDetails.number, not phoneNumber or card. It is a string in the owner example; preserve the plus sign and value as returned. No numeric conversion, E.164, length, requiredness or nullability rule is inferred.", "example": "", "x-paystar-observed-type": "string", "x-paystar-confirmation": { "source": "owner-provided example", "date": "2026-09-10", "decision": "P2P-DETAILS-001", "requiredness": "not established for all profiles", "nullability": "not established", "noNewValueConstraints": true } }, "iban": { "description": "IBAN payment instruction at paymentDetails.iban. Keep it as a string. Confirmed by the owner example, not a universal required field.", "example": "", "x-paystar-observed-type": "string", "x-paystar-confirmation": { "source": "owner-provided example", "date": "2026-09-10", "decision": "P2P-DETAILS-001", "requiredness": "not established for all profiles", "nullability": "not established", "noNewValueConstraints": true } }, "accountNumber": { "description": "Account-number payment instruction at paymentDetails.accountNumber, not bankAccount. Keep the string exactly as returned, including leading zeroes. It can coexist with qrUrl, as in the owner example.", "example": "", "x-paystar-observed-type": "string", "x-paystar-confirmation": { "source": "owner-provided example", "date": "2026-09-10", "decision": "P2P-DETAILS-001", "requiredness": "not established for all profiles", "nullability": "not established", "noNewValueConstraints": true } }, "qrUrl": { "description": "QR content at paymentDetails.qrUrl. The owner labels this value Base64; despite the field name, it is not confirmed to be an HTTP URL. Actual QR bytes, MIME type and raw-Base64 versus data-URI envelope remain unconfirmed.", "example": "", "x-paystar-observed-type": "string", "x-paystar-confirmation": { "source": "owner-provided example", "date": "2026-09-10", "decision": "P2P-DETAILS-001", "requiredness": "not established for all profiles", "nullability": "not established", "noNewValueConstraints": true } }, "method": { "description": "Method label at paymentDetails.method. ArsCbu is an owner-provided example, not a complete enum or a unique response-variant discriminator.", "example": "ArsCbu", "x-paystar-observed-type": "string", "x-paystar-confirmation": { "source": "owner-provided example", "date": "2026-09-10", "decision": "P2P-DETAILS-001", "requiredness": "not established for all profiles", "nullability": "not established", "noNewValueConstraints": true } } }, "required": [ "formUrl" ], "description": "Payment instructions and the PayStar form URL returned together for P2P with an H2H gateway integration (P2P-FORM-001, owner-confirmed 2026-09-10).", "x-paystar-detail-mapping": { "decision": "P2P-DETAILS-001", "confirmedAt": "2026-09-10", "source": "owner-provided examples; no new live test", "phoneNumberPathConfirmed": true, "phoneNumberResponsePath": "paymentDetails.number", "qrEncodingDetailsConfirmed": false, "methodEnumConfirmed": false, "exclusiveVariants": false }, "examples": [ { "fio": "", "bank": "", "number": "", "formUrl": "https://checkout.example/EXAMPLE_ONLY" }, { "fio": "", "iban": "", "formUrl": "https://checkout.example/EXAMPLE_ONLY" }, { "fio": "", "method": "ArsCbu", "formUrl": "https://checkout.example/EXAMPLE_ONLY", "accountNumber": "" }, { "qrUrl": "", "fio": "", "method": "ArsCbu", "formUrl": "https://checkout.example/EXAMPLE_ONLY", "accountNumber": "" } ] }, "P2PDepositCreateResponse": { "type": "object", "required": [ "externalId", "orderStatus", "paymentDetails" ], "properties": { "externalId": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "Processing" ] }, "paymentDetails": { "$ref": "#/components/schemas/P2PPaymentDetails" } }, "description": "When the gateway integration uses H2H, the same P2P create request returns both payment instructions and a PayStar payment-form URL. The merchant can display the instructions in its own checkout (H2H) or send the customer to the returned PayStar form (H2C), without creating another order or changing the request.", "example": { "externalId": "", "orderStatus": "Processing", "paymentDetails": { "card": "", "fio": "", "bank": "", "formUrl": "https://p2p.paystar.uk/?EXAMPLE_ONLY" } }, "examples": [ { "externalId": "", "orderStatus": "Processing", "paymentDetails": { "card": "", "fio": "", "bank": "", "formUrl": "https://p2p.paystar.uk/?EXAMPLE_ONLY" } }, { "externalId": "", "orderStatus": "Processing", "paymentDetails": { "fio": "", "bank": "", "number": "", "formUrl": "https://checkout.example/EXAMPLE_ONLY" } }, { "externalId": "", "orderStatus": "Processing", "paymentDetails": { "fio": "", "iban": "", "formUrl": "https://checkout.example/EXAMPLE_ONLY" } }, { "externalId": "", "orderStatus": "Processing", "paymentDetails": { "fio": "", "method": "ArsCbu", "formUrl": "https://checkout.example/EXAMPLE_ONLY", "accountNumber": "" } }, { "externalId": "", "orderStatus": "Processing", "paymentDetails": { "qrUrl": "", "fio": "", "method": "ArsCbu", "formUrl": "https://checkout.example/EXAMPLE_ONLY", "accountNumber": "" } } ] }, "H2CDepositCreateResponse": { "type": "object", "required": [ "externalId", "orderStatus", "formUrl" ], "properties": { "externalId": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "Init" ] }, "formUrl": { "type": "string", "format": "uri" } } }, "TokenDepositCreateResponse": { "type": "object", "required": [ "externalId", "orderStatus" ], "properties": { "externalId": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "Processing" ] }, "paymentDetails": { "type": "object", "properties": { "formUrl": { "type": [ "string", "null" ], "format": "uri" } } } } }, "PayoutCreateResponse": { "type": "object", "required": [ "externalId", "orderStatus" ], "properties": { "externalId": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "Created" ] } } }, "OrderHistoryItem": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "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": { "type": [ "string", "null" ], "description": "Payment History action code." }, "newCode": { "type": [ "string", "null" ], "description": "Additional Payment History code returned by the current API." } } }, "ExternalParams": { "type": "object", "properties": { "cardToken": { "type": [ "string", "null" ], "writeOnly": false, "description": "Sensitive; access and logging must be restricted." }, "cardStorageToken": { "type": [ "string", "null" ], "writeOnly": false, "description": "Sensitive; access and logging must be restricted." }, "cardHolder": { "type": [ "string", "null" ] }, "cardNumber": { "type": [ "string", "null" ], "description": "Must be masked when returned." } }, "additionalProperties": true, "description": "Flow-dependent object; it may be absent or contain null fields." }, "DepositStatusResponse": { "type": "object", "required": [ "externalId", "orderStatus", "orderHistory" ], "properties": { "externalId": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "Init", "Created", "Processing", "Success", "Failed" ], "description": "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": { "$ref": "#/components/schemas/Amount" }, "externalParams": { "$ref": "#/components/schemas/ExternalParams" }, "currency": { "$ref": "#/components/schemas/CurrencyCode", "description": "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." }, "orderHistory": { "type": "array", "items": { "$ref": "#/components/schemas/OrderHistoryItem" }, "description": "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 } }, "x-paystar-p2p-status-correction": { "decision": "P2P-STATE-001", "confirmedAt": "2026-09-10", "scope": "P2P deposits, including merchant-side H2H/H2C presentation", "from": "Failed", "to": "Success", "sameOrder": true, "identifiersUnchanged": true, "usualInitiator": "merchant support", "callbackHandlingRequired": true, "reverseBusinessTransitionRequired": false, "liveCorrectionVerified": false, "liveCallbackDeliveryVerified": false, "correctionDeadlineConfirmed": false, "pollingStopPolicyConfirmed": false, "deliveryContract": "Payload, signature, acknowledgement and retry details still require approved fixtures; this lifecycle decision does not define them.", "handling": "Process an authenticated Success correction for the existing P2P order even if it was Failed. Do not discard it solely because the order ID has been seen. Apply the successful business effect idempotently. Do not downgrade a stored Success to Failed; this does not waive callback validation or the agreed acknowledgement protocol." }, "x-paystar-deposit-history": { "decision": "DEP-STATUS-001", "confirmedAt": "2026-09-11", "scope": [ "getDepositStatusByMerchantId", "getDepositStatusByPayStarId" ], "required": true, "minItems": 1, "currentStateField": "orderStatus", "completeTraceGuaranteed": false, "payoutAndCallbackRulesChanged": false } }, "PayoutStatusResponse": { "type": "object", "required": [ "externalId", "orderStatus" ], "properties": { "externalId": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "Created", "Processing", "Success", "Failed" ] }, "amount": { "$ref": "#/components/schemas/Amount" }, "externalParams": { "$ref": "#/components/schemas/ExternalParams" }, "orderHistory": { "type": "array", "items": { "$ref": "#/components/schemas/OrderHistoryItem" }, "description": "Not guaranteed to be populated and may be delayed." } } }, "Balance": { "type": "object", "required": [ "currency", "merchantBalance", "merchantOverdraft", "pipelineBalance", "pipelineAvailableBalance", "pipelineProcessingOrdersDeposit", "pipelineProcessingOrdersWithdrawals" ], "properties": { "currency": { "type": "string" }, "merchantBalance": { "type": "number" }, "merchantOverdraft": { "type": "number" }, "pipelineBalance": { "type": "number" }, "pipelineAvailableBalance": { "type": "number" }, "pipelineProcessingOrdersDeposit": { "type": "number" }, "pipelineProcessingOrdersWithdrawals": { "type": "number" } } }, "BusinessError": { "type": "object", "required": [ "label", "message" ], "properties": { "label": { "type": "string", "examples": [ "VALIDATION_ERROR", "REQUEST_VALIDATION_ERROR", "TEMPORARY_ERROR", "NOT_FOUND", "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string", "description": "Do not branch on exact message text." }, "statusDescrption": { "type": [ "string", "null" ], "description": "Current compatible wire spelling, including the typo." }, "externalTransactionId": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "description": "Application code; the complete stable catalog is not yet documented." } } }, "ProblemDetails415": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string", "example": "Unsupported Media Type" }, "status": { "type": "integer", "const": 415 }, "traceId": { "type": "string" } } }, "CreatedFailedResponse": { "type": "object", "required": [ "externalId", "orderStatus" ], "properties": { "externalId": { "type": "string" }, "orderStatus": { "type": "string", "enum": [ "Failed" ] } } } }, "examples": { "P2PDepositRequest": { "summary": "P2P H2H request", "value": { "amount": 100, "currency": "RUB", "externalTransactionId": "merchant-deposit-123", "callbackUrl": "https://merchant.example/paystar/callback", "processingRedirectUrl": "https://merchant.example/payment/processing", "failedRedirectUrl": "https://merchant.example/payment/failed", "successRedirectUrl": "https://merchant.example/payment/success", "additionalFields": [ { "key": "payeerIdentifier", "value": "Merch-Customer-12345" } ] } }, "H2CDepositRequest": { "summary": "H2C hosted-form request", "value": { "amount": 100, "currency": "RUB", "externalTransactionId": "merchant-h2c-123", "callbackUrl": "https://merchant.example/paystar/callback", "additionalFields": [] } }, "TokenDepositRequest": { "summary": "Tokenized H2H request", "value": { "amount": 100, "currency": "RUB", "externalTransactionId": "merchant-token-deposit-123", "callbackUrl": "https://merchant.example/paystar/callback", "additionalFields": [ { "key": "cardStorageToken", "value": "{{cardStorageToken}}" } ] } }, "CardPayoutRequest": { "summary": "Typical card payout; confirm exact required fields with the PayStar manager", "value": { "amount": 1000, "currency": "RUB", "externalTransactionId": "merchant-payout-123", "callbackUrl": "https://merchant.example/paystar/callback", "additionalFields": [ { "key": "payeerIdentifier", "value": "merchant-customer-123" }, { "key": "bankName", "value": "Example Bank" }, { "key": "cardHolder", "value": "TEST CARDHOLDER" }, { "key": "cardNumber", "value": "{{testCardNumber}}" } ] } } } }, "x-paystar-contract-version": "2026-08-25.9", "x-paystar-published-date": "2026-08-25", "x-paystar-create-payload-examples": { "decision": "CREATE-ERRORS-001", "approvedAt": "2026-09-10", "exhaustive": false, "scope": [ "P2P deposit H2H/H2C", "ECOM H2H deposit", "Hosted H2C deposit", "Tokenized deposit", "Payout" ], "scopeMeaning": "Catalog coverage; an item appliesTo value overrides the catalog scope.", "scopeDecision": "CREATE-SCOPE-001", "scopeApprovedAt": "2026-09-15", "operations": [ "POST /api/v1/integration/deposit-order/", "POST /api/v1/integration/withdrawal-order/" ], "purpose": "Common unsuccessful-create response examples with owner-confirmed HTTP codes; not an exhaustive API error catalog.", "httpDecision": "CREATE-HTTP-001", "httpApprovedAt": "2026-09-15", "httpMapping": "HTTP values are owner-confirmed for each item scope. Other responses are not reclassified by this mapping.", "schemaBoundary": "CreatedFailedResponse is a separate HTTP 200 variant. Existing accepted-response branches remain unchanged; other examples use the existing BusinessError schema without new field constraints.", "emptyBodyResponses": "401/403 and other responses without JSON are outside this payload gallery; existing HTTP guidance still applies.", "liveCoverage": "Owner-supplied examples, not new per-flow live tests.", "items": [ { "id": "created_failed", "title": "Order created, processing failed", "orderCreated": true, "http": 200, "description": "The request produced an order, but processing failed. Keep the PayStar externalId and your original merchant order ID. This is not a rejection without an order.", "note": "HTTP 200 means the order was created, not that the payment succeeded. This body uses orderStatus, not status, and does not include payment details or a form URL. Inspect orderStatus and retain both order identifiers.", "payload": { "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "orderStatus": "Failed" } }, { "id": "channel_not_found", "title": "No matching channel or route", "orderCreated": false, "http": 423, "description": "The currency, amount, or other request parameters do not match available routing conditions for this pipeline. No order is created.", "note": "", "payload": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "0000-2", "externalTransactionId": null, "code": "1.2.4.3" } }, { "id": "insufficient_balance", "title": "Insufficient balance", "orderCreated": false, "http": 422, "appliesTo": [ "Payout" ], "description": "Insufficient balance to create the payout. No order is created.", "note": "Confirm the balance involved with your manager; the payload alone does not identify an account or wallet.", "payload": { "label": "TEMPORARY_ERROR", "message": "TEMPORARY_ERROR", "statusDescrption": "1-4010", "externalTransactionId": null, "code": "1.1.4.3" } }, { "id": "limit_reached", "title": "Configured limit reached", "orderCreated": false, "http": 400, "description": "A configured limit was reached. No order is created.", "note": "The limit ID is illustrative. This example has no code field; do not map the error by a particular UUID or exact message text.", "payload": { "label": "LIMITS_ERROR", "message": "Limit id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa was reached", "statusDescrption": "0001-0", "externalTransactionId": null } }, { "id": "duplicate_merchant_id", "title": "Duplicate merchant order ID", "orderCreated": false, "http": 400, "description": "An order with this merchant ID already exists. No new order is created by this rejected attempt.", "note": "Query the existing order using the original externalTransactionId from your request, even when externalTransactionId is null in this error. Do not replace the ID for a blind retry.", "payload": { "label": "VALIDATION_ERROR", "message": "Order with this external_transaction_id already exist", "statusDescrption": "1-4007", "externalTransactionId": null, "code": "1.1.5.1" } }, { "id": "required_field_missing", "title": "Required parameter missing", "orderCreated": false, "http": 400, "description": "A field required by the configured terminal is missing. No order is created.", "note": "BankAccount is an example of a configured requirement, not a mandatory field for every flow. Use the required-field list supplied for your terminal.", "payload": { "label": "VALIDATION_ERROR", "message": "additionalField BankAccount not found in request data. Description: Beneficiary’s bank account number, e.g. 1234567890", "statusDescrption": "0000-0", "externalTransactionId": null, "code": "1.2.4.8" } } ] }, "x-paystar-ecom-examples": { "decision": "ECOM-EXAMPLES-001", "source": "owner-provided request/response examples", "recordedAt": "2026-09-10", "liveTestPerformed": false, "contractBoundary": "Illustrative examples, not a complete normative schema. Requiredness, formats, HTTP status, supported flowData variants and redirect precedence are not inferred.", "keyCasing": "Exact PascalCase keys from the owner examples are preserved. Existing lowerCamelCase guidance and compatibility remain unchanged.", "slashBoundary": "The owner H2H sample omits the final slash; the H2C sample includes it. No redirect or alias equivalence has been tested by this update.", "examples": { "h2h": { "url": "https://secure.paystar.uk/api/v1/integration/deposit-order", "contentType": "application/json; charset=utf-8", "request": { "amount": 20, "currency": "AZN", "externalTransactionId": "UNIQUE_MERCHANT_ID", "failedRedirectUrl": "https://merchant.example/failed", "processingRedirectUrl": "https://merchant.example/processing", "successRedirectUrl": "https://merchant.example/success", "callbackUrl": "https://merchant.example/callback", "additionalFields": [ { "key": "PayeerIdentifier", "value": "MERCHANT_CUSTOMER_ID" }, { "key": "CardNumber", "value": "" }, { "key": "CardExpireYear", "value": "30" }, { "key": "CardExpireMonth", "value": "06" }, { "key": "CardCvv", "value": "" }, { "key": "CardHolder", "value": "" } ] }, "response": { "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "orderStatus": "Processing", "paymentDetails": { "formUrl": "https://redirect.example/EXAMPLE_ONLY", "flowData": { "action": "https://gateway.example/redirect?token=EXAMPLE_ONLY", "method": "GET", "params": [ { "name": "token", "value": "EXAMPLE_ONLY" } ], "metadata": { "description": "Redirect the user to complete payment", "type": "redirect" }, "instruction": { "type": "query" } } } } }, "h2c": { "url": "https://init.paystar.uk/api/v1/integration/deposit-order/", "contentType": "application/json; charset=utf-8", "request": { "amount": 50, "currency": "AZN", "externalTransactionId": "UNIQUE_MERCHANT_ID", "failedRedirectUrl": "https://merchant.example/failed", "processingRedirectUrl": "https://merchant.example/processing", "successRedirectUrl": "https://merchant.example/success", "callbackUrl": "https://merchant.example/callback", "additionalFields": [ { "key": "PayeerIdentifier", "value": "MERCHANT_CUSTOMER_ID" } ] }, "response": { "externalId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "orderStatus": "Init", "formUrl": "https://checkout.example/EXAMPLE_ONLY" } } } }, "x-paystar-deposit-status-examples": { "decision": "DEP-STATUS-001", "recordedAt": "2026-09-11", "source": "Owner-provided deposit status wire examples; order IDs anonymized.", "operationIds": [ "getDepositStatusByMerchantId", "getDepositStatusByPayStarId" ], "liveTestPerformed": false, "httpStatusProvided": false, "timestampNotice": "The supplied times are UTC without Z/offset. They retain the known mismatch with the existing date-time schema; no timezone suffix has been added to these wire examples.", "examples": { "success": { "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "orderStatus": "Success", "externalParams": { "cardToken": null, "cardStorageToken": null, "cardHolder": null, "cardNumber": null }, "amount": 10000, "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": { "externalId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "orderStatus": "Failed", "externalParams": { "cardToken": null, "cardStorageToken": null, "cardHolder": null, "cardNumber": null }, "amount": 26250, "currency": "ARS", "orderHistory": [ { "time": "2026-09-11T10:30:43.941409", "action": "1.2.1.1", "newCode": "1.1.4.32" } ] } } }, "x-paystar-preview": { "revision": "2026-09-15.5", "sourceBaseline": "2026-08-25.9", "sourceSnapshotUtc": "2026-09-08T06:51:10Z", "sourceSha256": "6ac32af9231a0e6f0870ae12c2129fb9065621e2704507d2981431738b81bd24", "jsonRepair": "Removed 26 syntactic trailing commas only.", "reviewPath": "/api/review", "productionContract": false } }