Create Order Error Codes - Surfboard Payments

Overview

This reference lists the error codes returned by the create order and initiate payment flows. Most create order calls also initiate a payment in the same request (via controlFunctions.initiatePaymentsOptions), so errors from either step can surface on the same endpoint.

See the Create an Order guide for request/response shape and the Payment Lifecycle guide for status semantics.

Error Response Shape

Errors return a status of ERROR along with an error code and message. Example:

{
  "status": "ERROR",
  "errorCode": "OR_0042",
  "message": "Terminal not found"
}

Error code prefixes indicate the source:

Prefix	Source
`OR_`	Orders service (validation, order state, terminal/store checks)
`PS_`	Payment service (payment initiation, refund handling)
`GC_`	Gift card service
`SP_`	Service provider

Messages may contain placeholders like <id>, <amount>, <type>, or <status> — the API substitutes the real value at runtime.

Create Order Errors

Errors thrown while validating and creating the order.

Validation and Schema

Code	Message	Notes
`OR_0015`	Order validation failed	Wraps the raw schema validator error. Check required fields and types.
`OR_0022`	Invalid order line item. Missing item price	At least one line is missing `amount.regular` or `amount.total`.
`OR_0023`	Invalid item price for item id `[<id>]`, `<errorMsg>`	Price on the named line item failed validation.
`OR_0037`	Invalid total order price	`totalOrderAmount` does not reconcile with the order lines and adjustments.
`OR_0049`	(empty message)	Reserved / edge-case validation failure.

Merchant, Store, and Terminal

Code	Message	Notes
`PS_0059`	No Merchant found with the given Merchant ID	Merchant ID in the URL does not exist.
`OR_0001`	No Merchant Details found for the Merchant ID	Merchant exists but is missing required configuration.
`OR_0002`	Order creation is not allowed for this merchant type `<type>`	The merchant type does not permit direct order creation.
`OR_0028`	Store is not in an active state	Activate the store before creating orders.
`OR_0042`	Terminal not found	`terminal$id` does not match any terminal.
`OR_0007`	The Terminal ID is not associated with this merchant	Terminal exists but belongs to another merchant.
`OR_0006`	The terminal is in deregistered state	Re-register the terminal before use.
`OR_0050`	Order cannot be created, terminal is in an inactive state	Terminal is registered but not active.

Currency

Code	Message	Notes
`OR_0003`	Currency Code is not present for this merchant	Merchant has no configured currency — contact your onboarding contact.
`OR_0004`	The currency code is not associated with this merchant	Use a currency enabled on the merchant.
`OR_0005`	Currency is mandatory as the merchant has more than one currency	Multi-currency merchants must set `amount.currency` explicitly.
`OR_0048`	Currencies should be same in order lines	All line items must use the same currency.

Payment Method Locking

Code	Message	Notes
`OR_0031`	No Payment Method found with the given payment method id	The `lockToPaymentMethods` id is unknown.
`OR_0032`	Lock to payment method is not allowed for this merchant	The merchant does not have the lock-to-method feature enabled.
`SP_0001`	Service provider IDs `[<ids>]` not associated with this merchant	One or more service provider IDs are invalid for this merchant.

Refunds (on create order)

Refunds are created as new orders with negative quantities and a purchaseOrderId on each line. These errors surface during that validation.

Code	Message	Notes
`OR_0010`	No purchase order found with ID: `<id>`	`purchaseOrderId` does not match any completed order.
`OR_0035`	Cannot refund from purchase order that is not completed. Status: `<status>`	Only completed orders can be refunded.
`OR_0039`	Cannot refund more than the original order amount	Refund amount exceeds the remaining refundable balance.
`PS_0043`	Invalid order line item. Missing purchase order id for refund line	Every refund line must carry `purchaseOrderId`.
`PS_0010`	Unlinked refunds are only supported for CARD payment methods	Unlinked refunds cannot be issued on non-card methods.
`GC_0004`	Gift card refunds are not supported	Gift card payments cannot be refunded via this flow.

Initiate Payment Errors

When the create order request also initiates a payment, these errors can be returned from the same call. They also surface when you call initiate payment directly.

Order State

Code	Message	Notes
`PS_0057`	Order not found	The order referenced by the payment request does not exist.
`PS_0062`	Order already paid	The order has already been fully paid.
`OR_0046`	Order cancelled	The order is in a cancelled state and cannot accept payments.
`PS_0019`	Cannot pay `[<amount>]`, amount payable `[<pendingFromOrder>]`	Requested amount exceeds the outstanding balance on the order.

Amount and Validation

Code	Message	Notes
`PS_0008`	Payment amount cannot be less than 0.01	Send a positive amount in the smallest currency unit.
`PS_0033`	`empty payload - payment initiation rejected` or `Initiate payment validation failed with error <err>`	Payload is missing or failed schema validation.
`PS_0025`	Payment initiation failed: `<error.message>`	Wraps unexpected exceptions from downstream services. See the Handling `PS_0025` section below.

