Cresora Commerce Documentation

Merchant lifecycle — create, submit for underwriting review, update, and close merchant accounts. Merchants progress through a state machine owned by Cresora Operations.

🔬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 merchants

GET/merchants

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

state?string

Merchant lifecycle state.

Renamed 2026-08 (one-way): UNDERWRITING was UNDER_REVIEW and CONFIG_FAILED was BOOTSTRAP_FAILED. The retired values are never reused; REVIEWING keeps its wire value (displayed "Under Review"). Added 2026-08: ACTIVE (the gateway-provisioned resting state — the provisioning flow previously went straight to LIVE).

DRAFT — being edited by partner, not yet submitted
SUBMITTED — awaiting Cresora Operations review
REVIEWING — under active Cresora review (pre-underwriting; displayed "Under Review")
AWAITING_MERCHANT_SIGNATURE — Cresora pre-check approved; the merchant processing agreement is out for the authorized signer's signature. Signature completion moves it to UNDERWRITING; a declined or abandoned envelope moves it to REJECTED (REJ_008)
UNDERWRITING — submitted to Paysafe underwriting; status-only — the underwriting result transitions it to APPROVED or REJECTED
APPROVED — underwriting passed, awaiting provisioning
CONFIGURING — approved; per-processor payment-gateway provisioning in progress
CONFIG_FAILED — gateway provisioning failed after retries; an admin can retry (resumes at the failed step)
ACTIVE — gateway-provisioned and resting pre-go-live; probe/test transactions run in this window. Cresora Operations fires go-live once the go-live gate passes
LIVE — processing real payments
REJECTED — rejected with rejection_reason_code + rejection_reason (see RejectionCode)
AWAITING_CLARIFICATION — Cresora requested more information; editable by the partner, re-enters review on response
SUSPENDED — temporarily blocked by Cresora
CLOSED — terminal state, cannot transition out

Value in

"DRAFT"
"SUBMITTED"
"REVIEWING"
"AWAITING_MERCHANT_SIGNATURE"
"UNDERWRITING"
"APPROVED"
"CONFIGURING"
"CONFIG_FAILED"
"ACTIVE"
"LIVE"
"REJECTED"
"AWAITING_CLARIFICATION"
"SUSPENDED"
"CLOSED"

mcc?string

Filter by exact merchant category code.

Match^[0-9]{4}$

Response Body

`application/json`

`application/problem+json`

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

{  "data": [    {      "id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",      "partner_id": "01885d7a-1234-7abc-8def-987654321fed",      "business_name": "Acme Pharmacy LLC",      "contact_email": "owner@acmepharmacy.com",      "contact_name": "Sarah Chen",      "state": "LIVE",      "merchant_category_code": "5912",      "channel": "CNP_ONLY",      "processor_mids": [        {          "processor": "TSYS",          "mid": "880012345678"        }      ],      "gateway_merchant_id": "wpg_m_8745",      "location_count": 2,      "resubmission_count": 0,      "resubmission_limit": 3,      "created_at": "2026-03-12T14:23:45Z",      "version": 7    }  ],  "pagination": {    "next_cursor": "eyJpZCI6IjAxODg1ZmVjLThjMGYtN2EzMSJ9",    "has_more": true,    "total_count": 147  }}

Create merchant (DRAFT)

POST/merchants

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.

Create a merchant under the authenticated partner.

Whether a merchant transacts with real funds is governed by the gateway-side test flag on its reseller/merchant registration — the platform itself carries no per-merchant environment field. Onboarding a merchant for real processing requires partner certification to be CERTIFIED (see Capabilities.certification_status).

business_name*string

Legal business name. Bounded at 5–100 characters by the payment gateway's own validation — a shorter or longer value is stored but can never be provisioned for processing, so it is rejected here rather than at go-live.

Length5 <= length <= 100

contact_email*string

Formatemail

Lengthlength <= 200

contact_name?string

Lengthlength <= 200

authorized_signer_name?string

