Cresora Commerce Documentation

Partner configuration — webhook URL, IP allowlist, HPP defaults, rate-limit tier, AVS decline policy. Read your own config; write via `PUT /config/partners/{partnerId}`. Rate-limit tier and AVS decline policy are Cresora-managed (admin-only); webhook URL, HPP settings, and IP allowlist are partner self-service.

List the features granted to the calling partner

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

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/config/feature-flags/me"

[
  {
    "flag_name": "ach_payments",
    "display_name": "ACH Payments",
    "description": "Accept ACH debit payments via the hosted payment page.",
    "enabled": false,
    "globally_available": true,
    "depends_on": [
      "hpp_flow"
    ],
    "unmet_dependencies": [
      "hpp_flow"
    ]
  }
]

{
  "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"
}

Set the calling partner's on/off for a granted feature

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

flagName*string

Feature flag key (snake_case, 1..100 chars).

Length1 <= length <= 100

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.

enabled*boolean

Turn the granted feature on (true) or off (false).

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/config/feature-flags/me/string" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "enabled": true  }'

{
  "flag_name": "ach_payments",
  "partner_id": "01940000-0000-7000-8000-00000000aaaa",
  "enabled": true,
  "updated_at": "2026-07-09T12:00:00Z",
  "updated_by": "01940000-0000-7000-8000-00000000bbbb",
  "version": 3
}

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

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

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

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

{
  "type": "https://docs.cresoracommerce.com/errors/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 MCC catalog

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/mcc-catalog"

[
  {
    "code": "8049",
    "label": "8049 — Physical Therapists, Except Mental Health",
    "risk": "yellow"
  }
]

{
  "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"
}

List US states

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/us-states"

[
  {
    "code": "CA",
    "name": "California"
  }
]

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

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

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

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

Get partner configuration

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

partnerId*string

The partner UUID. Partners may only target their own partner_id; admin actors may target any.

Formatuuid

Response Body

`application/json`

`application/problem+json`

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

{
  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",
  "api_version": "v1",
  "webhook_url": "https://api.acmepay.com/webhooks/cresora",
  "rate_limit_tier": "STANDARD",
  "hpp_settings": {
    "gateway_hpp_page_id": "string",
    "accepted_methods": [
      "credit_card"
    ]
  },
  "ip_allowlist": [
    "203.0.113.0/24"
  ],
  "avs_decline_policy": "NEVER_DECLINE",
  "version": 1
}

{
  "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"
}

Create or replace partner configuration

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

partnerId*string

The partner UUID. Partners may only target their own partner_id; admin actors may target any.

Formatuuid

Header Parameters

Idempotency-Key*string

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

Reserved prefixes — rejected with 400 idempotency_key_reserved:

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

Replay semantics:

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

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

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

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

api_version?string

Match^v\d+$

Lengthlength <= 8

webhook_url?string

HTTPS URL, or empty string to clear.

Lengthlength <= 2048

rate_limit_tier?string

Admin-only — non-admin actors that send this field with a new value get 401 forbidden_admin_only_field.

Value in"STANDARD" | "PREMIUM" | "ENTERPRISE"

hpp_settings?

HPP iframe / redirect defaults applied to all of this partner's HPP sessions.

ip_allowlist?array<>

Itemsitems <= 256

avs_decline_policy?string

Admin-only.

Value in"NEVER_DECLINE" | "DECLINE_UNLESS_FULL_MATCH" | "DECLINE_UNLESS_ZIP_MATCH"

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/config/partners/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "webhook_url": "https://api.acmepay.com/webhooks/cresora",    "ip_allowlist": [      "203.0.113.0/24",      "198.51.100.42/32"    ],    "hpp_settings": {      "accepted_methods": [        "credit_card",        "debit_card"      ]    }  }'

{
  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",
  "api_version": "v1",
  "webhook_url": "https://api.acmepay.com/webhooks/cresora",
  "rate_limit_tier": "STANDARD",
  "hpp_settings": {
    "gateway_hpp_page_id": "string",
    "accepted_methods": [
      "credit_card"
    ]
  },
  "ip_allowlist": [
    "203.0.113.0/24"
  ],
  "avs_decline_policy": "NEVER_DECLINE",
  "version": 1
}