Terminal, Merchant, and Store

Code	Message	Notes
`OR_0042`	Terminal not found	Terminal ID unknown.
`OR_0006`	Terminal `[<terminalId>]` is not active	Re-activate the terminal.
`PS_0013`	No linked terminals found / Terminal not linked to merchant / Terminal not linked to store	Link the terminal to the merchant/store before initiating.
`PS_0059`	Merchant not found	Merchant ID unknown.
`PS_0058`	Store not found	Store ID unknown.

Refund-Specific

Code	Message	Notes
`OR_0053`	Mixed linked and unlinked refund lines are not supported	Split mixed refunds into separate requests.
`PS_0104`	Multiple `purchasePaymentId` values found in refund lines / This purchase order has partial payments	Specify which payment to refund using `purchasePaymentId`.
`PS_0017`	No valid purchase payments found for the specified payment IDs / Purchase payment not found	The `purchasePaymentId` does not match a refundable payment.
`PS_0010`	Payment method `<method>` not supported for returns / No payments with matching payment method found / Unlinked refunds are not enabled for this merchant / Unlinked refunds are only supported for `[<methods>]` / Purchase payment does not support CARD_NP refund	Refund is not allowed for the given method or configuration.
`PS_0032`	Cannot refund amount `<amount>` (not enough remaining / not enough in card / not enough in other methods / exceeds max for `<method>`)	Refund would exceed the available balance.
`PS_0068`	Cannot refund amount `<amount>` as there are no card payments in the purchase order	No card payments are available to refund against.
`PS_0096`	Cannot initiate refund as there are no payments of type `<method>`	No payments of the requested method exist on the order.
`PS_0034`	Message is missing	Card-not-present refund is missing the `message` field.
`PS_0044`	Cannot refund amount `<amount>` as message `<msg>` is not allowed / Purchase payment id is required, more than one purchase matches the criteria	Card-not-present refund message/ID disambiguation required.

Combined Flow Errors

When the create order call also initiates a payment, downstream payment failures (processor, network, 3DS) are reported through the payment object rather than as a top-level error:

{
  "status": "ERROR",
  "errorCode": "<first processor code>",
  "message": "Payment failed",
  "payment": {
    "error": {
      "errorMessage": "...",
      "errorCode": ["..."],
      "psErrorCodes": ["..."]
    }
  }
}

Merge payment.error.errorCode and payment.error.psErrorCodes to get the full list of processor codes for logging and support.

Handling `PS_0025` — Terminal Not Connected

A common PS_0025 variant is:

PS_0025: Terminal is not connected to server so unable to send transactions

Re-run the terminal configure call and retry the payment. This can be done transparently — no user interaction is required. It is most common on SoftPOS, where the consumer device can drop its server session between transactions.

See Interapp Integration for the full recovery pattern.

Handling Patterns

Retryable vs. terminal. Treat PS_0025, PS_0013, and network-class errors as retryable after a configure/refresh. Treat OR_* validation errors as terminal — fix the payload and resubmit.
User-facing vs. internal. OR_0022, OR_0023, OR_0037, OR_0048 are actionable by the merchant integration team. PS_0025, PS_0059, PS_0058 usually mean misconfiguration — surface them to an internal log rather than to the cardholder.
Refund edge cases. When handling PS_0104, always re-issue the refund with an explicit purchasePaymentId — there is no sensible default when multiple payments exist on one order.
Log the full response. Capture errorCode, message, and payment.error.* together. Support tickets without the error code are very hard to trace.

Reference

Create an Order
Payment Lifecycle
Interapp Integration — PS_0025 recovery
Create Order API
Payments API

Other Guides

in-store

Tap to Pay on iPhone SDK

Accept contactless payments directly on iPhone. Complete integration guide for Surfboard's iOS SoftPOS SDK -- from setup to production.

in-store

Android SoftPOS SDK

Turn Android devices into payment terminals with the Surfboard Android SoftPOS SDK. Complete integration guide from setup to production.

in-store

CheckoutX SoftPOS

Accept in-person payments on smartphones and tablets by pairing the CheckoutX app with your own POS app — a dual-app setup that requires no SDK integration.

in-store

EMV Terminal Integration

Integrate traditional card-present terminals through Surfboard's unified API. From account setup to live payments in one guide.

Overview

Error Response Shape

Create Order Errors

Validation and Schema

Merchant, Store, and Terminal

Currency

Payment Method Locking

Refunds (on create order)

Initiate Payment Errors

Order State

Amount and Validation

Terminal, Merchant, and Store

Refund-Specific

Combined Flow Errors

Handling PS_0025 — Terminal Not Connected

Handling Patterns

Reference

Other Guides

Ready to get started?

Handling `PS_0025` — Terminal Not Connected