Person authorized to sign the Merchant Processing Agreement (distinct from the KYC principal and the operational contact). Optional at create; required at submit (DRAFT → SUBMITTED).

Lengthlength <= 200

authorized_signer_email?string

Email the signature request is addressed to. Optional at create; required at submit (DRAFT → SUBMITTED).

Formatemail

Lengthlength <= 200

merchant_category_code*string

ISO 18245 merchant category code (4 digits). Must be within the partner's certified scope; scope enforcement is a review-time control today (no mcc_outside_scope rejection is issued by this endpoint).

Match^[0-9]{4}$

channel?MerchantChannel

Card-acceptance channel mix for the merchant.

Default"CNP_ONLY"

Value in

"CNP_ONLY"
"CP_ONLY"
"OMNICHANNEL"

application?

Optional sections 2–6, persisted in the SAME transaction as the merchant row. If any section is rejected the merchant is not created either — a 4xx here never leaves a DRAFT behind.

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "business_name": "Acme Pharmacy LLC",    "contact_email": "owner@acmepharmacy.com",    "contact_name": "Sarah Chen",    "merchant_category_code": "5912"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "business_name": "string",  "contact_email": "user@example.com",  "contact_name": "string",  "authorized_signer_name": "string",  "authorized_signer_email": "string",  "merchant_category_code": "string",  "state": "DRAFT",  "channel": "CNP_ONLY",  "processor_mids": [    {      "processor": "TSYS",      "mid": "string"    }  ],  "gateway_merchant_id": "string",  "location_count": 0,  "hipaa_baa_status": "NOT_REQUIRED",  "pci_saq_type": "A",  "clarification_message": "string",  "rejection_reason_code": "REJ_001",  "rejection_reason": "string",  "esign_envelope": {    "status": "SENT",    "sent_at": "2019-08-24T14:15:22Z",    "last_status_at": "2019-08-24T14:15:22Z",    "reissue_count": 0  },  "restriction_reason": "string",  "resubmission_count": 0,  "resubmission_limit": 0,  "submitted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Get merchant

GET/merchants/{merchantId}

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

merchantId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "business_name": "string",  "contact_email": "user@example.com",  "contact_name": "string",  "authorized_signer_name": "string",  "authorized_signer_email": "string",  "merchant_category_code": "string",  "state": "DRAFT",  "channel": "CNP_ONLY",  "processor_mids": [    {      "processor": "TSYS",      "mid": "string"    }  ],  "gateway_merchant_id": "string",  "location_count": 0,  "hipaa_baa_status": "NOT_REQUIRED",  "pci_saq_type": "A",  "clarification_message": "string",  "rejection_reason_code": "REJ_001",  "rejection_reason": "string",  "esign_envelope": {    "status": "SENT",    "sent_at": "2019-08-24T14:15:22Z",    "last_status_at": "2019-08-24T14:15:22Z",    "reissue_count": 0  },  "restriction_reason": "string",  "resubmission_count": 0,  "resubmission_limit": 0,  "submitted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Update merchant (DRAFT only)

PATCH/merchants/{merchantId}

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

merchantId*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.

Partial update. Only provided fields are modified. Only allowed while merchant is in DRAFT state.

business_name?string

Legal business name. Bounded at 5–100 characters by the payment gateway's own validation (see CreateMerchantRequest).

Length5 <= length <= 100

contact_email?string

Formatemail

Length1 <= length <= 200

contact_name?string

Length1 <= length <= 200

authorized_signer_name?string

Length1 <= length <= 200

authorized_signer_email?string

Formatemail

Length1 <= length <= 200

merchant_category_code?string

Match^[0-9]{4}$

channel?MerchantChannel

Card-acceptance channel mix for the merchant.

Value in

"CNP_ONLY"
"CP_ONLY"
"OMNICHANNEL"

application?

