Cresora Commerce Documentation

Process card sales, refunds, voids, authorizations and captures. Batch close operations for settlement timing.

🔬Preview stream (/api/v1-preview)

These endpoints are reserved or behind feature flags and may change before promotion to stable. Operations badged “Reserved — not yet available”return 404 (or 501) today; do not build against them yet. This spec is generated from the canonical contract — see the stable /api/v1 reference for production-ready endpoints.

List transactions

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk__

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

Obtain via Partner Portal → Settings → API keys. Keys are only shown in full at creation/rotation time — Cresora does not retain the full value in retrievable form. Rotate any key that may have been exposed via logs, client code, or source control.

In: header

Query Parameters

cursor?string

Opaque pagination cursor from previous response. Do not parse.

Lengthlength <= 256

page_size?integer

Items per page (1–100).

Default25

Range1 <= value <= 100

merchant_id?string

Formatuuid

q?string

Free-text search: case-insensitive substring on gateway_transaction_id, OR exact transaction-id match when the value parses as a UUID. Identical semantics on the list, summary, and export operations.

Lengthlength <= 200

state?string

Transaction lifecycle state. Maps to domain TransactionState. Aligned with implementation at T-3.10 (3DS2 authentication).

INITIATED — created, not yet submitted to gateway
THREE_DS_PENDING — a 3DS challenge is outstanding, waiting for the customer to complete. The three_ds projection carries challenge_url; the customer browser is redirected there and the ISV then calls POST /transactions/{id}/three-ds/complete to resolve the transaction. 15-minute TTL; on timeout / abandonment the server-side sweep promotes the row to THREE_DS_FAILED with three_ds_failure_reason = callback_timeout. Also listen for the transaction.three_ds_completed webhook for an eventually-consistent ack path. No current POST /transactions create path issues a step-up — the saved-card SALE charges an already-authenticated vault credential; this state and the completion endpoint are retained for reserved card-authentication flows.
THREE_DS_FAILED — terminal 3DS authentication failure. The three_ds_failure_reason field carries one of: challenge_failed, challenge_abandoned, callback_timeout, signature_invalid, unsupported_card, issuer_declined. The transaction is not authorized — no funds are held. Distinct from the generic FAILED state so chargeback / retry logic can dispatch on the 3DS-specific cause.
AUTHORIZED — funds held, not yet captured
CAPTURED — capture submitted, awaiting settlement
SUBMITTED — ACH entry accepted into the ODFI origination batch (T-4.2). Distinct from CAPTURED because card-rail void / refund / auth-reverse rules don't map onto ACH semantics. Clearing happens 1-3 banking days later via the settlement webhook (SUBMITTED → SETTLED on cleared, or → FAILED with an R-code on NACHA return).
SETTLED — funds moved into the merchant batch (end of day)
VOIDED — cancelled pre-settlement
REFUNDED — fully refunded post-settlement (cumulative refund equals original amount)
PARTIALLY_REFUNDED — one or more partial refunds issued, remaining refundable capacity > 0. Re-entrant: additional partial refunds are accepted until cumulative == original amount, at which point the state advances to REFUNDED.
REVERSED — authorization released (card) or NACHA reversal (ACH)
FAILED — terminal failure state; see decline_code for cause (covers both 3DS-specific and non-3DS failures)
DISPUTED — chargeback opened against a SETTLED transaction (Sprint 7 dispute lifecycle); evidence-gathering window open.
CHARGED_BACK — chargeback lost / resolved against the merchant.
VERIFIED — terminal state for CARD_VERIFICATION ($0 auth). No auth hold, no settlement, no auth-reverse / void semantics apply. Inspect avs_response_code + cv_response_code for the verification outcome.

Value in

"INITIATED" | "THREE_DS_PENDING" | "THREE_DS_FAILED" | "AUTHORIZED" | "CAPTURED" | "SUBMITTED" | "SETTLED" | "VOIDED" | "REFUNDED" | "PARTIALLY_REFUNDED" | "REVERSED" | "FAILED" | "DISPUTED" | "CHARGED_BACK" | "VERIFIED"

type?string

Transaction type. Maps 1:1 to the domain TransactionType enum.

Value in

"AUTHORIZATION" | "SALE" | "CAPTURE" | "PARTIAL_CAPTURE" | "CAPTURE_ALL" | "AUTH_REVERSAL" | "PARTIAL_AUTH_REVERSAL" | "VOID" | "REFUND" | "PARTIAL_REFUND" | "CARD_VERIFICATION" | "SURCHARGE" | "ACH_DEBIT" | "ACH_REFUND" | "ACH_REVERSAL" | "ACH_VOID" | "ACH_RETURN" | "RECURRING_CREATE" | "RECURRING_UPDATE" | "RECURRING_CANCEL" | "RECURRING_RETRY" | "RECURRING_PAUSE" | "RECURRING_RESUME" | "RECURRING_COMPLETION" | "REPEAT_SALE" | "ADJUSTMENT" | "BATCH_CLOSE"

