PAYSTAR / DEVELOPER DOCUMENTATION

Payouts

Create a withdrawal with the fields and credentials assigned to your payout pipeline.

[01]

Create an H2H payout

Use credentials assigned to a payout pipeline. Required additional fields, available currencies and limits depend on that profile.

POSThttps://secure.paystar.uk/api/v1/integration/withdrawal-order/

Files in Downloads: OpenAPI JSON · YAML · Postman collection · Postman environment.

Reference files: Additional fields · Currencies · Errors and handling caveats.

Request contract

Field	Presence	Type & meaning
`amount`	Required	`number` 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. exclusiveMinimum: 0 Amount
`currency`	Required	`string` 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. CurrencyCode
`externalTransactionId`	Required	`string` Unique merchant-generated identifier used for status lookup and safe retry resolution. minLength: 1 ExternalTransactionId
`callbackUrl`	Optional	`string · uri`
`additionalFields`	Optional	`array of object` Required key set is merchant- and flow-configured. Confirm it with the PayStar manager.

Illustrative card-payout request

In Downloads, open the shared Postman collection and select Create Payout — approved destination fixture required. Use the profile-specific environment.

cURLSelect text to copy

curl --request POST \
  --url 'https://secure.paystar.uk/api/v1/integration/withdrawal-order/' \
  --header 'Authorization: Bearer <PAYSTAR_PAYOUT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 100.00,
  "currency": "RUB",
  "externalTransactionId": "UNIQUE_MERCHANT_ID",
  "additionalFields": [
    {
      "key": "cardNumber",
      "value": "<APPROVED_TEST_FIXTURE>"
    }
  ]
}'

Accepted response

Field	Presence	Type & meaning
`externalId`	Required	`string`
`orderStatus`	Required	`string · Created`

JSONSelect text to copy

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Created"
}

Unsuccessful responseCommon JSON payloads

These are common examples for this flow, not an exhaustive list of API errors; profile-specific requirements still apply. HTTP codes are owner-confirmed for these examples. Responses without a body do not have a JSON example here.

HTTP 200 · Order created, processing failedOrder created

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.

HTTP: 200

JSON · HTTP 200 response bodySelect text to copy

{
  "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "orderStatus": "Failed"
}

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.

HTTP 423 · No matching channel or routeNo new order

The currency, amount, or other request parameters do not match available routing conditions for this pipeline. No order is created.

HTTP: 423

JSON · HTTP 423 response bodySelect text to copy

{
  "label": "TEMPORARY_ERROR",
  "message": "TEMPORARY_ERROR",
  "statusDescrption": "0000-2",
  "externalTransactionId": null,
  "code": "1.2.4.3"
}

HTTP 422 · Insufficient balanceNo new order

Insufficient balance to create the payout. No order is created.

HTTP: 422

JSON · HTTP 422 response bodySelect text to copy

{
  "label": "TEMPORARY_ERROR",
  "message": "TEMPORARY_ERROR",
  "statusDescrption": "1-4010",
  "externalTransactionId": null,
  "code": "1.1.4.3"
}

Confirm the balance involved with your manager; the payload alone does not identify an account or wallet.

HTTP 400 · Configured limit reachedNo new order

A configured limit was reached. No order is created.

HTTP: 400

JSON · HTTP 400 response bodySelect text to copy

{
  "label": "LIMITS_ERROR",
  "message": "Limit id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa was reached",
  "statusDescrption": "0001-0",
  "externalTransactionId": null
}

The limit ID is illustrative. This example has no code field; do not map the error by a particular UUID or exact message text.

HTTP 400 · Duplicate merchant order IDNo new order

An order with this merchant ID already exists. No new order is created by this rejected attempt.

HTTP: 400

JSON · HTTP 400 response bodySelect text to copy

{
  "label": "VALIDATION_ERROR",
  "message": "Order with this external_transaction_id already exist",
  "statusDescrption": "1-4007",
  "externalTransactionId": null,
  "code": "1.1.5.1"
}

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.

HTTP 400 · Required parameter missingNo new order

A field required by the configured terminal is missing. No order is created.

HTTP: 400

JSON · HTTP 400 response bodySelect text to copy

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

BankAccount is an example of a configured requirement, not a mandatory field for every flow. Use the required-field list supplied for your terminal.

Unknown currency → · HTTP and transport responses → · Download error catalog and payload examples · JSON ↓

HTTP outcomes

HTTP	Meaning
`200`	Payout order created. Inspect orderStatus: HTTP 200 can include a Failed processing outcome and does not mean payment success.
`400`	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. BusinessError & handling
`401`	Missing or invalid payout Bearer token.
`403`	The key is valid but cannot use this payout capability.
`415`	Unsupported media type. Framework-level error raised before PayStar business processing.
`422`	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. BusinessError & handling
`423`	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. BusinessError & handling
`500`	Internal server error. BusinessError & handling

[02]

Follow the payout outcome

Keep the returned PayStar ID and the original merchant ID. Both status lookup methods are available in the baseline.

Payout status by merchant ID →
Payout status by PayStar ID →

Current payout coverage and the 422 investigation →

Files in Downloads: Order statuses · Payment history.

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

Confirm your profile with Yegor ↗