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.

🔬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 the features granted to the calling partner

GET/config/feature-flags/me

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

Response Body

`application/json`

`application/problem+json`

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

[  {    "flag_name": "string",    "display_name": "string",    "description": "string",    "enabled": true,    "globally_available": true,    "depends_on": [      "string"    ],    "unmet_dependencies": [      "string"    ]  }]

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

PUT/config/feature-flags/me/{flagName}

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

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

The partner's own on/off choice for a granted feature. enabled is mandatory — an absent field is rejected with 400 rather than defaulting to off.

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: string" \  -H "Content-Type: application/json" \  -d '{    "enabled": true  }'

{  "flag_name": "string",  "partner_id": "6a3a39f6-861b-4a48-b868-5de838400e06",  "enabled": true,  "updated_at": "2019-08-24T14:15:22Z",  "updated_by": "string",  "version": 0}

List the MCC catalog

GET/config/mcc-catalog

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

[  {    "code": "string",    "label": "string",    "risk": "green",    "baa_requirement": "required"  }]

List US states

GET/config/us-states

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

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

Get partner configuration

GET/config/partners/{partnerId}

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

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": "string",  "webhook_url": "string",  "rate_limit_tier": "STANDARD",  "hpp_settings": {    "gateway_hpp_page_id": "string",    "accepted_methods": [      "credit_card"    ]  },  "ip_allowlist": [    "string"  ],  "avs_decline_policy": "NEVER_DECLINE",  "version": 1}

Create or replace partner configuration

PUT/config/partners/{partnerId}

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

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 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 body for PUT /config/partners/{partnerId}. Every field is nullable; null / omitted = leave unchanged. webhook_url == "" (empty string) clears the column.

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 403 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: string" \  -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": "string",  "webhook_url": "string",  "rate_limit_tier": "STANDARD",  "hpp_settings": {    "gateway_hpp_page_id": "string",    "accepted_methods": [      "credit_card"    ]  },  "ip_allowlist": [    "string"  ],  "avs_decline_policy": "NEVER_DECLINE",  "version": 1}

Get the effective hosted-payment-page appearance config

GET/config/hpp-page

Authorization

BearerAuth

AuthorizationBearer <token>

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

csk_<prefix>_<random>

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

In: header

Query Parameters

merchant_id?string

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,    "hideTitle": false,    "hideMerchantName": false,    "allowTransparentEmbedding": false,    "achWebAuthorizationText": "string",    "achRecurringWebAuthorizationText": "string",    "achSaveOnlyWebAuthorizationText": "string"  },  "version": 0,  "provisioning": {    "status": "UNPROVISIONED",    "hosted_page_id": "string",    "error": "string",    "gateway_required_fields": [      "collect_email"    ]  },  "platform_required_fields": [    "convenience_fee"  ]}

Create or replace the partner-level HPP template

PUT/config/hpp-page

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.

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.

Save body for the HPP template (PUT /config/hpp-page) or a merchant override (PUT /config/hpp-page/merchants/{merchantId}).

expected_version?integer

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

Range0 <= value

Default0

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: string" \  -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,    "hideTitle": false,    "hideMerchantName": false,    "allowTransparentEmbedding": false,    "achWebAuthorizationText": "string",    "achRecurringWebAuthorizationText": "string",    "achSaveOnlyWebAuthorizationText": "string"  },  "version": 0,  "provisioning": {    "status": "UNPROVISIONED",    "hosted_page_id": "string",    "error": "string",    "gateway_required_fields": [      "collect_email"    ]  },  "platform_required_fields": [    "convenience_fee"  ]}

List the partner's HPP configs

GET/config/hpp-page/configs

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/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,      "hideTitle": false,      "hideMerchantName": false,      "allowTransparentEmbedding": false,      "achWebAuthorizationText": "string",      "achRecurringWebAuthorizationText": "string",      "achSaveOnlyWebAuthorizationText": "string"    },    "version": 0,    "provisioning": {      "status": "UNPROVISIONED",      "hosted_page_id": "string",      "error": "string",      "gateway_required_fields": [        "collect_email"      ]    },    "platform_required_fields": [      "convenience_fee"    ]  }]

Delete a per-merchant HPP override

DELETE/config/hpp-page/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

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

Create or replace a per-merchant HPP override

PUT/config/hpp-page/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

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

Save body for the HPP template (PUT /config/hpp-page) or a merchant override (PUT /config/hpp-page/merchants/{merchantId}).

expected_version?integer

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

Range0 <= value

Default0

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: string" \  -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,    "hideTitle": false,    "hideMerchantName": false,    "allowTransparentEmbedding": false,    "achWebAuthorizationText": "string",    "achRecurringWebAuthorizationText": "string",    "achSaveOnlyWebAuthorizationText": "string"  },  "version": 0,  "provisioning": {    "status": "UNPROVISIONED",    "hosted_page_id": "string",    "error": "string",    "gateway_required_fields": [      "collect_email"    ]  },  "platform_required_fields": [    "convenience_fee"  ]}

Replace a merchant's HPP iframe embedding allow-list

PUT/config/hpp-page/merchants/{merchantId}/embedding-domains

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

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

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 — including the literal localhost, which the gateway refuses. Every entry must also resolve to a public address (loopback/private targets are refused with allowed_embedding_domain_unsafe), so for local iframe development front the local app with a publicly resolvable hostname (a dev subdomain or an HTTPS tunnel). 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: string" \  -H "Content-Type: application/json" \  -d '{    "allowed_embedding_domains": [      "shop.example.com",      "*.checkout.example.com"    ]  }'

{  "allowed_embedding_domains": [    "string"  ]}

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

POST/config/hpp-page/merchants/{merchantId}/embedding-domains/add

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

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

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: string" \  -H "Content-Type: application/json" \  -d '{    "allowed_embedding_domains": [      "admin.example.com"    ]  }'

{  "allowed_embedding_domains": [    "string"  ]}

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`