rail?string

Value in"ACH" | "CARD"

from?string

Inclusive ISO-8601 lower bound on created_at.

Formatdate-time

to?string

Inclusive ISO-8601 upper bound on created_at.

Formatdate-time

amount_min?string

Inclusive lower bound on amount (dollars).

amount_max?string

Inclusive upper bound on amount (dollars).

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/transactions"

{
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
      "merchant_name": "string",
      "type": "AUTHORIZATION",
      "rail": "CARD",
      "amount": 0,
      "currency": "USD",
      "state": "INITIATED",
      "approval_code": "string",
      "decline_reason": "string",
      "card_last4": "string",
      "routing_last4": "string",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjAxSFhZWi4uLiJ9",
    "has_more": true,
    "total_count": 0
  }
}

{
  "type": "https://docs.cresoracommerce.com/errors/invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key not recognized or revoked.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "invalid_api_key",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/permission_denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks scope 'transactions.write' required for this endpoint.",
  "instance": "urn:cresora:trace:0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5",
  "code": "permission_denied",
  "retryable": false,
  "error_id": "0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after 60 seconds.",
  "instance": "urn:cresora:trace:0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "error_id": "0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal error occurred. Please retry; if the error persists, contact support with the error_id.",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "internal_error",
  "retryable": true,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

Create transaction (polymorphic — all card + ACH operations)

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk__

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Format: 1–128 characters of letters, digits, . _ : -. Anything else is rejected with 400 validation_error. The character set is narrower than base64: padded base64 (+ / =) is NOT accepted, base64url is. The key is forwarded verbatim to the payment gateway on transaction creates, so it must satisfy the gateway's key contract too — rejecting locally gives you an actionable error instead of an opaque upstream failure mid-request.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header Idempotency-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 409 idempotency_key_conflict. Generate a new key and retry.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Retrying after an indeterminate failure. On 502 gateway_outcome_unknown the transaction is recorded as pending and the outcome is not yet known — retry with the SAME key (a fresh key risks a double charge) or poll the transaction. This is also what a gateway-side "an earlier request with this key is still in flight" response surfaces as.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Operation discriminator. See CreateTransactionRequest for accepted values. TransactionType values without a variant (e.g. SURCHARGE, ADJUSTMENT, recurring lifecycle markers) are not accepted at this endpoint and return 501.

Value in"SALE"

entry_mode?string

Optional on SALE — defaults to ECOMMERCE when omitted (any value except ACH, which is the ACH-rail entry mode). ACH operations (ACH_DEBIT, ACH_VOID, ACH_REVERSAL, ACH_REFUND) pin ACH server-side — omit the field, or send exactly ACH; any other value is rejected with a field-level 400 (never silently overridden). Follow-up operations (CAPTURE family, VOID, REFUND family, AUTH_REVERSAL) derive it from the parent transaction and ignore a supplied value.

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount*Amount

Charge amount. Required for SALE, PARTIAL_CAPTURE, PARTIAL_REFUND, and ACH_DEBIT. Optional for ACH_REFUND (omit = full refund) and AUTH_REVERSAL (omit = full reversal; a lesser amount performs a PARTIAL reversal — see AuthReversalRequest). Ignored for CAPTURE / CAPTURE_ALL / REFUND / VOID (derived from the parent transaction).

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id?string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

6- or 8-digit bank identification number (ISO 7812-1), used by the surcharge engine to discriminate debit (never surchargeable — Durbin) from credit. Optional on SALE (cardholder-initiated only); a missing BIN routes the calculator into the no-surcharge fail-safe branch.

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

vault_token*string

Cresora vault token (prefix cvt_) identifying the saved card to charge. From a prior HPP save-card session (data.cresoraVaultToken on the hpp_session.completed webhook, also readable via the stored-credentials API).

Lengthlength <= 256

use_type*string

Declared reuse intent. Must be within the credential's declared scope. ONE_TIME_FUTURE is cardholder-initiated; the others are merchant-initiated (billed as-is).

Value in"RECURRING" | "INSTALLMENT" | "UNSCHEDULED_COF" | "ONE_TIME_FUTURE"

custom_fields?array<>

Merchant custom-field values attached to this transaction. Accepted ONLY on SALE and ACH_DEBIT creates, on recurring-contract create (captured once and re-attached to every scheduled installment charge), and on HPP session create (pre-filled onto the hosted page; the field must additionally be visible on the hosted-payment-page surface). Supplying custom_fields on any other transaction type is rejected with 400 custom_fields_not_supported_for_type. Values are validated against the merchant's own ENABLED definitions.

NOT accepted on a save_card HPP session: the hosted page suppresses custom fields on save-card pages, so the values would be silently discarded. Submitting them there returns 422 custom_field_invalid.

Itemsitems <= 10

level2_data?

Level 2 purchase-card data — corporate/purchasing-card interchange qualification fields attached at transaction create. At least one field must be present (400 level2_data_empty otherwise). Forwarded to the gateway verbatim; echoed on reads and on the transaction webhook events.

level3_data?

Level 3 (line-item detail) purchase-card data attached at transaction create. Accepted ONLY on SALE and ACH_DEBIT creates, on recurring-contract create (captured once and re-attached to every installment charge), and on HPP session create. Any other transaction type rejects with 400 level_data_not_supported_for_type.

line_items is REQUIRED with at least one entry: a header-only Level 3 block is stored by the gateway without error but silently settles on the Level 2 path — the platform rejects that shape (400 level3_line_items_required) so a submission you believe is L3 can never silently not be.

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"CAPTURE"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"PARTIAL_CAPTURE"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount*Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"CAPTURE_ALL"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id?string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids*array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"VOID"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"REFUND"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason*string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"PARTIAL_REFUND"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount*Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason*string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"AUTH_REVERSAL"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"ACH_DEBIT"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount*Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id?string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code*string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number*string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number*string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type*string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check*string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version*string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip*string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at*string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

custom_fields?array<>

Itemsitems <= 10

level2_data?

level3_data?

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"ACH_VOID"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason*AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"ACH_REVERSAL"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason*AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"ACH_REFUND"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id*string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason*string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

merchant_id*string

Merchant the transaction belongs to. MUST be owned by the authenticated partner — a foreign merchant_id returns 404 (uniform code, no cross-tenant existence leak).

Formatuuid

type*string

Value in"BATCH_CLOSE"

entry_mode?string

currency?Currency

ISO 4217 currency code. Phase 1 supports USD only.

Default"USD"

Value in"USD"

amount?Amount

Match^\d+\.\d{2}$

surcharge_amount?Amount

Match^\d+\.\d{2}$

convenience_fee_amount?Amount

Match^\d+\.\d{2}$

tax_amount?Amount

Match^\d+\.\d{2}$

parent_transaction_id?string

Parent transaction this follow-up operation references. Required for CAPTURE, PARTIAL_CAPTURE, VOID, REFUND, PARTIAL_REFUND, AUTH_REVERSAL, ACH_VOID, ACH_REVERSAL, and ACH_REFUND.

Formatuuid

parent_transaction_ids?array<>

CAPTURE_ALL only — batch of parent AUTHORIZATION ids to capture. Hard cap of 50 per call; split larger batches across multiple CAPTURE_ALL calls with distinct Idempotency-Keys.

Items1 <= items <= 50

gateway_transaction_id?string

Upstream gateway reference. Not required — follow-up operations resolve the gateway reference from parent_transaction_id server-side.

Lengthlength <= 128

card_bin?string

Match^\d{6}(\d{2})?$

card_brand?string

Optional surcharge-engine hint (SALE, cardholder-initiated only).

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in"WEB" | "PPD" | "CCD" | "TEL"

routing_number?string

ABA routing number (9 digits). Required for ACH_DEBIT.

Match^\d{9}$

account_number?string

Bank account number (NACHA OR1). Required for ACH_DEBIT.

Match^\d{4,17}$

account_type?string

Required for ACH_DEBIT.

Value in"CHECKING" | "SAVINGS"

name_on_check?string

Account holder name. Required for ACH_DEBIT.

Lengthlength <= 128

consent_text_version?string

Version reference of the ACH authorization consent document the customer accepted. Required for ACH_DEBIT.

Lengthlength <= 64

consent_ip?string

IPv4/IPv6 literal the customer authorized from. Required for ACH_DEBIT.

consent_at?string

ISO 8601 UTC instant of the ACH authorization (e.g. 2026-05-21T10:30:00Z). Required for ACH_DEBIT.

Formatdate-time

void_reason?AchVoidReason

Required for ACH_VOID.

Value in

"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "AUTHORIZATION_REVOKED" | "MERCHANT_REQUEST" | "COMPLIANCE_HOLD" | "SYSTEM_ERROR"

reversal_reason?AchReversalReason

Required for ACH_REVERSAL.

Value in"INCORRECT_AMOUNT" | "INCORRECT_ACCOUNT" | "DUPLICATE_ENTRY" | "INCORRECT_EAN"

refund_reason?string

Structured refund reason. Required for REFUND, PARTIAL_REFUND, and ACH_REFUND. insurance_adjustment covers the healthcare-ICP co-pay correction pattern.

Value in"overpayment" | "service_not_rendered" | "insurance_adjustment" | "customer_requested" | "other_with_note"

capture_reason?string

Optional free-text capture reason for CAPTURE / PARTIAL_CAPTURE. Recorded in the lifecycle timeline + audit log.

Lengthlength <= 280

refund_note?string

Optional free-text note accompanying a refund reason (primarily for refund_reason = other_with_note).

Lengthlength <= 280

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/transactions" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "merchant_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",    "type": "SALE",    "amount": "50.00",    "currency": "USD",    "vault_token": "cvt_01885fec-4444-7a31-9bbb-3e5b9a1f8c42",    "use_type": "ONE_TIME_FUTURE"  }'

{
  "transaction_id": "01918a2f-3e7c-7219-bbb3-d8f1e2c3a4b6",
  "merchant_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",
  "type": "SALE",
  "state": "CAPTURED",
  "amount": "42.50",
  "currency": "USD",
  "entry_mode": "KEYED",
  "decline_code": null,
  "avs_response_code": "Y",
  "cv_response_code": "M",
  "surcharge_amount": "0.00",
  "convenience_fee_amount": "0.00",
  "tax_amount": "0.00",
  "three_ds": null,
  "three_ds_failure_reason": null,
  "custom_fields": [
    {
      "name": "patientId",
      "value": "PT48213"
    }
  ],
  "created_at": "2026-04-29T18:42:11Z"
}

{
  "type": "https://docs.cresoracommerce.com/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for 1 field(s)",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "validation_error",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "errors": [
    {
      "field": "merchant_category_code",
      "code": "Pattern",
      "message": "must match pattern ^[0-9]{4}$"
    }
  ]
}

{
  "type": "https://docs.cresoracommerce.com/errors/invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key not recognized or revoked.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "invalid_api_key",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/permission_denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks scope 'transactions.write' required for this endpoint.",
  "instance": "urn:cresora:trace:0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5",
  "code": "permission_denied",
  "retryable": false,
  "error_id": "0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for 1 field(s)",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "validation_error",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "errors": [
    {
      "field": "merchant_category_code",
      "code": "Pattern",
      "message": "must match pattern ^[0-9]{4}$"
    }
  ]
}

{
  "type": "https://docs.cresoracommerce.com/errors/idempotency_key_conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Idempotency-Key was used 5 minutes ago with a different request body.",
  "instance": "urn:cresora:trace:0191c8a2-cbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "idempotency_key_conflict",
  "retryable": false,
  "error_id": "0191c8a2-cbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for 1 field(s)",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "validation_error",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "errors": [
    {
      "field": "merchant_category_code",
      "code": "Pattern",
      "message": "must match pattern ^[0-9]{4}$"
    }
  ]
}

{
  "type": "https://docs.cresoracommerce.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after 60 seconds.",
  "instance": "urn:cresora:trace:0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "error_id": "0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal error occurred. Please retry; if the error persists, contact support with the error_id.",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "internal_error",
  "retryable": true,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for 1 field(s)",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "validation_error",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "errors": [
    {
      "field": "merchant_category_code",
      "code": "Pattern",
      "message": "must match pattern ^[0-9]{4}$"
    }
  ]
}

