Payment API Documentation

START BY TASK

Choose what you need to build.

This documentation separates the stable public contract from route-specific configuration. Use it for implementation planning, then confirm the merchant profile before sending traffic.

01Create a depositH2H, hosted or tokenized→ 02Check deposit statusUse either transaction ID→ 03Check the balanceMerchant and pipeline view→ 04Create a payoutH2H payout onboarding→ 05Check payout statusReconcile by either transaction ID→

Merchant-specific by design

The API accepts the documented contract, while active currencies, limits, required additionalFields and routes depend on the pipeline assigned to your merchant.

QUICK START

From credentials to a safe first payment.

01

Choose the flow

Use direct H2H, hosted checkout, a stored-card token, or payout based on how payment data is collected.

02

Configure access

Receive the Bearer key assigned to the pipeline and confirm the server IP, currencies and required fields with PayStar.

03

Create the operation

Send an amount in major currency units and a unique externalTransactionId. Store both your ID and the PayStar ID.

04

Handle uncertainty

Persist asynchronous updates. After a timeout or 5xx, query status with the original merchant ID before any retry.

H2H DEPOSIT · CURLValues are safe placeholders · select the code to copy

curl --request POST \
  --url https://secure.paystar.uk/api/v1/integration/deposit-order/ \
  --header 'Authorization: Bearer <PAYSTAR_DEPOSIT_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 100.00,
    "currency": "EUR",
    "externalTransactionId": "order-demo-001",
    "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": []
  }'

AUTHENTICATION & ENVIRONMENTS

One header. Pipeline-specific access.

Send the key in the Authorization header on every protected request. Each key is issued for one specific pipeline. Two deposit pipelines use different keys, and deposit and payout pipelines never share a key.

HTTP HEADERAuthorization: Bearer <pipeline-specific-key>

Assigned environment

Use only the host and credentials assigned to your integration profile.

Server-side only

Never expose the key in browser code, URLs, source control, screenshots or logs.

Pipeline scope

The key, access, currencies and available operations are bound to one pipeline. Any additional pipeline requires its own key.

API HOSTS

One core API. Two specialized deposit hosts.

secure.paystar.uk is the main domain for the complete API: deposits, balances, payouts and status checks. init.paystar.uk and token.paystar.uk are used only for their specific deposit collection models.

CORE APIPRIMARY HOST

secure.paystar.uk

Use this domain for the full merchant API when it is assigned to your profile. Direct H2H deposit creation on this host uses P2PDepositRequest.

DepositsDeposit statusBalancesPayoutsPayout status

SPECIALIZED DEPOSIT HOSTHOSTED CARD H2C

init.paystar.uk

Hosted card collection that keeps card entry outside the merchant page and can reduce PCI DSS scope. Used only to create this hosted deposit flow.

H2CDepositRequest

SPECIALIZED DEPOSIT HOSTTOKENIZED

token.paystar.uk

Creates a deposit using the token assigned to an approved merchant tokenized flow.

TokenDepositRequest

PCI boundary

Merchants without the required PCI scope must use hosted checkout or an approved tokenized flow instead of collecting card data directly.

LIFECYCLE & SAFE RETRIES

Keep both identifiers and check before repeating.

01CreateSend a unique merchant ID

→

02StoreKeep merchant and PayStar IDs

→

03ObserveRead current status and history

→

04ResolveQuery status before retry

Amounts: use JSON numbers in major currency units. Quoted numeric strings remain backward-compatible only.
Currencies: use alpha-3 codes. A catalog entry does not guarantee an active merchant route.
Status: treat orderStatus as current state. orderHistory can be empty or delayed.
Errors: branch on HTTP status and explicitly stable codes, not exact message text.
Retry: after timeout, missing response or 5xx, query by the original externalTransactionId first.

DASHBOARD BUILDING BLOCKS

Build your own internal payment dashboard.

PayStar can provide your developers with a set of API methods and reusable frontend components for a payment dashboard with the same operational depth as our own interfaces. Use them to assemble the views and workflows your support, finance and payment teams need.

01 · METHODS

Use dashboard-ready API methods

Bring deposits, payouts, balances, statuses and exceptions into one consistent data layer.

02 · COMPONENTS

Start from frontend building blocks

Use reusable PayStar components for payment views and operational workflows instead of building every interface element from scratch.

03 · COMPOSE

Fit the dashboard to your operation

Build a private payment workspace around the roles, data and actions your team actually needs.

PLAN YOUR DASHBOARDChoose the methods and components for your internal payment view.

Book a call with Yegor →

API REFERENCE

Seven operations in the current contract.

Open an operation to inspect its request contract, successful response and HTTP outcomes. Each stable operationId can also be used as an anchor by documentation and code-generation tools.

Deposits

POST/api/v1/integration/deposit-order/FLOW-SPECIFIC

Create a deposit

Creates an H2H, hosted or tokenized deposit according to the selected host and request schema.

Request & response contract3 flow schemas · 7 responses

Request body

application/json

secure.paystar.uk · core APIP2PDepositRequestDirect H2H deposit on the primary host. Shared fields plus all three redirect URLs.

