Reference

get/api/v1/events

List events across all payments

The polling equivalent of your webhook endpoint. Scoped to the key's environment.

200

A page of events.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

422

validation_error.

429

Rate limited. Retry after the interval in the Retry-After header.

get/api/v1/payments/{id}/events

List a payment's timeline

200

Events, oldest first.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found.

429

Rate limited. Retry after the interval in the Retry-After header.

get/api/v1/insights

List insights

The ranked findings from the dashboard's Insights page, for the key's environment: approval gaps between providers, declines left without a retry, fees above your pricing rules, refund and dispute trends, provider health, routing advice. Each carries an estimate of the money involved (over payments already seen, in your reporting currency), its evidence and the dashboard path where it is fixed. Dismissed and snoozed findings are left out. Computed on request and rate limited to 20 calls a minute.

200

The findings, most money first.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

422

validation_error (an unknown range).

429

Rate limited. Retry after the interval in the Retry-After header.

get/api/v1/merchants

List your sub-merchants

200

The partner's merchants.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

not_a_partner.

429

Rate limited. Retry after the interval in the Retry-After header.

post/api/v1/merchants

Provision a sub-merchant

White-label partners only. Requires a live key and the partner flag on your workspace, both enforced server-side. country is checked against Payshen's country gate: a country Payshen does not onboard is refused with country_blocked; a country under review is provisioned, and the merchant's going live and provider applications wait until Payshen clears the workspace.

201

The sub-merchant workspace was created and its owner invited. account_review is approved when the partner is approved, so the merchant can go live; otherwise the merchant sends its account for review from Get live.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

not_a_partner, or live_key_required when called with a test key.

409

already_invited.

422

validation_error, or country_blocked when Payshen does not onboard merchants registered in the country sent.

429

merchant_limit - the partner's allowance is exhausted.

get/api/v1/openapi.jsonno auth

This document

The machine-readable contract, unauthenticated so it can be read and imported before you have an account.

200

An OpenAPI 3.1 document.

get/api/v1/payments

List payments

Newest first, cursor paginated on payment id. Scoped to the key's environment.

200

A page of payments.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

422

validation_error - an unknown status filter.

429

Rate limited. Retry after the interval in the Retry-After header.

post/api/v1/payments

Create a payment

Routes the payment across your active connections. A second connection is tried only after a soft decline or a technical error before anything was executed (per routing mode), never after a timeout or an unknown result, which answers UNKNOWN. With return_url the response is a redirect instead of an outcome.

201

Created. Either an outcome, or a redirect to complete it.

400

idempotency_key_required (a live key sent no Idempotency-Key), invalid_idempotency_key or invalid_json.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

409

idempotency_in_progress, or routing_failed when no connection can take it. With debug: true a routing_failed error also carries error.excluded, the same list as routing.excluded.

413

payload_too_large - the body exceeds 16 KB.

422

validation_error, or idempotency_key_reuse for a reused key with a different body. no_eligible_method - the hosted flow was asked for methods no active connection can take; the message names each one and why, so the checkout is never opened with nothing to offer. return_url_required - ui: "embedded" was sent without return_url. no_eligible_connection - ui: "embedded" and no connection can take this payment right now; the message says why. pan_not_accepted - a field (a reference, metadata, a description) holds a card number; Payshen never accepts card data. return_url_not_allowed - with a live key, return_url or cancel_url points at a host that is not on the workspace's allowed return hosts (set in the dashboard under Developers; off unless the merchant turns it on).

429

Rate limited. Retry after the interval in the Retry-After header.

500

internal_error - nothing was sent to a provider; safe to retry with the same Idempotency-Key. payment_result_unknown - a provider may have received the payment and its result could not be recorded yet; the error carries request_id. Do not retry with a new Idempotency-Key. A retry with the same key never charges again: it answers 409 while the first request's claim is fresh (15 minutes), then the payment as Payshen recorded it (often UNKNOWN). A daily job records such a payment even if nobody retries.