{
  "type": "https://docs.cresoracommerce.com/errors/gateway_unavailable",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "Payment gateway temporarily unavailable.",
  "instance": "urn:cresora:trace:0191c8a2-ebcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "gateway_unavailable",
  "retryable": true,
  "error_id": "0191c8a2-ebcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/feature_disabled",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "HPP CARD session creation is temporarily unavailable",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "feature_disabled",
  "retryable": false,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/gateway_timeout",
  "title": "Gateway Timeout",
  "status": 504,
  "detail": "Payment gateway read timeout - outcome indeterminate, replay only via idempotency key",
  "instance": "urn:cresora:trace:0191c8a2-abcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "gateway_timeout",
  "retryable": true,
  "error_id": "0191c8a2-abcd-7a31-8c44-d8f1e2c3a4b5"
}

Transaction KPI summary

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk__

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Query Parameters

merchant_id?string

Formatuuid

q?string

Free-text search: case-insensitive substring on gateway_transaction_id, OR exact transaction-id match when the value parses as a UUID. Identical semantics on the list, summary, and export operations.

Lengthlength <= 200

state?string

Transaction lifecycle state. Maps to domain TransactionState. Aligned with implementation at T-3.10 (3DS2 authentication).

INITIATED — created, not yet submitted to gateway
THREE_DS_PENDING — a 3DS challenge is outstanding, waiting for the customer to complete. The three_ds projection carries challenge_url; the customer browser is redirected there and the ISV then calls POST /transactions/{id}/three-ds/complete to resolve the transaction. 15-minute TTL; on timeout / abandonment the server-side sweep promotes the row to THREE_DS_FAILED with three_ds_failure_reason = callback_timeout. Also listen for the transaction.three_ds_completed webhook for an eventually-consistent ack path. No current POST /transactions create path issues a step-up — the saved-card SALE charges an already-authenticated vault credential; this state and the completion endpoint are retained for reserved card-authentication flows.
THREE_DS_FAILED — terminal 3DS authentication failure. The three_ds_failure_reason field carries one of: challenge_failed, challenge_abandoned, callback_timeout, signature_invalid, unsupported_card, issuer_declined. The transaction is not authorized — no funds are held. Distinct from the generic FAILED state so chargeback / retry logic can dispatch on the 3DS-specific cause.
AUTHORIZED — funds held, not yet captured
CAPTURED — capture submitted, awaiting settlement
SUBMITTED — ACH entry accepted into the ODFI origination batch (T-4.2). Distinct from CAPTURED because card-rail void / refund / auth-reverse rules don't map onto ACH semantics. Clearing happens 1-3 banking days later via the settlement webhook (SUBMITTED → SETTLED on cleared, or → FAILED with an R-code on NACHA return).
SETTLED — funds moved into the merchant batch (end of day)
VOIDED — cancelled pre-settlement
REFUNDED — fully refunded post-settlement (cumulative refund equals original amount)
PARTIALLY_REFUNDED — one or more partial refunds issued, remaining refundable capacity > 0. Re-entrant: additional partial refunds are accepted until cumulative == original amount, at which point the state advances to REFUNDED.
REVERSED — authorization released (card) or NACHA reversal (ACH)
FAILED — terminal failure state; see decline_code for cause (covers both 3DS-specific and non-3DS failures)
DISPUTED — chargeback opened against a SETTLED transaction (Sprint 7 dispute lifecycle); evidence-gathering window open.
CHARGED_BACK — chargeback lost / resolved against the merchant.
VERIFIED — terminal state for CARD_VERIFICATION ($0 auth). No auth hold, no settlement, no auth-reverse / void semantics apply. Inspect avs_response_code + cv_response_code for the verification outcome.

