Cresora Commerce Documentation

Per-merchant custom-field definitions — up to 10 fields per merchant (a Cresora product cap; the gateway documents none). Definitions are delivered onto the merchant's gateway record and the field VALUES ride transaction creates (Sale / Authorization / ACH debit + recurring contract create) and hosted-page checkouts. Partner self-service (`custom_fields:config:read` / `custom_fields:config:write`); the merchant is scoped from your API key, never a path/body param.

🔬Preview stream (/api/v1-preview)

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

Get a merchant's custom-field definitions

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk__

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

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

In: header

Path Parameters

merchantId*string

The merchant whose custom-field definitions are managed. Must belong to the authenticated partner.

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{
  "id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "partner_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",
  "merchant_id": "01885fec-9d1a-7b42-8ccc-4f6cabff9d53",
  "fields": [
    {
      "name": "patientId",
      "description": "Clinic patient reference",
      "isEnabled": true,
      "maxLength": 25
    }
  ],
  "version": 3,
  "provisioning": {
    "status": "PROVISIONED",
    "error": null,
    "provisioned_version": 3
  }
}

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

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

Empty

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

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

Delete a merchant's custom-field definitions

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk__

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

In: header

Path Parameters

merchantId*string

The merchant whose custom-field definitions are managed. Must belong to the authenticated partner.

Formatuuid

Response Body

`application/problem+json`

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

Empty

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

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

Empty

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

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

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

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

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

Create or replace a merchant's custom-field definitions

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk__

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

In: header

Path Parameters

merchantId*string

The merchant whose custom-field definitions are managed. Must belong to the authenticated partner.

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.

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

Reserved prefixes — rejected with 400 idempotency_key_reserved:

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

Replay semantics:

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

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

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

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

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expected_version?integer

The version the client last read (0 on first save). Drives optimistic-lock conflict detection — a stale value returns 409.

Default0

Range0 <= value

fields?array<>

The full desired set (at most 10; empty clears all fields).

Itemsitems <= 10

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/config/custom-fields/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "expected_version": 0,    "fields": [      {        "name": "patientId",        "description": "Clinic patient reference",        "isEnabled": true,        "maxLength": 25      }    ]  }'

{
  "id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
  "partner_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",
  "merchant_id": "01885fec-9d1a-7b42-8ccc-4f6cabff9d53",
  "fields": [
    {
      "name": "patientId",
      "description": "Clinic patient reference",
      "isEnabled": true,
      "maxLength": 25
    }
  ],
  "version": 3,
  "provisioning": {
    "status": "PROVISIONED",
    "error": null,
    "provisioned_version": 3
  }
}

{
  "type": "https://docs.cresoracommerce.com/errors/idempotency_key_required",
  "title": "Bad Request",
  "status": 400,
  "detail": "Idempotency-Key header is required on write operations",
  "instance": "urn:cresora:trace:0191c8a2-aa3e-7c21-9ab3-d8f1e2c3a4b5",
  "code": "idempotency_key_required",
  "retryable": false,
  "error_id": "0191c8a2-aa3e-7c21-9ab3-d8f1e2c3a4b5"
}

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

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

Empty

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

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

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

List the partner's merchant custom-field configs

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk__

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

In: header

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/config/custom-fields/configs"

[
  {
    "id": "0191c8a2-7f3e-7c21-9ab3-d8f1e2c3a4b5",
    "partner_id": "01885fec-8c0f-7a31-9bbb-3e5b9a1f8c42",
    "merchant_id": "01885fec-9d1a-7b42-8ccc-4f6cabff9d53",
    "fields": [
      {
        "name": "patientId",
        "description": "Clinic patient reference",
        "isEnabled": true,
        "maxLength": 25
      }
    ],
    "version": 3,
    "provisioning": {
      "status": "PROVISIONED",
      "error": null,
      "provisioned_version": 3
    }
  }
]

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

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

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

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

Custom Fields

200application/json

401application/problem+json

403application/problem+json

404

429application/problem+json

500application/problem+json

204

401application/problem+json

403application/problem+json

404

422application/problem+json

429application/problem+json

500application/problem+json

502application/problem+json

503application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404

409application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

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

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`