Cresora Commerce Documentation

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

🔬Planned operations — published for review, not callable

This reference includes operations marked x-cresora-status: planned in the canonical contract: they have no route on any host and return 404 (or 501 for reserved discriminator variants) until released. There is no separate preview stream, no feature flag to enable one, and no enrollment — the badge on each operation tells you whether it is served. See the stable /api/v1 reference for what you can call today. Like the stable API, these operations are server-to-server: there is no interactive console here. Download the preview spec (YAML).

List transactions

GET/transactions

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk_<prefix>_<random>

<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).

Range1 <= value <= 100

Default25

merchant_id?string

Formatuuid

q?string

Free-text search over opaque identifiers, trimmed before matching: case-insensitive substring on gateway_transaction_id; exact match on the transaction id or merchant_id when the value parses as a UUID; exact match on the ACH routing_number_last4 or account_number_last4 when the value is exactly 4 digits. Amount, state and type are not searched — use their dedicated parameters.

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 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; a NACHA return drives SUBMITTED → RETURNED / SETTLED → RETURNED with an R-code — see the transaction.returned webhook).
SETTLED — funds moved into the merchant batch (end of day)
RETURNED — terminal: the ACH entry came back with a NACHA R-code, from SUBMITTED or SETTLED
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"
"RETURNED"
"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_code": "insufficient_funds",      "decline_reason": "string",      "card_last4": "string",      "routing_last4": "string",      "account_last4": "string",      "account_type": "CHECKING",      "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "next_cursor": "string",    "has_more": true,    "total_count": 0  }}

Create transaction (polymorphic — all card + ACH operations)

POST/transactions

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk_<prefix>_<random>

<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 X-Idempotent-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 → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
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.

Polymorphic request body for POST /transactions, discriminated on type. The wire format is one flat JSON object (mirrors the gateway's POST /api/transactions); the variants below pin per-operation required fields so generated SDKs stay typed.

AUTHORIZATION and CARD_VERIFICATION on card are reserved and currently return 501 — the only card instrument is a Cresora vault token (cvt_, delivered by an HPP save-card flow), and the gateway wire shapes for a vault-token authorize / $0-verify are not yet vendor-confirmed. They carry no request variant until then.

Authorize + capture in one step on a saved card, referenced by its Cresora vault token (cvt_…) — the opaque, partner-scoped handle returned on an hpp_session.completed webhook (or via the stored-credentials API). Raw PAN and raw gateway tokens are never accepted at this boundary (ADR-014 — the Cresora-identity-only surface): a card is first captured through an HPP save-card flow, which vaults it and yields the cvt_… reference.

use_type declares the reuse intent and drives the network CIT/MIT classification. It must be one of the uses the credential was vaulted with — the credential_usages declared on the HPP session that saved the card (readable as scope on the stored-credentials API); an intent outside that scope is refused with 422 stored_credential_scope_violation. Every credential carries at least one usage: the session that saves it must declare credential_usages (enforced at session create since 2026-08):

ONE_TIME_FUTURE — cardholder-initiated (the customer is present, paying with their saved card). Surcharge and convenience fee are computed server-side and the merchant's AVS policy is applied.
RECURRING / INSTALLMENT / UNSCHEDULED_COF — merchant-initiated; the amount is billed as-is (no surcharge / convenience fee, no AVS policy — the payer is not at the checkout to satisfy a step-up).

A declined charge is still a 200 with state = FAILED and a decline_code. A 422 stored_credential_not_chargeable with retryable: true means the vault entry's owning-customer link is still being established — retry shortly, do not re-enrol the payer. With retryable: false the vault entry predates the current charge-identity requirements — the payer must re-establish the payment method through a save hosted-page flow.

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*"SALE"

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.

Value in

"KEYED"
"SWIPED"
"CHIP"
"CONTACTLESS"
"ECOMMERCE"
"RECURRING"
"ACH"

currency?"USD"

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}$

convenience_fee_disclosure_acknowledged_at?string