Value in

"INITIATED" | "THREE_DS_PENDING" | "THREE_DS_FAILED" | "AUTHORIZED" | "CAPTURED" | "SUBMITTED" | "SETTLED" | "VOIDED" | "REFUNDED" | "PARTIALLY_REFUNDED" | "REVERSED" | "FAILED" | "DISPUTED" | "CHARGED_BACK" | "VERIFIED"

type?string

Transaction type. Maps 1:1 to the domain TransactionType enum.

Value in

"AUTHORIZATION" | "SALE" | "CAPTURE" | "PARTIAL_CAPTURE" | "CAPTURE_ALL" | "AUTH_REVERSAL" | "PARTIAL_AUTH_REVERSAL" | "VOID" | "REFUND" | "PARTIAL_REFUND" | "CARD_VERIFICATION" | "SURCHARGE" | "ACH_DEBIT" | "ACH_REFUND" | "ACH_REVERSAL" | "ACH_VOID" | "ACH_RETURN" | "RECURRING_CREATE" | "RECURRING_UPDATE" | "RECURRING_CANCEL" | "RECURRING_RETRY" | "RECURRING_PAUSE" | "RECURRING_RESUME" | "RECURRING_COMPLETION" | "REPEAT_SALE" | "ADJUSTMENT" | "BATCH_CLOSE"