Optional sections 2–6, persisted in the SAME transaction as the basics — a rejected section rolls the whole PATCH back, so the record is never half-saved.

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "business_name": "string",  "contact_email": "user@example.com",  "contact_name": "string",  "authorized_signer_name": "string",  "authorized_signer_email": "string",  "merchant_category_code": "string",  "state": "DRAFT",  "channel": "CNP_ONLY",  "processor_mids": [    {      "processor": "TSYS",      "mid": "string"    }  ],  "gateway_merchant_id": "string",  "location_count": 0,  "hipaa_baa_status": "NOT_REQUIRED",  "pci_saq_type": "A",  "clarification_message": "string",  "rejection_reason_code": "REJ_001",  "rejection_reason": "string",  "esign_envelope": {    "status": "SENT",    "sent_at": "2019-08-24T14:15:22Z",    "last_status_at": "2019-08-24T14:15:22Z",    "reissue_count": 0  },  "restriction_reason": "string",  "resubmission_count": 0,  "resubmission_limit": 0,  "submitted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Submit merchant for review

POST/merchants/{merchantId}/submit

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

merchantId*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

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/submit" \  -H "Idempotency-Key: string"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "business_name": "string",  "contact_email": "user@example.com",  "contact_name": "string",  "authorized_signer_name": "string",  "authorized_signer_email": "string",  "merchant_category_code": "string",  "state": "DRAFT",  "channel": "CNP_ONLY",  "processor_mids": [    {      "processor": "TSYS",      "mid": "string"    }  ],  "gateway_merchant_id": "string",  "location_count": 0,  "hipaa_baa_status": "NOT_REQUIRED",  "pci_saq_type": "A",  "clarification_message": "string",  "rejection_reason_code": "REJ_001",  "rejection_reason": "string",  "esign_envelope": {    "status": "SENT",    "sent_at": "2019-08-24T14:15:22Z",    "last_status_at": "2019-08-24T14:15:22Z",    "reissue_count": 0  },  "restriction_reason": "string",  "resubmission_count": 0,  "resubmission_limit": 0,  "submitted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Resubmit a rejected merchant for review

POST/merchants/{merchantId}/resubmit

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

merchantId*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

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/resubmit" \  -H "Idempotency-Key: string"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "business_name": "string",  "contact_email": "user@example.com",  "contact_name": "string",  "authorized_signer_name": "string",  "authorized_signer_email": "string",  "merchant_category_code": "string",  "state": "DRAFT",  "channel": "CNP_ONLY",  "processor_mids": [    {      "processor": "TSYS",      "mid": "string"    }  ],  "gateway_merchant_id": "string",  "location_count": 0,  "hipaa_baa_status": "NOT_REQUIRED",  "pci_saq_type": "A",  "clarification_message": "string",  "rejection_reason_code": "REJ_001",  "rejection_reason": "string",  "esign_envelope": {    "status": "SENT",    "sent_at": "2019-08-24T14:15:22Z",    "last_status_at": "2019-08-24T14:15:22Z",    "reissue_count": 0  },  "restriction_reason": "string",  "resubmission_count": 0,  "resubmission_limit": 0,  "submitted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Respond to a clarification request

POST/merchants/{merchantId}/respond-clarification

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

merchantId*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

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/respond-clarification" \  -H "Idempotency-Key: string"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "business_name": "string",  "contact_email": "user@example.com",  "contact_name": "string",  "authorized_signer_name": "string",  "authorized_signer_email": "string",  "merchant_category_code": "string",  "state": "DRAFT",  "channel": "CNP_ONLY",  "processor_mids": [    {      "processor": "TSYS",      "mid": "string"    }  ],  "gateway_merchant_id": "string",  "location_count": 0,  "hipaa_baa_status": "NOT_REQUIRED",  "pci_saq_type": "A",  "clarification_message": "string",  "rejection_reason_code": "REJ_001",  "rejection_reason": "string",  "esign_envelope": {    "status": "SENT",    "sent_at": "2019-08-24T14:15:22Z",    "last_status_at": "2019-08-24T14:15:22Z",    "reissue_count": 0  },  "restriction_reason": "string",  "resubmission_count": 0,  "resubmission_limit": 0,  "submitted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Resend the merchant's MPA signature envelope

