Reference dictionaries

{
  "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."
  }
}

{
  "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
}

{
  "type": "string",
  "minLength": 1,
  "description": "Unique merchant-generated identifier used for status lookup and safe retry resolution."
}

{
  "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"
    }
  ]
}

{
  "type": "object",
  "required": [
    "key",
    "value"
  ],
  "properties": {
    "key": {
      "type": "string",
      "minLength": 1,
      "description": "Canonical documented casing is lowerCamelCase."
    },
    "value": {
      "$ref": "#/components/schemas/AdditionalFieldValue"
    }
  }
}

{
  "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."
    }
  }
}

{
  "title": "P2P H2H deposit request",
  "allOf": [
    {
      "$ref": "#/components/schemas/BaseDepositRequest"
    },
    {
      "type": "object",
      "required": [
        "processingRedirectUrl",
        "failedRedirectUrl",
        "successRedirectUrl"
      ]
    }
  ]
}

{
  "title": "H2C hosted-form deposit request",
  "allOf": [
    {
      "$ref": "#/components/schemas/BaseDepositRequest"
    }
  ],
  "x-paystar-pci-rule": "Merchant must not collect card data."
}

{
  "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"
          }
        }
      }
    }
  ]
}

{
  "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."
}

{
  "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": "<RECIPIENT_PHONE_NUMBER>",
      "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": "<IBAN>",
      "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": "<ACCOUNT_NUMBER>",
      "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": "<BASE64_QR_DATA>",
      "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": "<RECIPIENT_NAME>",
      "bank": "<BANK_NAME>",
      "number": "<RECIPIENT_PHONE_NUMBER>",
      "formUrl": "https://checkout.example/EXAMPLE_ONLY"
    },
    {
      "fio": "<RECIPIENT_NAME>",
      "iban": "<IBAN>",
      "formUrl": "https://checkout.example/EXAMPLE_ONLY"
    },
    {
      "fio": "<RECIPIENT_NAME>",
      "method": "ArsCbu",
      "formUrl": "https://checkout.example/EXAMPLE_ONLY",
      "accountNumber": "<ACCOUNT_NUMBER>"
    },
    {
      "qrUrl": "<BASE64_QR_DATA>",
      "fio": "<RECIPIENT_NAME>",
      "method": "ArsCbu",
      "formUrl": "https://checkout.example/EXAMPLE_ONLY",
      "accountNumber": "<ACCOUNT_NUMBER>"
    }
  ]
}

{
  "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": "<PAYSTAR_ORDER_ID>",
    "orderStatus": "Processing",
    "paymentDetails": {
      "card": "<REDACTED_PAYMENT_DETAIL>",
      "fio": "<RECIPIENT_NAME>",
      "bank": "<BANK_NAME>",
      "formUrl": "https://p2p.paystar.uk/?EXAMPLE_ONLY"
    }
  },
  "examples": [
    {
      "externalId": "<PAYSTAR_ORDER_ID>",
      "orderStatus": "Processing",
      "paymentDetails": {
        "card": "<REDACTED_PAYMENT_DETAIL>",
        "fio": "<RECIPIENT_NAME>",
        "bank": "<BANK_NAME>",
        "formUrl": "https://p2p.paystar.uk/?EXAMPLE_ONLY"
      }
    },
    {
      "externalId": "<PAYSTAR_ORDER_ID>",
      "orderStatus": "Processing",
      "paymentDetails": {
        "fio": "<RECIPIENT_NAME>",
        "bank": "<BANK_NAME>",
        "number": "<RECIPIENT_PHONE_NUMBER>",
        "formUrl": "https://checkout.example/EXAMPLE_ONLY"
      }
    },
    {
      "externalId": "<PAYSTAR_ORDER_ID>",
      "orderStatus": "Processing",
      "paymentDetails": {
        "fio": "<RECIPIENT_NAME>",
        "iban": "<IBAN>",
        "formUrl": "https://checkout.example/EXAMPLE_ONLY"
      }
    },
    {
      "externalId": "<PAYSTAR_ORDER_ID>",
      "orderStatus": "Processing",
      "paymentDetails": {
        "fio": "<RECIPIENT_NAME>",
        "method": "ArsCbu",
        "formUrl": "https://checkout.example/EXAMPLE_ONLY",
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    },
    {
      "externalId": "<PAYSTAR_ORDER_ID>",
      "orderStatus": "Processing",
      "paymentDetails": {
        "qrUrl": "<BASE64_QR_DATA>",
        "fio": "<RECIPIENT_NAME>",
        "method": "ArsCbu",
        "formUrl": "https://checkout.example/EXAMPLE_ONLY",
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ]
}

{
  "type": "object",
  "required": [
    "externalId",
    "orderStatus",
    "formUrl"
  ],
  "properties": {
    "externalId": {
      "type": "string"
    },
    "orderStatus": {
      "type": "string",
      "enum": [
        "Init"
      ]
    },
    "formUrl": {
      "type": "string",
      "format": "uri"
    }
  }
}

{
  "type": "object",
  "required": [
    "externalId",
    "orderStatus"
  ],
  "properties": {
    "externalId": {
      "type": "string"
    },
    "orderStatus": {
      "type": "string",
      "enum": [
        "Processing"
      ]
    },
    "paymentDetails": {
      "type": "object",
      "properties": {
        "formUrl": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri"
        }
      }
    }
  }
}

{
  "type": "object",
  "required": [
    "externalId",
    "orderStatus"
  ],
  "properties": {
    "externalId": {
      "type": "string"
    },
    "orderStatus": {
      "type": "string",
      "enum": [
        "Created"
      ]
    }
  }
}

{
  "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."
    }
  }
}

{
  "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."
}

{
  "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
  }
}

{
  "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."
    }
  }
}

{
  "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"
    }
  }
}

{
  "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."
    }
  }
}

{
  "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"
    }
  }
}

{
  "type": "object",
  "required": [
    "externalId",
    "orderStatus"
  ],
  "properties": {
    "externalId": {
      "type": "string"
    },
    "orderStatus": {
      "type": "string",
      "enum": [
        "Failed"
      ]
    }
  }
}