rail?string

Value in"ACH" | "CARD"

from?string

Formatdate-time

to?string

Formatdate-time

amount_min?string

amount_max?string

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/transactions/summary"

{
  "total_count": 0,
  "total_volume": 0,
  "count_by_state": {
    "property1": 0,
    "property2": 0
  },
  "count_by_rail": {
    "property1": 0,
    "property2": 0
  },
  "approved_count": 0,
  "declined_count": 0,
  "auth_rate": 0,
  "refund_count": 0,
  "refund_volume": 0,
  "open_dispute_count": 0
}

{
  "type": "https://docs.cresoracommerce.com/errors/invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key not recognized or revoked.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "invalid_api_key",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/permission_denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks scope 'transactions.write' required for this endpoint.",
  "instance": "urn:cresora:trace:0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5",
  "code": "permission_denied",
  "retryable": false,
  "error_id": "0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after 60 seconds.",
  "instance": "urn:cresora:trace:0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "error_id": "0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal error occurred. Please retry; if the error persists, contact support with the error_id.",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "internal_error",
  "retryable": true,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

Export transactions as CSV

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk__

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Query Parameters

merchant_id?string

Formatuuid

q?string

Free-text search: case-insensitive substring on gateway_transaction_id, OR exact transaction-id match when the value parses as a UUID. Identical semantics on the list, summary, and export operations.

Lengthlength <= 200

state?string

Transaction lifecycle state. Maps to domain TransactionState. Aligned with implementation at T-3.10 (3DS2 authentication).

INITIATED — created, not yet submitted to gateway
THREE_DS_PENDING — a 3DS challenge is outstanding, waiting for the customer to complete. The three_ds projection carries challenge_url; the customer browser is redirected there and the ISV then calls POST /transactions/{id}/three-ds/complete to resolve the transaction. 15-minute TTL; on timeout / abandonment the server-side sweep promotes the row to THREE_DS_FAILED with three_ds_failure_reason = callback_timeout. Also listen for the transaction.three_ds_completed webhook for an eventually-consistent ack path. No current POST /transactions create path issues a step-up — the saved-card SALE charges an already-authenticated vault credential; this state and the completion endpoint are retained for reserved card-authentication flows.
THREE_DS_FAILED — terminal 3DS authentication failure. The three_ds_failure_reason field carries one of: challenge_failed, challenge_abandoned, callback_timeout, signature_invalid, unsupported_card, issuer_declined. The transaction is not authorized — no funds are held. Distinct from the generic FAILED state so chargeback / retry logic can dispatch on the 3DS-specific cause.
AUTHORIZED — funds held, not yet captured
CAPTURED — capture submitted, awaiting settlement
SUBMITTED — ACH entry accepted into the ODFI origination batch (T-4.2). Distinct from CAPTURED because card-rail void / refund / auth-reverse rules don't map onto ACH semantics. Clearing happens 1-3 banking days later via the settlement webhook (SUBMITTED → SETTLED on cleared, or → FAILED with an R-code on NACHA return).
SETTLED — funds moved into the merchant batch (end of day)
VOIDED — cancelled pre-settlement
REFUNDED — fully refunded post-settlement (cumulative refund equals original amount)
PARTIALLY_REFUNDED — one or more partial refunds issued, remaining refundable capacity > 0. Re-entrant: additional partial refunds are accepted until cumulative == original amount, at which point the state advances to REFUNDED.
REVERSED — authorization released (card) or NACHA reversal (ACH)
FAILED — terminal failure state; see decline_code for cause (covers both 3DS-specific and non-3DS failures)
DISPUTED — chargeback opened against a SETTLED transaction (Sprint 7 dispute lifecycle); evidence-gathering window open.
CHARGED_BACK — chargeback lost / resolved against the merchant.
VERIFIED — terminal state for CARD_VERIFICATION ($0 auth). No auth hold, no settlement, no auth-reverse / void semantics apply. Inspect avs_response_code + cv_response_code for the verification outcome.

Value in

"INITIATED" | "THREE_DS_PENDING" | "THREE_DS_FAILED" | "AUTHORIZED" | "CAPTURED" | "SUBMITTED" | "SETTLED" | "VOIDED" | "REFUNDED" | "PARTIALLY_REFUNDED" | "REVERSED" | "FAILED" | "DISPUTED" | "CHARGED_BACK" | "VERIFIED"

type?string

Transaction type. Maps 1:1 to the domain TransactionType enum.

Value in

"AUTHORIZATION" | "SALE" | "CAPTURE" | "PARTIAL_CAPTURE" | "CAPTURE_ALL" | "AUTH_REVERSAL" | "PARTIAL_AUTH_REVERSAL" | "VOID" | "REFUND" | "PARTIAL_REFUND" | "CARD_VERIFICATION" | "SURCHARGE" | "ACH_DEBIT" | "ACH_REFUND" | "ACH_REVERSAL" | "ACH_VOID" | "ACH_RETURN" | "RECURRING_CREATE" | "RECURRING_UPDATE" | "RECURRING_CANCEL" | "RECURRING_RETRY" | "RECURRING_PAUSE" | "RECURRING_RESUME" | "RECURRING_COMPLETION" | "REPEAT_SALE" | "ADJUSTMENT" | "BATCH_CLOSE"

rail?string

Value in"ACH" | "CARD"

from?string

Formatdate-time

to?string

Formatdate-time

amount_min?string

amount_max?string

Response Body

`text/csv`

`application/problem+json`

curl -X GET "https://example.com/transactions/export"

"string"

{
  "type": "https://docs.cresoracommerce.com/errors/invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key not recognized or revoked.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "invalid_api_key",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/permission_denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks scope 'transactions.write' required for this endpoint.",
  "instance": "urn:cresora:trace:0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5",
  "code": "permission_denied",
  "retryable": false,
  "error_id": "0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after 60 seconds.",
  "instance": "urn:cresora:trace:0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "error_id": "0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal error occurred. Please retry; if the error persists, contact support with the error_id.",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "internal_error",
  "retryable": true,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

Get transaction

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk__

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

transactionId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  "type": "AUTHORIZATION",
  "rail": "CARD",
  "state": "INITIATED",
  "amount": 0,
  "surcharge_amount": 0,
  "tax_amount": 0,
  "currency": "USD",
  "entry_mode": "string",
  "approval_code": "string",
  "decline_reason": "string",
  "avs_response_code": "string",
  "cv_response_code": "string",
  "routing_last4": "string",
  "idempotency_key": "string",
  "custom_fields": [
    {
      "name": "patientId",
      "value": "PT48213"
    }
  ],
  "level2_data": {
    "po_number": "PO4711",
    "merchant_zip": "78701"
  },
  "level3_data": {
    "ship_from_zip": "78701",
    "destination_zip": "90210",
    "destination_country_code": "USA",
    "invoice_number": "INV-42",
    "freight_amount": "5.00",
    "line_items": [
      {
        "product_code": "SVC-001",
        "description": "Consulting",
        "quantity": "2",
        "unit_price": "50.00",
        "tax_amount": "8.25",
        "extended_amount": "100.00",
        "total_amount": "108.25"
      }
    ]
  },
  "parent_transaction_id": "2862f816-fb62-4845-833b-6951bbef56b3",
  "recurring_contract_id": "06e8cf01-8f38-4d73-81db-510f9724f797",
  "settled_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "available_actions": [
    "capture"
  ],
  "refundable_balance": {
    "original": 0,
    "refunded_to_date": 0,
    "remaining": 0
  },
  "state_transitions": [
    {
      "from_state": "string",
      "to_state": "string",
      "actor_type": "string",
      "reason": "string",
      "occurred_at": "2019-08-24T14:15:22Z"
    }
  ],
  "related_transactions": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "type": "AUTHORIZATION",
      "rail": "CARD",
      "state": "INITIATED",
      "amount": 0,
      "parent_transaction_id": "2862f816-fb62-4845-833b-6951bbef56b3",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ],
  "disputes": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "state": "RECEIVED",
      "reason_category": "string",
      "reason_code": "string",
      "reason_description": "string",
      "amount": 0,
      "currency": "USD",
      "case_number": "string",
      "response_deadline": "2019-08-24",
      "open": true
    }
  ]
}