POST/merchants/{merchantId}/envelope/resend

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

merchantId*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

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/envelope/resend" \  -H "Idempotency-Key: string"

{  "status": "SENT",  "sent_at": "2019-08-24T14:15:22Z",  "last_status_at": "2019-08-24T14:15:22Z",  "reissue_count": 0}

Get merchant state-transition history

GET/merchants/{merchantId}/transitions

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

merchantId*string

Formatuuid

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

Response Body

`application/json`

`application/problem+json`

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

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "from_state": "string",      "to_state": "string",      "actor_type": "string",      "actor_id": "string",      "actor_label": "string",      "reason": "string",      "trace_id": "string",      "occurred_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "next_cursor": "string",    "has_more": true,    "total_count": 0  }}

Get a merchant's go-live gate status

GET/merchants/{merchantId}/go-live-gate

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

merchantId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/go-live-gate"

{  "can_go_live": true,  "items": [    {      "id": "string",      "label": "string",      "verified_by": "string",      "verification": "AUTO",      "overridable": true,      "status": "PASSED",      "unresolved_reason": "string"    }  ]}

Get a merchant's application sections 2–5 (PII masked)

GET/merchants/{merchantId}/application

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

merchantId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{  "gateway_submission": {    "requires_tax_identifiers": true,    "awaiting_input": true,    "awaiting_input_reason": "FIRST_SUBMISSION",    "awaiting_since": "2019-08-24T14:15:22Z"  },  "processing_profile": {    "dba": "string",    "business_type": "string",    "tax_id_last2": "string",    "business_address": {      "address_line1": "string",      "address_line2": "string",      "city": "string",      "state": "string",      "zip": "string",      "country": "US"    },    "business_website": "string",    "business_start_date": "2019-08-24",    "estimated_monthly_volume": 0,    "expected_annual_volume": 0,    "estimated_avg_ticket": 0,    "card_present_percentage": 0,    "card_not_present_percentage": 0,    "processing_history": {      "previous_processor": "string",      "years_processing": "string",      "chargeback_rate": "string",      "chargeback_notes": "string"    },    "primary_contact_phone": "string"  },  "beneficial_owners": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "full_legal_name": "string",      "ownership_percentage": 0,      "date_of_birth": "2019-08-24",      "tax_identifier_type": "SSN",      "business_title": "CEO_CFO",      "is_control_person": true,      "phone": "string",      "email": "string",      "residential_address": {        "address_line1": "string",        "address_line2": "string",        "city": "string",        "state": "string",        "zip": "string",        "country": "US"      },      "kyc_status": "string"    }  ],  "principal": {    "first_name": "string",    "last_name": "string",    "title": "string",    "ownership_percentage": 0,    "email": "string",    "phone": "string",    "gov_id_type": "string",    "gov_id_number_last4": "string",    "gov_id_expiration": "2019-08-24",    "gov_id_issuing_region": "string",    "gov_id_issuing_country": "string"  },  "bank_account": {    "account_holder_name": "string",    "routing_number": "string",    "account_number_last4": "string",    "account_type": "string",    "funding_method": "string",    "statement_descriptor": "string"  },  "accepted_modalities": [    "string"  ],  "payment_config": {    "hsa_fsa_iias": true,    "surcharging": true,    "settlement_frequency": "string",    "settlement_currency": "string",    "batch_close_time": "string",    "timezone": "string"  }}

Get the settlement bank-account verification status

GET/merchants/{merchantId}/bank-verification

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

merchantId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{  "status": "NOT_STARTED",  "updated_at": "2019-08-24T14:15:22Z"}

Poll the provider and refresh the bank-verification status

POST/merchants/{merchantId}/bank-verification/check

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

merchantId*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

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/bank-verification/check" \  -H "Idempotency-Key: string"