SALE only. UTC instant the payer accepted the disclosed convenience fee — the confirm-click, not the submit. Required together with convenience_fee_disclosure_channel whenever the merchant's program resolves a non-zero fee on a cardholder-initiated charge (use_type: ONE_TIME_FUTURE); missing → 422 convenience_fee_disclosure_required. The pair is forwarded to the gateway, which requires it beside the itemized fee, and is persisted on the transaction as dispute evidence. Must not sit more than a few minutes ahead of the platform clock (422 convenience_fee_disclosure_in_future); no lower bound. Ignored on a merchant-initiated charge and when the resolved fee is zero. Sending one half without the other is a 400.

Formatdate-time

convenience_fee_disclosure_channel?string

SALE only. The surface on which the convenience-fee disclosure was shown and accepted — API for a direct integration's own checkout. Travels with convenience_fee_disclosure_acknowledged_at (both or neither).

Value in

"VIRTUAL_TERMINAL"
"HOSTED_PAYMENT_PAGE"
"API"

surcharge_disclosure_acknowledged_at?string

SALE only, card tender. UTC instant the payer accepted the disclosed surcharge — the confirm-click, not the submit. Required together with surcharge_disclosure_channel whenever the merchant's surcharge program is ACTIVE on the API channel; missing → 422 surcharge_disclosure_required. The pair is forwarded to the gateway, whose surcharging engine requires the attestation beside the surcharge it assesses, and is persisted on the transaction as dispute evidence. Must not sit more than a few minutes ahead of the platform clock (422 surcharge_disclosure_in_future); no lower bound. Ignored on a non-card tender. Sending one half without the other is a 400. Independent of the convenience-fee pair — at most one program is enabled per merchant, so a request carries at most one pair.

Formatdate-time

surcharge_disclosure_channel?string

SALE only. The surface on which the surcharge disclosure was shown and accepted — API for a direct integration's own checkout. Travels with surcharge_disclosure_acknowledged_at (both or neither).

Value in

"VIRTUAL_TERMINAL"
"HOSTED_PAYMENT_PAGE"
"API"

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). Optional; accepted on any transaction type, validated for shape and ignored — kept for backward compatibility. Cresora keeps no BIN table and classifies no card: the debit exclusion that governs surcharging (Durbin) is decided by the gateway's surcharging engine from the card it charges. A vault charge carries no BIN (G-62).

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

card_brand?string

Optional card-brand hint; accepted on any transaction type, validated against the enum and ignored — kept for backward compatibility. It does not influence the surcharge, which the gateway computes from the card it charges.

Value in

"VISA"
"MASTERCARD"
"DISCOVER"
"AMEX"
"OTHER"

ach_sec_code?string

NACHA SEC code. Required for ACH_DEBIT.

Value in

"WEB"
"PPD"
"CCD"
"TEL"

account_type?string

ACH_DEBIT only, optional — overrides the account type the saved account was established with; must not contradict it. There is no field for the account number itself: the partner API never carries raw bank-account data (ADR-057), so routing_number / account_number are unknown fields.

Value in

"CHECKING"
"SAVINGS"

name_on_check?string

ACH_DEBIT only, optional — account-holder name override; falls back to what the saved account recorded.

Lengthlength <= 100

consent_text_version?string

The Cresora-REGISTERED authorization-text version the payer accepted. You must display that registered text VERBATIM — this field attests which registered version was shown, not your own wording. Required for ACH_DEBIT. Use only ids from this spec's root x-cresora-consent-versions extension — the published, vendor-confirmed set, each with the exact text to display. The runtime registry may hold further internal ids that are deliberately not published; never submit an id you did not find in the catalog. An unknown id is rejected with 400 ach_consent_version_unknown.

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.

Temporal fences, applied per how the debit was initiated (the authorization-retention obligation is NACHA OR1 section 2.5; the 7-day window quantifying "reasonably recent" is Cresora policy):