{
  "type": "https://docs.cresoracommerce.com/errors/invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key not recognized or revoked.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "invalid_api_key",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/permission_denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks scope 'transactions.write' required for this endpoint.",
  "instance": "urn:cresora:trace:0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5",
  "code": "permission_denied",
  "retryable": false,
  "error_id": "0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/merchant_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Merchant 01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42 does not exist or is not accessible.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "merchant_not_found",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after 60 seconds.",
  "instance": "urn:cresora:trace:0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "error_id": "0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal error occurred. Please retry; if the error persists, contact support with the error_id.",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "internal_error",
  "retryable": true,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

Complete 3DS2 challenge

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk__

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Path Parameters

transactionId*string

Formatuuid

Header Parameters

Idempotency-Key*string

Client-generated unique key — a UUIDv4 is the recommended form. Cresora deduplicates within a 24-hour window scoped to the partner.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

hpp:, recurring: — Cresora's own server-minted deterministic keys. A client key in these namespaces could collide with a platform-generated record.
rb:, inv-charge:, inv-installment: — reserved by the payment gateway for its internally-minted keys.

Replay semantics:

Same key + same request body → Cresora returns the cached response from the original call. Response includes header Idempotency-Replay: true so the client can distinguish replays from fresh executions. Status code, body and side effects are identical to the original call.
Same key + different body → 409 idempotency_key_conflict. Generate a new key and retry.
Key older than 24 hours → treated as a fresh key; no replay guarantee from beyond the window.

Do NOT reuse keys across different partners. Scope is enforced per partner_id so the same key in partner A and partner B is independent.

Match^[A-Za-z0-9._:\-]+$

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

challenge_response*string

Opaque token from the challenge-completion redirect. Forwarded verbatim to the gateway. 256-char cap is a defense-in-depth DoS guard (3DS tokens are ≤ 64 chars in the gateway's wire format).

Lengthlength <= 256

merchant_id*string

Merchant the parent transaction belongs to. MUST match the merchant_id on the parent transaction — mismatched values are rejected as validation_error (404 not returned to avoid leaking parent existence to a foreign partner).

Formatuuid

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/transactions/497f6eca-6276-4993-bfeb-53cbbbba6f08/three-ds/complete" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "challenge_response": "cres_3ds_pARf8UXu0Wm9qQPDfT4bP0Vk",    "merchant_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42"  }'

{
  "transaction_id": "01918a2f-3e7c-7219-bbb3-d8f1e2c3a4b6",
  "merchant_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",
  "type": "SALE",
  "state": "CAPTURED",
  "amount": "42.50",
  "currency": "USD",
  "entry_mode": "KEYED",
  "decline_code": null,
  "avs_response_code": "Y",
  "cv_response_code": "M",
  "surcharge_amount": "0.00",
  "convenience_fee_amount": "0.00",
  "tax_amount": "0.00",
  "three_ds": null,
  "three_ds_failure_reason": null,
  "custom_fields": [
    {
      "name": "patientId",
      "value": "PT48213"
    }
  ],
  "created_at": "2026-04-29T18:42:11Z"
}

{
  "type": "https://docs.cresoracommerce.com/errors/invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key not recognized or revoked.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "invalid_api_key",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/permission_denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks scope 'transactions.write' required for this endpoint.",
  "instance": "urn:cresora:trace:0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5",
  "code": "permission_denied",
  "retryable": false,
  "error_id": "0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/merchant_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "Merchant 01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42 does not exist or is not accessible.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "merchant_not_found",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/idempotency_key_conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Idempotency-Key was used 5 minutes ago with a different request body.",
  "instance": "urn:cresora:trace:0191c8a2-cbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "idempotency_key_conflict",
  "retryable": false,
  "error_id": "0191c8a2-cbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for 1 field(s)",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "validation_error",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "errors": [
    {
      "field": "merchant_category_code",
      "code": "Pattern",
      "message": "must match pattern ^[0-9]{4}$"
    }
  ]
}

{
  "type": "https://docs.cresoracommerce.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after 60 seconds.",
  "instance": "urn:cresora:trace:0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "error_id": "0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal error occurred. Please retry; if the error persists, contact support with the error_id.",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "internal_error",
  "retryable": true,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/gateway_unavailable",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "Payment gateway temporarily unavailable.",
  "instance": "urn:cresora:trace:0191c8a2-ebcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "gateway_unavailable",
  "retryable": true,
  "error_id": "0191c8a2-ebcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/feature_disabled",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "HPP CARD session creation is temporarily unavailable",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "feature_disabled",
  "retryable": false,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/gateway_timeout",
  "title": "Gateway Timeout",
  "status": 504,
  "detail": "Payment gateway read timeout - outcome indeterminate, replay only via idempotency key",
  "instance": "urn:cresora:trace:0191c8a2-abcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "gateway_timeout",
  "retryable": true,
  "error_id": "0191c8a2-abcd-7a31-8c44-d8f1e2c3a4b5"
}

Preview surcharge rules

Authorization

BearerAuth

AuthorizationBearer <token>

Cresora API key, sent as an opaque bearer token in the Authorization header. Format:

csk__

<prefix> — 8 URL-safe chars, shown in UI and logs for identification without revealing the full key (e.g. csk_Ab3kX9mQ…). Use ApiKey.prefix to match.
<random> — 24+ cryptographically random URL-safe chars.

In: header

Query Parameters

merchant_id*string

Formatuuid

amount*string

Decimal amount with exactly 2 digits after the point. Always positive. Represented as string to avoid floating-point precision loss in JavaScript clients.

Match^\d+\.\d{2}$

state*string

US state code (e.g. TX, CA).

Match^[A-Z]{2}$

card_brand?string

Optional brand hint (from client-side tokenization metadata). When supplied, the brand cap participates in the rate computation and Amex merchant-eligibility is checked; when omitted, the preview uses state + merchant inputs only.

Value in"VISA" | "MASTERCARD" | "DISCOVER" | "AMEX" | "OTHER"

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/surcharge/rules?merchant_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&amount=42.50&state=string"

{
  "applicable": true,
  "reason": "APPLIED",
  "surcharge_amount": "3.00",
  "rate_percent": "3.00",
  "total_amount": "103.00",
  "disclosure_required": false,
  "disclosure_text": null
}

{
  "type": "https://docs.cresoracommerce.com/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for 1 field(s)",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b6",
  "code": "validation_error",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b6",
  "errors": [
    {
      "field": "merchant_category_code",
      "code": "Pattern",
      "message": "must match pattern ^[0-9]{4}$"
    }
  ]
}

{
  "type": "https://docs.cresoracommerce.com/errors/invalid_api_key",
  "title": "Unauthorized",
  "status": 401,
  "detail": "API key not recognized or revoked.",
  "instance": "urn:cresora:trace:0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "invalid_api_key",
  "retryable": false,
  "error_id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/permission_denied",
  "title": "Forbidden",
  "status": 403,
  "detail": "API key lacks scope 'transactions.write' required for this endpoint.",
  "instance": "urn:cresora:trace:0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5",
  "code": "permission_denied",
  "retryable": false,
  "error_id": "0191c8a2-9b7c-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/rate_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Too many requests. Retry after 60 seconds.",
  "instance": "urn:cresora:trace:0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "rate_limit_exceeded",
  "retryable": true,
  "error_id": "0191c8a2-dbcd-7a31-8c44-d8f1e2c3a4b5"
}

{
  "type": "https://docs.cresoracommerce.com/errors/internal_error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An internal error occurred. Please retry; if the error persists, contact support with the error_id.",
  "instance": "urn:cresora:trace:0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5",
  "code": "internal_error",
  "retryable": true,
  "error_id": "0191c8a2-fbcd-7a31-8c44-d8f1e2c3a4b5"
}

Transactions

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

501application/problem+json

502application/problem+json

503application/problem+json

504application/problem+json

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

200text/csv

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

502application/problem+json

503application/problem+json

504application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`text/csv`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`