get/api/v1/payments/{id}

Retrieve a payment

200

The payment.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found. Also returned for a payment belonging to another workspace or environment.

429

Rate limited. Retry after the interval in the Retry-After header.

post/api/v1/payments/{id}/capture

Capture an authorization

Full or partial. Only a payment created with capture_method: manual can be captured.

200

Captured (CAPTURED). Or PENDING when the provider accepted the capture and reports its result later (Adyen, Solidgate): nothing is captured yet, and payment.captured follows when the provider confirms it.

400

idempotency_key_required - a ps_live_ key sent no Idempotency-Key (required in production, optional in sandbox); invalid_idempotency_key - the Idempotency-Key is not 8-200 printable ASCII characters.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found.

409

not_capturable - the payment is not AUTHORIZED (already captured, voided, or a capture or void is in flight or unknown); capture_conflict - another capture or void took it first; no_provider_ref - there is no provider reference to capture; idempotency_in_progress - a request with this Idempotency-Key is still being processed. simulated_payment - a live payment a simulation answered (no provider holds it, no money moved): on a production deployment a simulation never answers an operation on a live payment, so nothing was sent and nothing changed.

422

validation_error or invalid_amount - the amount is not a positive integer or exceeds the authorization; idempotency_key_reuse - the key was used with a different amount.

429

Rate limited. Retry after the interval in the Retry-After header.

500

state_unconfirmed - the provider was asked and its answer could not be recorded (the message says whether it confirmed, refused or did not answer); state_conflict - the provider confirmed the capture and the payment had meanwhile moved. Do not retry: the same Idempotency-Key replays this answer, and the payment is checked with the provider by Payshen operations.

501

unsupported - the payment's provider cannot capture.

502