Never in the future — a small clock-skew tolerance is allowed; beyond it, 400 naming consent_at. Applies to every ACH_DEBIT.
A payer-initiated debit (a raw-account debit, or a saved account charged with use_type: ONE_TIME_FUTURE) attests a FRESH online affirmation, so consent_at must also fall within a 7-day recency window — older is 400.
A merchant-initiated debit against a saved account (use_type: RECURRING, INSTALLMENT, or UNSCHEDULED_COF) stands on the STANDING authorization you hold, which is legitimately older than 7 days — the recency window is not applied. The instant you supply must still be the real capture time of that authorization: it is recorded as the entry's authorization evidence and produced in a bank-return dispute (R10).

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 when the definition is visible there; a definition hidden on the hosted-page surface is accepted too — its value is applied to the resulting transaction server-side without being rendered). 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 400 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.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/transactions" \  -H "Idempotency-Key: string" \  -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"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "type": "AUTHORIZATION",  "state": "INITIATED",  "amount": "string",  "currency": "USD",  "entry_mode": "KEYED",  "surcharge_amount": "string",  "surcharge_reversed_amount": "string",  "convenience_fee_amount": "string",  "convenience_fee_disclosure_acknowledged_at": "2019-08-24T14:15:22Z",  "convenience_fee_disclosure_channel": "VIRTUAL_TERMINAL",  "surcharge_disclosure_acknowledged_at": "2019-08-24T14:15:22Z",  "surcharge_disclosure_channel": "VIRTUAL_TERMINAL",  "tax_amount": "string",  "decline_code": "insufficient_funds",  "avs_response_code": "string",  "cv_response_code": "string",  "three_ds": {    "challenge_url": "http://example.com",    "acs_transaction_id": "string",    "version": "2.1.0",    "expires_at": "2019-08-24T14:15:22Z"  },  "three_ds_failure_reason": "challenge_failed",  "custom_fields": [    {      "name": "patientId",      "value": "PT48213"    }  ],  "level2_data": {    "po_number": "string",    "merchant_zip": "string"  },  "level3_data": {    "ship_from_zip": "string",    "destination_zip": "string",    "destination_country_code": "string",    "invoice_number": "string",    "order_number": "string",    "duty_amount": "string",    "freight_amount": "string",    "discount_amount": "string",    "line_items": [      {        "product_code": "string",        "commodity_code": "string",        "description": "string",        "upc": "string",        "invoice_number": "string",        "tax_type": "string",        "quantity": "string",        "unit_of_measure": "string",        "unit_price": "string",        "discount_amount": "string",        "total_amount": "string",        "tax_amount": "string",        "tax_rate": "string",        "extended_amount": "string",        "freight_amount": "string",        "duty_amount": "string",        "tax_included": true      }    ]  },  "created_at": "2019-08-24T14:15:22Z",  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e"}

Transaction KPI summary

GET/transactions/summary

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk_<prefix>_<random>

<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 over opaque identifiers, trimmed before matching: case-insensitive substring on gateway_transaction_id; exact match on the transaction id or merchant_id when the value parses as a UUID. Unlike the list operation, a 4-digit value does NOT match ACH routing/account last-4 — this read model carries no such columns. Amount, state and type are not searched — use their dedicated parameters.

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 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; a NACHA return drives SUBMITTED → RETURNED / SETTLED → RETURNED with an R-code — see the transaction.returned webhook).
SETTLED — funds moved into the merchant batch (end of day)
RETURNED — terminal: the ACH entry came back with a NACHA R-code, from SUBMITTED or SETTLED
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"
"RETURNED"
"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}

Export transactions as CSV

GET/transactions/export

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk_<prefix>_<random>

<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 over opaque identifiers, trimmed before matching: case-insensitive substring on gateway_transaction_id; exact match on the transaction id or merchant_id when the value parses as a UUID. Unlike the list operation, a 4-digit value does NOT match ACH routing/account last-4 — this read model carries no such columns. Amount, state and type are not searched — use their dedicated parameters.

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 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; a NACHA return drives SUBMITTED → RETURNED / SETTLED → RETURNED with an R-code — see the transaction.returned webhook).
SETTLED — funds moved into the merchant batch (end of day)
RETURNED — terminal: the ACH entry came back with a NACHA R-code, from SUBMITTED or SETTLED
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"
"RETURNED"
"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"

Get transaction