{  "status": "NOT_STARTED",  "updated_at": "2019-08-24T14:15:22Z"}

Get merchant fee settings

GET/merchants/{merchantId}/fee-settings

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

merchantId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{  "surcharge": {    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",    "status": "NOT_CONFIGURED",    "enabled": true,    "waiting_period_expires_at": "2019-08-24T14:15:22Z",    "notice_filed_at": "2019-08-24T14:15:22Z",    "notice_attested_date": "2019-08-24",    "default_rate": 0,    "channel": "NONE",    "disclosure_copy_template": "string",    "attested_cost_of_acceptance_rate": 1,    "cost_of_acceptance_attested_at": "2019-08-24T14:15:22Z",    "differential_network_rates_attested": true,    "differential_network_rates_attested_at": "2019-08-24T14:15:22Z",    "network_policies": [      {        "network": "Visa",        "is_allowed": true,        "custom_rate": 0      }    ],    "last_mirrored_at": "2019-08-24T14:15:22Z",    "version": 0  },  "convenience_fee": {    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",    "enabled": true,    "fee_type": "FIXED",    "fixed_amount": 0.01,    "percentage_rate": 1,    "version": 0  }}

Update the merchant's surcharge rate and channel

PUT/merchants/{merchantId}/fee-settings/surcharge

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

merchantId*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.

The partner's edit of an EXISTING surcharge configuration — rate and channel only. Creating the configuration, filing the card-brand notice, enabling and the state overrides are Cresora Compliance operations on the Admin Console.

default_rate*number

Fraction with at most four decimals (0.025 = 2.5%); the gateway caps it at the merchant's attested cost of acceptance.

Multiple Of0.0001

Range0 <= value <= 0.03

channel*SurchargeChannel

The ONE gateway channel the surcharge program applies to. The vendor's documentation names a single channel per configuration (G-111 ask 43 open on whether several may be combined), so Cresora writes exactly one.

Value in

"NONE"
"VIRTUAL_TERMINAL"
"API"
"HOSTED_PAYMENT_PAGE"
"RECURRING_BILLING"

version?integer

The last-read version of the program (stale value → 409).

Range0 <= value

Default0

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/fee-settings/surcharge" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "default_rate": 0,    "channel": "NONE"  }'

{  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "status": "NOT_CONFIGURED",  "enabled": true,  "waiting_period_expires_at": "2019-08-24T14:15:22Z",  "notice_filed_at": "2019-08-24T14:15:22Z",  "notice_attested_date": "2019-08-24",  "default_rate": 0,  "channel": "NONE",  "disclosure_copy_template": "string",  "attested_cost_of_acceptance_rate": 1,  "cost_of_acceptance_attested_at": "2019-08-24T14:15:22Z",  "differential_network_rates_attested": true,  "differential_network_rates_attested_at": "2019-08-24T14:15:22Z",  "network_policies": [    {      "network": "Visa",      "is_allowed": true,      "custom_rate": 0    }  ],  "last_mirrored_at": "2019-08-24T14:15:22Z",  "version": 0}

Create or update the merchant's convenience-fee program

PUT/merchants/{merchantId}/fee-settings/convenience-fee

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

merchantId*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.

enabled*boolean

fee_type*string

Value in

"FIXED"
"PERCENTAGE"

fixed_amount?|

Range0.01 <= value

percentage_rate?|

Range0 < value <= 1

version?integer

Range0 <= value

Default0

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/fee-settings/convenience-fee" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "enabled": true,    "fee_type": "FIXED"  }'

{  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "enabled": true,  "fee_type": "FIXED",  "fixed_amount": 0.01,  "percentage_rate": 1,  "version": 0}

Get the merchant's fee eligibility

GET/merchants/{merchantId}/fee-eligibility

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