init.paystar.ukH2CDepositRequestShared fields; hosted acquiring without merchant PCI DSS scope.

token.paystar.ukTokenDepositRequestShared fields plus additionalFields containing cardStorageToken.

amountrequired: numberAmount in major currency units.
currencyrequired: string · alpha-3Payment currency.
externalTransactionIdrequired: stringUnique merchant transaction ID.
callbackUrl: string · URIOptional asynchronous status callback URL.
processingRedirectUrlP2P required: string · URICustomer redirect while the payment is processing.
failedRedirectUrlP2P required: string · URICustomer redirect after a failed payment.
successRedirectUrlP2P required: string · URICustomer redirect after a successful payment.
additionalFields[]token required: key/value objectsFlow-specific fields; token flow must include cardStorageToken.

200 · Flow-specific response

application/json

P2PDepositCreateResponseexternalId · orderStatusOptional paymentDetails: card, fio, bank and formUrl. Treat these values as sensitive.

H2CDepositCreateResponseexternalId · orderStatus · formUrlOpen the returned hosted form URL for the customer.

TokenDepositCreateResponseexternalId · orderStatusOptional paymentDetails.formUrl.

HTTP responses

200: Deposit accepted · response schema depends on the selected host.
400: Request validation failed · BusinessError
401: Missing or invalid deposit Bearer token.
403: Valid key without this deposit capability.
415: Unsupported media type · ProblemDetails415
423: No active route for the request, currency or configured limits · BusinessError
500: Internal error · BusinessError

operationId: createDepositThe request schema depends on the assigned deposit flow.

Deposit status

GET/api/v1/integration/deposit-order/{externalId}/statusDOCUMENTED

Get deposit status by PayStar ID

Request & response contract1 path parameter · 5 responses

Request

path

externalIdrequired: stringPayStar order ID returned by the create operation.

200 · DepositStatusResponse

application/json

externalIdrequired: stringPayStar order ID.
orderStatusrequired: enumInit, Created, Processing, Success or Failed.
amount: numberOrder amount.
externalParams: objectFlow-dependent sensitive values; restrict logging and mask card data.
orderHistory[]: arrayItems contain time, action and newCode; history can be empty or delayed.

HTTP responses

200: Current order state · DepositStatusResponse
401: Missing or invalid Bearer token.
403: Valid key without access to this resource.
404: Order not found · BusinessError
500: Internal server error.

operationId: getDepositStatusByPayStarIdUse the PayStar order ID returned by the create operation.

GET/api/v1/integration/deposit-order/{externalTransactionId}/status-by-external-transaction-idDOCUMENTED

Get deposit status by merchant ID

Request & response contract1 path parameter · 5 responses

Request

path

externalTransactionIdrequired: stringOriginal merchant transaction ID.

200 · DepositStatusResponse

application/json

externalIdrequired: stringPayStar order ID.
orderStatusrequired: enumInit, Created, Processing, Success or Failed.
amount: numberOrder amount.
externalParams: objectFlow-dependent sensitive values; restrict logging and mask card data.
orderHistory[]: arrayItems contain time, action and newCode; history can be empty or delayed.

HTTP responses

200: Current order state · DepositStatusResponse
401: Missing or invalid Bearer token.
403: Valid key without access to this resource.
404: Order not found · BusinessError
500: Internal server error.

operationId: getDepositStatusByMerchantIdUse this check before repeating an uncertain create request.

Balance · secure.paystar.uk

GET/api/v1/balance/merchant?currency={currency}DOCUMENTED

Get merchant and pipeline balance

Returns balance information for the permitted merchant profile and requested currency.

Request & response contract1 parameter · 5 responses

Request

query

currencyrequired: string · alpha-3Currency requested for the merchant and pipeline balance.

200 · Balance

application/json

currencyrequired: stringResponse currency.
merchantBalancerequired: numberMerchant balance.
merchantOverdraftrequired: numberMerchant overdraft.
pipelineBalancerequired: numberPipeline balance.
pipelineAvailableBalancerequired: numberCurrently available pipeline balance.
pipelineProcessingOrdersDepositrequired: numberDeposits still processing.
pipelineProcessingOrdersWithdrawalsrequired: numberPayouts still processing.

HTTP responses

200: Balance data · Balance
400: Missing or malformed currency · BusinessError
401: Missing or invalid Bearer token.
403: Valid key without balance access.

operationId: getMerchantBalanceCurrency is required and uses an alpha-3 code.

Payouts · secure.paystar.uk

POST/api/v1/integration/withdrawal-order/DOCUMENTED

Create an H2H payout

Creates a payout for merchant profiles with payout capability enabled. Required fields and routes remain profile-specific.

Request & response contract1 body schema · 8 responses

Request · PayoutRequest

application/json

amountrequired: numberAmount in major currency units.
currencyrequired: string · alpha-3Payout currency.
externalTransactionIdrequired: stringUnique merchant transaction ID.
callbackUrl: string · URIOptional asynchronous status callback URL.
additionalFields[]flow-specific: key/value objectsRequired keys depend on the merchant and payout route; confirm them with PayStar.