{
  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",
  "api_version": "v1",
  "webhook_url": "https://api.acmepay.com/webhooks/cresora",
  "rate_limit_tier": "STANDARD",
  "hpp_settings": {
    "gateway_hpp_page_id": "string",
    "accepted_methods": [
      "credit_card"
    ]
  },
  "ip_allowlist": [
    "203.0.113.0/24"
  ],
  "avs_decline_policy": "NEVER_DECLINE",
  "version": 1
}

{
  "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}$"
    }
  ]
}

{
  "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"
}

Get the effective hosted-payment-page appearance config

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk__

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

In: header

Query Parameters

merchant_id?string

Resolve the effective config for this merchant (override-or-template). Omit for the template.

Formatuuid

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://example.com/config/hpp-page"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",
  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  "is_template": true,
  "is_active": true,
  "appearance": {
    "presetKey": "string",
    "logo": {
      "mode": "cresora",
      "dataUrl": "string",
      "fileName": "string"
    },
    "page": {
      "bg": "string",
      "border": "string"
    },
    "header": {
      "bg": "string",
      "border": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "panel": {
      "bg": "string",
      "border": "string"
    },
    "input": {
      "bg": "string",
      "focusBg": "string",
      "border": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "button": {
      "fill": "string",
      "border": "string"
    },
    "typography": {
      "fontFamily": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "fields": {
      "order": {
        "invoiceNumber": false,
        "tax": false,
        "shipping": false,
        "total": true,
        "customerSetsInvoice": false
      },
      "address": {
        "billingAddress": false,
        "shippingAddress": false,
        "hideAddressPhone": false
      },
      "collectEmail": false,
      "resultScreenLabel": "string",
      "headerText": "string",
      "processButtonText": "string",
      "footerLinks": {
        "terms": {
          "enabled": true,
          "url": "http://example.com"
        },
        "privacy": {
          "enabled": true,
          "url": "http://example.com"
        },
        "support": {
          "enabled": true,
          "url": "http://example.com"
        },
        "about": {
          "enabled": true,
          "url": "http://example.com"
        }
      },
      "poweredBy": {
        "mode": "custom",
        "text": "string"
      },
      "copyright": {
        "mode": "custom",
        "text": "string"
      }
    },
    "redirects": {
      "submitUrl": "http://example.com",
      "editUrl": "http://example.com",
      "continueUrl": "http://example.com"
    },
    "customCss": "string",
    "paymentMethods": [
      "card"
    ],
    "allowLevel3LineItems": false,
    "allowedEmbeddingDomains": [
      "string"
    ],
    "supportTokenization": false
  },
  "version": 0,
  "provisioning": {
    "status": "UNPROVISIONED",
    "hosted_page_id": "string",
    "error": "string",
    "gateway_required_fields": [
      "collect_email"
    ]
  }
}

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

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

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

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

Create or replace the partner-level HPP template

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk__

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

In: header

Header Parameters

Idempotency-Key*string

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

Reserved prefixes — rejected with 400 idempotency_key_reserved:

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

Replay semantics:

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

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

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

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expected_version?integer

The version the client last read (0 on first save). Optimistic-lock guard; a stale value yields 409.

Default0

Range0 <= value

is_active?boolean

Whether the page is active (the gateway's isActive mirror).

Defaulttrue

appearance*

Hosted-payment-page appearance/branding. Theme tokens are the merchant's chosen colors (data, not Cresora theme). Mirrors the gateway hosted-page config surface (theme, fields/panels, redirects, payment methods, Level-3, embedding domains, tokenization).

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/config/hpp-page" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "appearance": {}  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",
  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  "is_template": true,
  "is_active": true,
  "appearance": {
    "presetKey": "string",
    "logo": {
      "mode": "cresora",
      "dataUrl": "string",
      "fileName": "string"
    },
    "page": {
      "bg": "string",
      "border": "string"
    },
    "header": {
      "bg": "string",
      "border": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "panel": {
      "bg": "string",
      "border": "string"
    },
    "input": {
      "bg": "string",
      "focusBg": "string",
      "border": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "button": {
      "fill": "string",
      "border": "string"
    },
    "typography": {
      "fontFamily": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "fields": {
      "order": {
        "invoiceNumber": false,
        "tax": false,
        "shipping": false,
        "total": true,
        "customerSetsInvoice": false
      },
      "address": {
        "billingAddress": false,
        "shippingAddress": false,
        "hideAddressPhone": false
      },
      "collectEmail": false,
      "resultScreenLabel": "string",
      "headerText": "string",
      "processButtonText": "string",
      "footerLinks": {
        "terms": {
          "enabled": true,
          "url": "http://example.com"
        },
        "privacy": {
          "enabled": true,
          "url": "http://example.com"
        },
        "support": {
          "enabled": true,
          "url": "http://example.com"
        },
        "about": {
          "enabled": true,
          "url": "http://example.com"
        }
      },
      "poweredBy": {
        "mode": "custom",
        "text": "string"
      },
      "copyright": {
        "mode": "custom",
        "text": "string"
      }
    },
    "redirects": {
      "submitUrl": "http://example.com",
      "editUrl": "http://example.com",
      "continueUrl": "http://example.com"
    },
    "customCss": "string",
    "paymentMethods": [
      "card"
    ],
    "allowLevel3LineItems": false,
    "allowedEmbeddingDomains": [
      "string"
    ],
    "supportTokenization": false
  },
  "version": 0,
  "provisioning": {
    "status": "UNPROVISIONED",
    "hosted_page_id": "string",
    "error": "string",
    "gateway_required_fields": [
      "collect_email"
    ]
  }
}

{
  "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"
}

{
  "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 HPP 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/hpp-page/configs"

[
  {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",
    "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
    "is_template": true,
    "is_active": true,
    "appearance": {
      "presetKey": "string",
      "logo": {
        "mode": "cresora",
        "dataUrl": "string",
        "fileName": "string"
      },
      "page": {
        "bg": "string",
        "border": "string"
      },
      "header": {
        "bg": "string",
        "border": "string",
        "fontSize": 0,
        "fontColor": "string"
      },
      "panel": {
        "bg": "string",
        "border": "string"
      },
      "input": {
        "bg": "string",
        "focusBg": "string",
        "border": "string",
        "fontSize": 0,
        "fontColor": "string"
      },
      "button": {
        "fill": "string",
        "border": "string"
      },
      "typography": {
        "fontFamily": "string",
        "fontSize": 0,
        "fontColor": "string"
      },
      "fields": {
        "order": {
          "invoiceNumber": false,
          "tax": false,
          "shipping": false,
          "total": true,
          "customerSetsInvoice": false
        },
        "address": {
          "billingAddress": false,
          "shippingAddress": false,
          "hideAddressPhone": false
        },
        "collectEmail": false,
        "resultScreenLabel": "string",
        "headerText": "string",
        "processButtonText": "string",
        "footerLinks": {
          "terms": {
            "enabled": true,
            "url": "http://example.com"
          },
          "privacy": {
            "enabled": true,
            "url": "http://example.com"
          },
          "support": {
            "enabled": true,
            "url": "http://example.com"
          },
          "about": {
            "enabled": true,
            "url": "http://example.com"
          }
        },
        "poweredBy": {
          "mode": "custom",
          "text": "string"
        },
        "copyright": {
          "mode": "custom",
          "text": "string"
        }
      },
      "redirects": {
        "submitUrl": "http://example.com",
        "editUrl": "http://example.com",
        "continueUrl": "http://example.com"
      },
      "customCss": "string",
      "paymentMethods": [
        "card"
      ],
      "allowLevel3LineItems": false,
      "allowedEmbeddingDomains": [
        "string"
      ],
      "supportTokenization": false
    },
    "version": 0,
    "provisioning": {
      "status": "UNPROVISIONED",
      "hosted_page_id": "string",
      "error": "string",
      "gateway_required_fields": [
        "collect_email"
      ]
    }
  }
]

{
  "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"
}

Delete a per-merchant HPP override

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 HPP override is being managed. Must belong to the authenticated partner.

Formatuuid

Response Body

`application/problem+json`

curl -X DELETE "https://example.com/config/hpp-page/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 per-merchant HPP override

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 HPP override is being 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.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

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

Replay semantics:

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

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

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

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expected_version?integer

The version the client last read (0 on first save). Optimistic-lock guard; a stale value yields 409.

Default0

Range0 <= value

is_active?boolean

Whether the page is active (the gateway's isActive mirror).

Defaulttrue

appearance*

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/config/hpp-page/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "appearance": {}  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",
  "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea",
  "is_template": true,
  "is_active": true,
  "appearance": {
    "presetKey": "string",
    "logo": {
      "mode": "cresora",
      "dataUrl": "string",
      "fileName": "string"
    },
    "page": {
      "bg": "string",
      "border": "string"
    },
    "header": {
      "bg": "string",
      "border": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "panel": {
      "bg": "string",
      "border": "string"
    },
    "input": {
      "bg": "string",
      "focusBg": "string",
      "border": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "button": {
      "fill": "string",
      "border": "string"
    },
    "typography": {
      "fontFamily": "string",
      "fontSize": 0,
      "fontColor": "string"
    },
    "fields": {
      "order": {
        "invoiceNumber": false,
        "tax": false,
        "shipping": false,
        "total": true,
        "customerSetsInvoice": false
      },
      "address": {
        "billingAddress": false,
        "shippingAddress": false,
        "hideAddressPhone": false
      },
      "collectEmail": false,
      "resultScreenLabel": "string",
      "headerText": "string",
      "processButtonText": "string",
      "footerLinks": {
        "terms": {
          "enabled": true,
          "url": "http://example.com"
        },
        "privacy": {
          "enabled": true,
          "url": "http://example.com"
        },
        "support": {
          "enabled": true,
          "url": "http://example.com"
        },
        "about": {
          "enabled": true,
          "url": "http://example.com"
        }
      },
      "poweredBy": {
        "mode": "custom",
        "text": "string"
      },
      "copyright": {
        "mode": "custom",
        "text": "string"
      }
    },
    "redirects": {
      "submitUrl": "http://example.com",
      "editUrl": "http://example.com",
      "continueUrl": "http://example.com"
    },
    "customCss": "string",
    "paymentMethods": [
      "card"
    ],
    "allowLevel3LineItems": false,
    "allowedEmbeddingDomains": [
      "string"
    ],
    "supportTokenization": false
  },
  "version": 0,
  "provisioning": {
    "status": "UNPROVISIONED",
    "hosted_page_id": "string",
    "error": "string",
    "gateway_required_fields": [
      "collect_email"
    ]
  }
}

{
  "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/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"
}

Replace a merchant's HPP iframe embedding allow-list

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 HPP iframe embedding allow-list is 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.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

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

Replay semantics:

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

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

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

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

allowed_embedding_domains*array<>

Hostnames authorized to embed this merchant's HPP page in an iframe. Each entry is a bare hostname (example.com) or a single-level wildcard (*.example.com) — host values only, not URLs. IP literals and entries without a TLD are rejected. Exception: the literal localhost is accepted for local iframe development, as an explicit allow-list entry. Must be non-empty. The merchant is identified by the {merchantId} path segment; the page is per-merchant (no rail dimension). For the /add operation the size cap applies to the resulting union.

Items1 <= items <= 20

Response Body

`application/json`

`application/problem+json`

curl -X PUT "https://example.com/config/hpp-page/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/embedding-domains" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "allowed_embedding_domains": [      "shop.example.com",      "*.checkout.example.com"    ]  }'

{
  "allowed_embedding_domains": [
    "string"
  ]
}

{
  "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"
}

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

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

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

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

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

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

Add to a merchant's HPP iframe embedding allow-list (additive)

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 HPP iframe embedding allow-list is extended. 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.

Reserved prefixes — rejected with 400 idempotency_key_reserved:

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

Replay semantics:

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

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

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

Length1 <= length <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

allowed_embedding_domains*array<>

Items1 <= items <= 20

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/config/hpp-page/merchants/497f6eca-6276-4993-bfeb-53cbbbba6f08/embedding-domains/add" \  -H "Idempotency-Key: 7f3e2a9c-b4c1-4e25-9ab3-d8f1e2c3a4b5" \  -H "Content-Type: application/json" \  -d '{    "allowed_embedding_domains": [      "admin.example.com"    ]  }'

{
  "allowed_embedding_domains": [
    "string"
  ]
}

{
  "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"
}

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

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

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

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

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

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

Config

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

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

404

429application/problem+json

500application/problem+json

200application/json

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

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

409application/problem+json

429application/problem+json

500application/problem+json

200application/json

401application/problem+json

403application/problem+json

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

422application/problem+json

429application/problem+json

500application/problem+json

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

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

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

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