merchantId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{  "profile": {    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",    "standard_channel": "IN_PERSON",    "alternative_channel": "IN_PERSON",    "alternative_channel_attested": true,    "alternative_channel_attested_at": "2019-08-24T14:15:22Z",    "gov_education_attested": true,    "gov_education_attested_at": "2019-08-24T14:15:22Z",    "api_disclosure_attested": true,    "api_disclosure_attested_at": "2019-08-24T14:15:22Z",    "platform_fee_agreement": true,    "platform_fee_disclosed_in_terms": true,    "version": 0  },  "determination": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",    "trigger": "MERCHANT_CREATED",    "resolver_version": 1,    "evaluated_at": "2019-08-24T14:15:22Z",    "outcomes": [      {        "instrument": "SURCHARGE",        "verdict": "ELIGIBLE",        "failures": [          {            "reason": "CF_NO_CARD",            "detail": "string",            "capturable": true          }        ],        "unmet_conditions": [          {            "reason": "CF_NO_CARD",            "detail": "string",            "capturable": true          }        ]      }    ],    "allowed_instruments": [      "SURCHARGE"    ],    "active_instrument_ineligible": true,    "inputs": {      "accepts_card": true,      "accepts_ach": true,      "boarded_processors": [        "string"      ],      "accepted_modalities": [        "string"      ],      "merchant_category_code": "string",      "registered_state": "string",      "registered_state_prohibited": true,      "standard_channel": "IN_PERSON",      "alternative_channel": "IN_PERSON",      "alternative_channel_attested": true,      "gov_education_attested": true,      "api_disclosure_attested": true,      "hosted_page_surface": true,      "platform_fee_agreement": true,      "platform_fee_disclosed_in_terms": true,      "surcharge_program_enabled": true,      "surcharge_notice_attested": true,      "surcharge_cost_basis_recorded": true,      "convenience_fee_enabled": true,      "convenience_fee_shape": "FIXED",      "convenience_fee_over_ceiling": true    }  }}

Create or update the merchant's fee profile

PUT/merchants/{merchantId}/fee-profile

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

merchantId*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.

standard_channel?|null

alternative_channel?|null

alternative_channel_attested?|

The merchant attests the alternative channel is a genuine alternative to its standard channel. Omit (or send null) to leave the recorded attestation as it is; false revokes it — refused with 422 fee_profile_locked_while_fee_enabled while the convenience-fee program is enabled (the gateway requires it on an enabled fee line).

api_disclosure_attested?|

For API-direct merchants — the ISV attests its checkout discloses the fee before the payer commits. Omit (or send null) to leave the recorded attestation as it is; false revokes it.

gov_education_attested?|

Admin-only compliance determination. Omit or echo the recorded value; a partner change is rejected with 422 fee_profile_field_admin_only.

platform_fee_agreement?|

Admin-only — the merchant agreement permits a platform fee.

platform_fee_disclosed_in_terms?|

Admin-only — the platform fee is disclosed in the agreement terms.

version?integer

0 on first-time setup; the last-read version on updates (stale value → 409).

Range0 <= value

Default0

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/fee-profile" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'

{  "profile": {    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",    "standard_channel": "IN_PERSON",    "alternative_channel": "IN_PERSON",    "alternative_channel_attested": true,    "alternative_channel_attested_at": "2019-08-24T14:15:22Z",    "gov_education_attested": true,    "gov_education_attested_at": "2019-08-24T14:15:22Z",    "api_disclosure_attested": true,    "api_disclosure_attested_at": "2019-08-24T14:15:22Z",    "platform_fee_agreement": true,    "platform_fee_disclosed_in_terms": true,    "version": 0  },  "determination": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",    "trigger": "MERCHANT_CREATED",    "resolver_version": 1,    "evaluated_at": "2019-08-24T14:15:22Z",    "outcomes": [      {        "instrument": "SURCHARGE",        "verdict": "ELIGIBLE",        "failures": [          {            "reason": "CF_NO_CARD",            "detail": "string",            "capturable": true          }        ],        "unmet_conditions": [          {            "reason": "CF_NO_CARD",            "detail": "string",            "capturable": true          }        ]      }    ],    "allowed_instruments": [      "SURCHARGE"    ],    "active_instrument_ineligible": true,    "inputs": {      "accepts_card": true,      "accepts_ach": true,      "boarded_processors": [        "string"      ],      "accepted_modalities": [        "string"      ],      "merchant_category_code": "string",      "registered_state": "string",      "registered_state_prohibited": true,      "standard_channel": "IN_PERSON",      "alternative_channel": "IN_PERSON",      "alternative_channel_attested": true,      "gov_education_attested": true,      "api_disclosure_attested": true,      "hosted_page_surface": true,      "platform_fee_agreement": true,      "platform_fee_disclosed_in_terms": true,      "surcharge_program_enabled": true,      "surcharge_notice_attested": true,      "surcharge_cost_basis_recorded": true,      "convenience_fee_enabled": true,      "convenience_fee_shape": "FIXED",      "convenience_fee_over_ceiling": true    }  }}