200 · PayoutCreateResponse

application/json

externalIdrequired: stringPayStar order ID.
orderStatusrequired: enumCreated.

HTTP responses

200: Payout accepted · PayoutCreateResponse
400: Request validation failed · BusinessError
401: Missing or invalid payout Bearer token.
403: Valid key without this payout capability.
415: Unsupported media type · ProblemDetails415
422: Request cannot be processed for the configured profile · BusinessError
423: No active route for the request, currency or configured limits · BusinessError
500: Internal error · BusinessError

operationId: createPayoutRequired payout fields remain route-specific.

Payout status · secure.paystar.uk

GET/api/v1/integration/withdrawal-order/{externalId}/statusDOCUMENTED

Get payout status by PayStar ID

Request & response contract1 path parameter · 5 responses

Request

path

externalIdrequired: stringPayStar order ID returned by the create operation.

200 · PayoutStatusResponse

application/json

externalIdrequired: stringPayStar order ID.
orderStatusrequired: enumCreated, Processing, Success or Failed.
amount: numberOrder amount.
externalParams: objectFlow-dependent values; restrict logging and mask card data.
orderHistory[]: arrayItems contain time, action and newCode; history can be empty or delayed.

HTTP responses

200: Current order state · PayoutStatusResponse
401: Missing or invalid Bearer token.
403: Valid key without access to this resource.
404: Order not found · BusinessError
500: Internal server error.

operationId: getPayoutStatusByPayStarIdUse the PayStar order ID returned by the create operation.

GET/api/v1/integration/withdrawal-order/{externalTransactionId}/status-by-external-transaction-idDOCUMENTED

Get payout status by merchant ID

Request & response contract1 path parameter · 5 responses

Request

path

externalTransactionIdrequired: stringOriginal merchant transaction ID.

200 · PayoutStatusResponse

application/json

externalIdrequired: stringPayStar order ID.
orderStatusrequired: enumCreated, Processing, Success or Failed.
amount: numberOrder amount.
externalParams: objectFlow-dependent values; restrict logging and mask card data.
orderHistory[]: arrayItems contain time, action and newCode; history can be empty or delayed.

HTTP responses

200: Current order state · PayoutStatusResponse
401: Missing or invalid Bearer token.
403: Valid key without access to this resource.
404: Order not found · BusinessError
500: Internal server error.

operationId: getPayoutStatusByMerchantIdUse the merchant ID to reconcile an uncertain request.

CONTRACT BOUNDARY

Separate the public contract from merchant configuration.

Public baseline

Operations, schemas, authentication pattern, statuses and response models documented on this page.

Merchant profile

Enabled capabilities, hosts, currencies, limits, credentials and required additional fields.

Provider context

Route availability, onboarding, payment experience and provider-specific operating constraints.

Confirm before implementation

PayStar provides the integration profile separately so the team can apply the public contract to the exact merchant scenario.

Currency referenceAlpha-3 catalog; route support still requires pipeline verification.Download JSON ↓ Bank-name catalogIncomplete geographic catalog; do not validate exclusively against it.Download JSON ↓

MACHINE-READABLE

Use the same source in code, tools and AI agents.

Download the credential-free baseline for editors, code generation and integration tooling. Merchant configuration is provided separately.

YAML

OpenAPI 3.1Best for editors, gateways and code generation

↓ JSON

OpenAPI 3.1Structured API contract for automated tooling

↓ JSON

Postman collectionSeven requests organised by operation

↓ JSON

Postman environmentCredential-free variable template

↓ JSON

Reference dictionariesCurrency and integration reference catalog

↓ JSON

Bank-name catalogIncomplete geographic reference catalog

↓

6 public filesContract 2026-08-25.9Published 25 Aug 2026Credential-free templates

Build payment flows from a contract you can read—and machines can use.

Choose what you need to build.

From credentials to a safe first payment.

Choose the flow

Configure access

Create the operation

Handle uncertainty

One header. Pipeline-specific access.

One core API. Two specialized deposit hosts.

init.paystar.uk

token.paystar.uk

Keep both identifiers and check before repeating.

Build your own internal payment dashboard.

Use dashboard-ready API methods

Start from frontend building blocks

Fit the dashboard to your operation

Seven operations in the current contract.

Deposits

Create a deposit

Request body

200 · Flow-specific response

HTTP responses

Deposit status

Get deposit status by PayStar ID

Request

200 · DepositStatusResponse

HTTP responses

Get deposit status by merchant ID

Request

200 · DepositStatusResponse

HTTP responses

Balance · secure.paystar.uk

Get merchant and pipeline balance

Request

200 · Balance

HTTP responses

Payouts · secure.paystar.uk

Create an H2H payout

Request · PayoutRequest

200 · PayoutCreateResponse

HTTP responses

Payout status · secure.paystar.uk

Get payout status by PayStar ID

Request

200 · PayoutStatusResponse

HTTP responses

Get payout status by merchant ID

Request

200 · PayoutStatusResponse

HTTP responses

Separate the public contract from merchant configuration.

Use the same source in code, tools and AI agents.

Confirm the profile before production traffic.