GET/transactions/{transactionId}

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk_<prefix>_<random>

<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,  "surcharge_reversed_amount": 0,  "tax_amount": 0,  "currency": "USD",  "entry_mode": "string",  "approval_code": "string",  "decline_code": "insufficient_funds",  "decline_reason": "string",  "avs_response_code": "string",  "cv_response_code": "string",  "card_last4": "string",  "routing_last4": "string",  "account_last4": "string",  "account_type": "CHECKING",  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",  "sec_code": "WEB",  "idempotency_key": "string",  "custom_fields": [    {      "name": "patientId",      "value": "PT48213"    }  ],  "level2_data": {    "po_number": "string",    "merchant_zip": "string"  },  "level3_data": {    "ship_from_zip": "string",    "destination_zip": "string",    "destination_country_code": "string",    "invoice_number": "string",    "order_number": "string",    "duty_amount": "string",    "freight_amount": "string",    "discount_amount": "string",    "line_items": [      {        "product_code": "string",        "commodity_code": "string",        "description": "string",        "upc": "string",        "invoice_number": "string",        "tax_type": "string",        "quantity": "string",        "unit_of_measure": "string",        "unit_price": "string",        "discount_amount": "string",        "total_amount": "string",        "tax_amount": "string",        "tax_rate": "string",        "extended_amount": "string",        "freight_amount": "string",        "duty_amount": "string",        "tax_included": true      }    ]  },  "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    }  ]}

Complete 3DS2 challenge

POST/transactions/{transactionId}/three-ds/complete

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk_<prefix>_<random>

<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 X-Idempotent-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 → 422 idempotency_key_reused. Generate a new key and retry, or re-send the original body.
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.

Completes a 3DS challenge after the customer returns from the issuer's challenge page. The challenge_response is the opaque token returned in the redirect query string (or POSTed form parameter, depending on flow). merchant_id is required so the use case can resolve the gateway merchant context (gateway_merchant_id) without an extra round-trip to the IAM key scope — the value MUST match the merchant on the parent transaction, otherwise the call is rejected as validation_error.

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: string" \  -H "Content-Type: application/json" \  -d '{    "challenge_response": "string",    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "type": "AUTHORIZATION",  "state": "INITIATED",  "amount": "string",  "currency": "USD",  "entry_mode": "KEYED",  "surcharge_amount": "string",  "surcharge_reversed_amount": "string",  "convenience_fee_amount": "string",  "convenience_fee_disclosure_acknowledged_at": "2019-08-24T14:15:22Z",  "convenience_fee_disclosure_channel": "VIRTUAL_TERMINAL",  "surcharge_disclosure_acknowledged_at": "2019-08-24T14:15:22Z",  "surcharge_disclosure_channel": "VIRTUAL_TERMINAL",  "tax_amount": "string",  "decline_code": "insufficient_funds",  "avs_response_code": "string",  "cv_response_code": "string",  "three_ds": {    "challenge_url": "http://example.com",    "acs_transaction_id": "string",    "version": "2.1.0",    "expires_at": "2019-08-24T14:15:22Z"  },  "three_ds_failure_reason": "challenge_failed",  "custom_fields": [    {      "name": "patientId",      "value": "PT48213"    }  ],  "level2_data": {    "po_number": "string",    "merchant_zip": "string"  },  "level3_data": {    "ship_from_zip": "string",    "destination_zip": "string",    "destination_country_code": "string",    "invoice_number": "string",    "order_number": "string",    "duty_amount": "string",    "freight_amount": "string",    "discount_amount": "string",    "line_items": [      {        "product_code": "string",        "commodity_code": "string",        "description": "string",        "upc": "string",        "invoice_number": "string",        "tax_type": "string",        "quantity": "string",        "unit_of_measure": "string",        "unit_price": "string",        "discount_amount": "string",        "total_amount": "string",        "tax_amount": "string",        "tax_rate": "string",        "extended_amount": "string",        "freight_amount": "string",        "duty_amount": "string",        "tax_included": true      }    ]  },  "created_at": "2019-08-24T14:15:22Z",  "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e"}

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

`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`