List merchant locations

GET/merchants/{merchantId}/locations

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

merchantId*string

Formatuuid

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

Response Body

`application/json`

`application/problem+json`

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

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",      "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",      "location_name": "string",      "address_line1": "string",      "address_line2": "string",      "city": "string",      "state_province": "string",      "postal_code": "string",      "country": "string",      "phone_number": "string",      "contact_name": "string",      "mid": "string",      "merchant_category_code": "string",      "is_active": true,      "created_at": "2019-08-24T14:15:22Z",      "version": 0    }  ],  "pagination": {    "next_cursor": "string",    "has_more": true,    "total_count": 0  }}

Create merchant location

POST/merchants/{merchantId}/locations

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

merchantId*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.

location_name*string

Lengthlength <= 200

address_line1*string

address_line2?string

city*string

state_province*string

postal_code*string

country?"US"

ISO 3166-1 alpha-2 country code. Phase 1 supports US only.

Default"US"

Value in

"US"

phone_number?string

contact_name?string

Lengthlength <= 200

mid?string

merchant_category_code?string

Match^[0-9]{4}$

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/locations" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "location_name": "string",    "address_line1": "string",    "city": "string",    "state_province": "string",    "postal_code": "string"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "location_name": "string",  "address_line1": "string",  "address_line2": "string",  "city": "string",  "state_province": "string",  "postal_code": "string",  "country": "string",  "phone_number": "string",  "contact_name": "string",  "mid": "string",  "merchant_category_code": "string",  "is_active": true,  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Get merchant location

GET/merchants/{merchantId}/locations/{locationId}

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

merchantId*string

Formatuuid

locationId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "location_name": "string",  "address_line1": "string",  "address_line2": "string",  "city": "string",  "state_province": "string",  "postal_code": "string",  "country": "string",  "phone_number": "string",  "contact_name": "string",  "mid": "string",  "merchant_category_code": "string",  "is_active": true,  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Update merchant location

PATCH/merchants/{merchantId}/locations/{locationId}

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

merchantId*string

Formatuuid

locationId*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.

Partial update — null/omitted fields are left unchanged. address_line2, phone_number, contact_name, and mid accept "" to explicitly clear. For the other string fields, an empty string "" is rejected with 400, but a whitespace-only value (e.g. " ") is silently treated as no change — the field is left unchanged, not rejected.

location_name?string

Length1 <= length <= 200

address_line1?string

Length1 <= length

address_line2?string

city?string

Length1 <= length

state_province?string

Length1 <= length

postal_code?string

Length1 <= length

country?"US"

ISO 3166-1 alpha-2 country code. Phase 1 supports US only.

Value in

"US"

phone_number?string

contact_name?string

Lengthlength <= 200

mid?string

merchant_category_code?string

Match^[0-9]{4}$

is_active?boolean

Response Body

`application/json`

`application/problem+json`