psp_error - the provider refused the capture (the message is the provider's): nothing was captured and the payment is AUTHORIZED again; the Idempotency-Key is released, so a new attempt is safe. capture_result_unknown - the provider did not answer and may have captured: the payment is UNKNOWN. Do NOT retry; the same Idempotency-Key replays this answer, and Payshen settles the payment from the provider's record.

503

provider_unavailable - the payment is held by a real provider that this deployment cannot reach (the connection's credentials are missing, or live provider access is off), so the capture was NOT sent and nothing changed. Payshen never lets a simulation answer for a real provider's payment. Retry once the connection reaches its provider; the Idempotency-Key is released, so a new attempt is safe.

post/api/v1/payments/{id}/complete

Complete an embedded payment after customer authentication

After the customer's 3-D Secure challenge (a confirm that answered REQUIRES_ACTION). A BROWSER call, authenticated like confirm by the session client_secret. It takes no payment method and never charges: Payshen asks the provider, with your connection's own credentials, what became of the payment and applies the provider's answer - CAPTURED, AUTHORIZED (manual capture), DECLINED (the customer failed the challenge, decline_reason e.g. payment_intent_authentication_failure) or CANCELLED - after checking its amount and currency against the payment. Still REQUIRES_ACTION with a fresh next_action while the customer has not finished. Idempotent and safe to repeat: the provider's own webhook may settle the payment first, and whichever arrives second changes nothing. The merchant is told the outcome once, by payment.captured, payment.authorized, payment.declined or payment.cancelled.

200

The payment's authoritative state, as the provider reported it.

404

not_found - no payment matches this id and client_secret.

422

validation_error - the body is malformed. pan_not_accepted - card data was sent. not_confirmable - this payment was not created for embedded confirmation.

429

rate_limited - too many completion attempts.

post/api/v1/payments/{id}/confirm

Confirm an embedded payment

The embedded Checkout SDK's confirm. A BROWSER call, authenticated by the session client_secret from an embedded create response (ui: "embedded"), NOT the ps_live_ API key - which must never ship to the browser. It accepts ONLY a provider-issued token via payment_method; raw card data (PAN, CVV, expiry) is refused with pan_not_accepted, because Payshen never receives or transmits card data. Idempotent: a retry after a lost response returns the authoritative payment state without charging again. The charge is bound to the provider chosen at session-init and never fails over to another provider. When the card issuer requires Strong Customer Authentication (3-D Secure), the answer is REQUIRES_ACTION with next_action (type: AUTHENTICATE): nothing is charged yet, it is not a decline, and the payment is never sent to another provider. Complete the challenge, then call POST /v1/payments/{id}/complete. Calling confirm again instead is equivalent: it never charges a second time, it applies the provider's outcome or hands back what the customer still needs. A challenge nobody finishes is cancelled at the provider after an hour and the payment ends CANCELLED (payment.cancelled, reason authentication_abandoned).

200

The payment's authoritative state after the charge, or recovered on an idempotent retry (Idempotent-Replay: true). REQUIRES_ACTION with next_action when the customer must authenticate first.

404

not_found - no payment matches this id and client_secret (a wrong id and a wrong secret answer identically; the endpoint is not an oracle).

409

provider_unavailable - the provider this payment was bound to at session-init is no longer available, and it was NOT re-routed. Create a new payment.

410

session_expired - this payment session has expired.

422

pan_not_accepted - raw card data was sent; send only the provider token. validation_error - the body is malformed. not_confirmable - this payment was not created for embedded confirmation.

429

rate_limited - too many confirm attempts.

post/api/v1/payments/{id}/refunds

Refund a captured or settled payment

Full or partial, from a captured, partially refunded or settled payment (a settled payment is refunded at the provider like any other; it moves to PARTIALLY_REFUNDED or REFUNDED once the provider confirms). The amount is clamped to the refundable balance, and concurrent full refunds cannot both succeed. Send an Idempotency-Key: it is REQUIRED for a ps_live_ key (a keyless live refund is refused 400 idempotency_key_required) and optional in sandbox. On this endpoint the key also names the refund itself, so a request repeated under the same key is answered from that refund and never refunds twice - which is exactly why a live refund must carry one: without it, a network retry is a second refund. For 24 hours the stored response is replayed as it was sent; after that, the same key on the same payment is answered from the refund's current record (its final result once it is settled). A refund the provider has not confirmed yet is counted in refund_pending_amount, not in refunded_amount, and is settled from the provider's own record: a refund still pending is never answered as refunded.

200

Refunded: the provider confirmed it.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found.

409

refund_pending - this refund, or one holding the rest of the balance, is not confirmed yet: the provider accepted it and is still processing it, or its answer is still being settled. It is not refunded, and its amount is in refund_pending_amount. Do not retry with a new key; the same Idempotency-Key answers its final result once it is settled. Also not_refundable and refund_conflict. simulated_payment - a live payment a simulation answered (no provider holds it, no money moved): on a production deployment a simulation never answers an operation on a live payment, so nothing was sent and nothing changed.

422

validation_error or invalid_amount - nothing refundable, or an invalid amount; idempotency_key_reuse - the key was used with a different amount.

429

Rate limited. Retry after the interval in the Retry-After header.

500

state_unconfirmed - the provider confirmed the refund, and either recording it failed or the payment's status could not be updated after it (the message says which). Do not retry: the same Idempotency-Key replays this answer for 24 hours, and after that is answered from the refund's record.

502

psp_error - the provider refused the refund: nothing was refunded and the amount is refundable again. The same Idempotency-Key answers the same refusal; a retry with a NEW Idempotency-Key is a new refund and is safe. refund_result_unknown - the provider did not answer and may have refunded: the amount stays in refund_pending_amount. Do NOT retry, with any key; Payshen settles it from the provider's record and the payment shows the result.

503

provider_unavailable - the payment is held by a real provider that this deployment cannot reach (the connection's credentials are missing, or live provider access is off), so the refund was NOT sent and nothing changed. Payshen never lets a simulation answer for a real provider's payment. Retry once the connection reaches its provider; the Idempotency-Key is released, so a new attempt is safe.

post/api/v1/payments/{id}/void

Void an authorization

Releases an uncaptured authorization. A captured payment must be refunded instead.

200

Voided (CANCELLED). Or PENDING when the provider accepted the void and reports its result later: payment.voided follows when the provider confirms it.

400

idempotency_key_required - a ps_live_ key sent no Idempotency-Key (required in production, optional in sandbox); invalid_idempotency_key - the Idempotency-Key is not 8-200 printable ASCII characters.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found.

409

not_voidable - the payment is not AUTHORIZED (already captured, voided, or a capture or void is in flight or unknown); void_conflict - another capture or void took it first; no_provider_ref - there is no provider reference to void; idempotency_in_progress - a request with this Idempotency-Key is still being processed. simulated_payment - a live payment a simulation answered (no provider holds it, no money moved): on a production deployment a simulation never answers an operation on a live payment, so nothing was sent and nothing changed.

429

Rate limited. Retry after the interval in the Retry-After header.

500

state_unconfirmed - the provider was asked and its answer could not be recorded (the message says whether it confirmed, refused or did not answer); state_conflict - the provider confirmed the void and the payment had meanwhile moved. Do not retry: the same Idempotency-Key replays this answer, and the payment is checked with the provider by Payshen operations.

501

unsupported - the payment's provider cannot void.

502

psp_error - the provider refused the void (the message is the provider's): the payment is AUTHORIZED again; the Idempotency-Key is released, so a new attempt is safe. void_result_unknown - the provider did not answer and may have voided: the payment is UNKNOWN. Do NOT retry; the same Idempotency-Key replays this answer, and Payshen settles the payment from the provider's record.

503

provider_unavailable - the payment is held by a real provider that this deployment cannot reach (the connection's credentials are missing, or live provider access is off), so the void was NOT sent and nothing changed. Payshen never lets a simulation answer for a real provider's payment. Retry once the connection reaches its provider; the Idempotency-Key is released, so a new attempt is safe.

get/api/v1/provider-webhooks/{connectionId}no auth

Inbound provider payment callback (GET)

The same callback, for rails that send it as a GET with every parameter in the query string (Verotel's postbacks). Handled exactly as the POST, with an empty body; the query string reaches the connection's adapter, which verifies it. Called by the provider, not by you.

200

Accepted and stored, answered as the rail expects (Verotel: plain OK).

401

The signature does not hold. An unknown connection, and a rail that takes no callbacks, answer identically by design.

413

Query string over 64 KB.

429

Rate limited.

post/api/v1/provider-webhooks/{connectionId}no auth

Inbound provider payment callback

Called by the payment provider holding one of your provider connections, not by you. The provider signs it with the secret issued for that connection and the connection's adapter verifies it; the event is stored before it is interpreted, and it can only move the payment that connection holds. A redelivery of the same event id is answered 200 and changes nothing. Documented so integrators understand the inbound path, not so they call it.

200

Accepted and stored. result says what it did: apply, ignored or review; duplicate marks a delivery already held. A rail that expects its own acknowledgement gets exactly that instead of JSON (Verotel OK, Vendo's XML, emerchantpay's notification echo, Praxis's signed reply), for a repeat as well.

401

The signature does not hold. An unknown connection, and a rail that takes no callbacks, answer identically by design.

413

Body or query string over 64 KB.

429

Rate limited.

post/api/v1/psp-webhooks/{pspId}no auth

Inbound provider webhook

Called by a payment provider, not by you. Requires an HMAC signature issued to that provider. Documented so integrators understand the inbound path, not so they call it.

200

Accepted, stored and applied.

401

Missing or invalid signature. An unknown provider id answers identically, by design.

429

Rate limited.

get/api/v1/suggestions

List suggestions

The routing engine's suggestions for the key's environment, newest first: the same ones the dashboard shows as cards. A suggestion carries a monthly money figure (value) only when the lower end of its 95% interval is above zero; otherwise value is null and value_reason says why (a worth_testing suggestion is one only a routing test can measure). Its evidence is frozen when it is made, with a hash, and once accepted realized says what it actually did. Recomputed at most hourly: listen for suggestion.created rather than polling. Payshen never holds or moves money; nothing here is a balance. API keys carry no narrower scope: any key of the workspace may read and decide suggestions in its own environment. Rate limited to 30 calls a minute.

200

A page of suggestions.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

422

validation_error (an unknown state, a limit out of range, or a cursor that is not an id).

429

Rate limited. Retry after the interval in the Retry-After header.

get/api/v1/suggestions/{id}

Retrieve a suggestion

One suggestion of this workspace in the key's environment. Rate limited to 60 calls a minute.

200

The suggestion.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found - no such suggestion in this workspace and the key's environment.

429

Rate limited. Retry after the interval in the Retry-After header.

post/api/v1/suggestions/{id}/accept

Accept a suggestion

Applies it the safe way, exactly as the dashboard's Accept does; live traffic is never repointed in one call. A routing suggestion starts a routing test that sends 10% of the segment to the suggested connection for up to 14 days on the published rule that carries it (the engine promotes or stops the test on its own), or, when no published rule carries the segment, writes a draft rule a person publishes. A pricing suggestion writes the learned rates as draft fee rules to confirm. result.outcome says which. Requires an Idempotency-Key, in sandbox too: a lost answer retried under the same key replays it and never starts a second test. Rate limited to 30 calls a minute.

200

Accepted. data is the suggestion, now accepted; result what was applied.

400

idempotency_key_required - no Idempotency-Key was sent (required on this call with any key); invalid_idempotency_key - it is not 8-200 printable ASCII characters.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found - no such suggestion in this workspace and the key's environment.

409

suggestion_not_open - it was already accepted, rejected, superseded or expired; suggestion_connection_gone - a connection it names is no longer active; nothing_to_apply - its evidence no longer yields a change to apply; idempotency_in_progress - a request with this Idempotency-Key is still being processed.

422

idempotency_key_reuse - this Idempotency-Key was used with a different request.

429

Rate limited. Retry after the interval in the Retry-After header.

post/api/v1/suggestions/{id}/reject

Reject a suggestion

Declines it, with an optional reason kept with it. It does not come back unless the evidence behind it materially changes (then it is a new suggestion). Rate limited to 30 calls a minute.

200

Rejected. data is the suggestion, now rejected.

400

invalid_json - the body is not JSON; invalid_idempotency_key - the Idempotency-Key is not 8-200 printable ASCII characters.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found - no such suggestion in this workspace and the key's environment.

409

suggestion_not_open - it was already accepted, rejected, superseded or expired (read it again for its state); idempotency_in_progress - a request with this Idempotency-Key is still being processed.

413

payload_too_large.

422

validation_error - a field other than reason, or a reason over 500 characters; idempotency_key_reuse - this Idempotency-Key was used with a different body.

429

Rate limited. Retry after the interval in the Retry-After header.

post/api/v1/suggestions/{id}/snooze

Snooze a suggestion

Hides it for 7 days, as the dashboard's Ignore does. It comes back as open on its own if the evidence still holds, and is expired if it no longer does. Rate limited to 30 calls a minute.

200

Snoozed. data is the suggestion, now snoozed, with snoozed_until.

400

invalid_idempotency_key - the Idempotency-Key is not 8-200 printable ASCII characters.

401

Missing, malformed, revoked, expired or unknown API key. An expired key's message gives the date it expired.

403

tenant_suspended: the workspace is suspended. account_not_approved: a live key, or a live payment, before Payshen has reviewed and approved the account; test keys are never refused for it. insufficient_scope: the key is restricted and lacks the scope this operation names under security.

404

not_found - no such suggestion in this workspace and the key's environment.

409

suggestion_not_open - it was already accepted, rejected, superseded or expired (read it again for its state); idempotency_in_progress - a request with this Idempotency-Key is still being processed.

422

idempotency_key_reuse - this Idempotency-Key was used with a different body.

429

Rate limited. Retry after the interval in the Retry-After header.