curl -X PATCH "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/locations/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "location_name": "string",  "address_line1": "string",  "address_line2": "string",  "city": "string",  "state_province": "string",  "postal_code": "string",  "country": "string",  "phone_number": "string",  "contact_name": "string",  "mid": "string",  "merchant_category_code": "string",  "is_active": true,  "created_at": "2019-08-24T14:15:22Z",  "version": 0}

Delete merchant location

DELETE/merchants/{merchantId}/locations/{locationId}

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

merchantId*string

Formatuuid

locationId*string

Formatuuid

Response Body

`application/problem+json`

curl -X DELETE "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/locations/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

List own merchant's compliance documents (metadata only)

GET/merchants/{merchantId}/compliance-documents

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

merchantId*string

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "document_type": "PCI_SAQ_A",    "status": "NOT_UPLOADED",    "file_name": "string",    "file_size_bytes": 0,    "mime_type": "string",    "uploaded_at": "2019-08-24T14:15:22Z",    "uploaded_by": "string",    "reviewed_by": "string",    "reviewed_at": "2019-08-24T14:15:22Z",    "rejection_reason": "string",    "side": "FRONT"  }]

Upload a compliance document (encrypted at rest)

POST/merchants/{merchantId}/compliance-documents

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

merchantId*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

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

document_type*ComplianceDocumentType

Value in

"PCI_SAQ_A"
"PCI_SAQ_A_EP"
"PCI_SAQ_B_IP"
"PCI_SAQ_D"
"PCI_SAQ_P2PE"
"PCI_SAQ_C_VT"
"HIPAA_BAA"
"HIPAA_BAA_AMENDMENT"
"GOVERNMENT_ID"
"SURCHARGE_NOTICE_FORM"

side?string

Required for GOVERNMENT_ID (the face this file shows); must be omitted for every other type.

Value in

"FRONT"
"BACK"

file*file

The document. PDF for PCI SAQ / HIPAA BAA; PDF, PNG or JPEG for GOVERNMENT_ID — see the operation description.

Formatbinary

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/compliance-documents" \  -H "Idempotency-Key: string" \  -F document_type="PCI_SAQ_A" \  -F file="string"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "document_type": "PCI_SAQ_A",  "status": "NOT_UPLOADED",  "file_name": "string",  "file_size_bytes": 0,  "mime_type": "string",  "uploaded_at": "2019-08-24T14:15:22Z",  "side": "FRONT"}

Record the SAQ type determined by the SAQ wizard

POST/merchants/{merchantId}/compliance/saq-type

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

merchantId*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.

saq_type*PciSaqType

PCI SAQ type. Determined by the ISV's 5-question SAQ wizard and confirmed by Cresora Compliance. C_VT is reachable only via wizard override (no question maps to it).

Value in

"A"
"A_EP"
"B_IP"
"C_VT"
"P2PE"
"D"

override_reason?string

Required only when the ISV overrides the wizard's recommendation. Persisted verbatim in the 7-year audit trail; must not contain a card number (rejected with a validation error if it does).

Lengthlength <= 1000

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/compliance/saq-type" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "saq_type": "A"  }'

{  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",  "hipaa_baa_status": "NOT_REQUIRED",  "pci_saq_type": "A",  "baa_verified_by": "string",  "baa_verified_at": "2019-08-24T14:15:22Z",  "saq_confirmed_by": "string",  "saq_confirmed_at": "2019-08-24T14:15:22Z"}

Download the HIPAA BAA template to sign

GET/merchants/{merchantId}/compliance/baa-template

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

merchantId*string

Formatuuid

Response Body

`application/pdf`

`application/problem+json`

curl -X GET "https://example.com/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/compliance/baa-template"

"string"

List PCI SAQ types

GET/onboarding/saq-types

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

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/onboarding/saq-types"

[  {    "code": "string",    "label": "string"  }]

Merchants

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

201application/json

400application/problem+json

401application/problem+json

403application/problem+json

409application/problem+json

422application/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

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

422application/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

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

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

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

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

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/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/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/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`

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

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