H P P
Hosted Payment Pages — Cresora-hosted checkout. PCI scope stays with Cresora + the gateway. The partner only handles the session redirect and the callback on completion.
/hpp/sessionsAuthorization
BearerAuth 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…). UseApiKey.prefixto 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
Header Parameters
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: trueso 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.
^[A-Za-z0-9._:\-]+$1 <= length <= 128Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
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
curl -X POST "https://example.com/hpp/sessions" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea" }'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "merchant_id": "500924a8-3f5e-4c00-beb8-2efcde988aea", "payment_method": "card", "state": "PENDING", "hpp_url": "http://example.com", "iframe_url": "http://example.com", "rendering_mode": "redirect", "capture_mode": "sale", "amount_mode": "customer_entered", "page_purpose": "payment", "recurring_plan": { "recurring_amount": "string", "frequency": "daily", "interval": 1, "number_of_payments": 2, "initial_charge_amount": "string" }, "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e", "amount": "string", "surcharge_amount": "string", "convenience_fee_amount": "string", "total_amount": "string", "currency": "USD", "expires_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z"}/hpp/sessions/{sessionId}Authorization
BearerAuth 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…). UseApiKey.prefixto match.<random>— 24+ cryptographically random URL-safe chars.
Obtain via Partner Portal → Settings → API keys. Keys are only shown in full at creation/rotation time — Cresora does not retain the full value in retrievable form. Rotate any key that may have been exposed via logs, client code, or source control.
In: header
Path Parameters
uuidResponse Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/hpp/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "state": "PENDING", "payment_method": "card", "capture_mode": "sale", "amount_mode": "customer_entered", "page_purpose": "payment", "recurring_plan": { "recurring_amount": "string", "frequency": "daily", "interval": 1, "number_of_payments": 2, "initial_charge_amount": "string" }, "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e", "tokenization_outcome": "not_requested", "vault_token": "string", "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482", "completed_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "rendering_mode": "redirect", "last_attempt": { "at": "2019-08-24T14:15:22Z", "reason": "reversed" }, "card": { "last4": "string", "expiry_month": 1, "expiry_year": 0, "brand": "string" }, "bank": { "account_type": "CHECKING", "account_last4": "string", "routing_last4": "string" }, "token_capture_failure": { "at": "2019-08-24T14:15:22Z", "reason": "string" }, "level3_data": { "ship_from_zip": "string", "destination_zip": "string", "destination_country_code": "string", "invoice_number": "string", "order_number": "string", "duty_amount": "string", "freight_amount": "string", "discount_amount": "string", "line_items": [ { "product_code": "string", "commodity_code": "string", "description": "string", "upc": "string", "invoice_number": "string", "tax_type": "string", "quantity": "string", "unit_of_measure": "string", "unit_price": "string", "discount_amount": "string", "total_amount": "string", "tax_amount": "string", "tax_rate": "string", "extended_amount": "string", "freight_amount": "string", "duty_amount": "string", "tax_included": true } ] }}/hpp/sessions/{sessionId}/cancelAuthorization
BearerAuth 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…). UseApiKey.prefixto match.<random>— 24+ cryptographically random URL-safe chars.
Obtain via Partner Portal → Settings → API keys. Keys are only shown in full at creation/rotation time — Cresora does not retain the full value in retrievable form. Rotate any key that may have been exposed via logs, client code, or source control.
In: header
Path Parameters
uuidHeader Parameters
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: trueso 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.
^[A-Za-z0-9._:\-]+$1 <= length <= 128Response Body
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
curl -X POST "https://example.com/hpp/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel" \ -H "Idempotency-Key: string"{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "state": "PENDING", "payment_method": "card", "capture_mode": "sale", "amount_mode": "customer_entered", "page_purpose": "payment", "recurring_plan": { "recurring_amount": "string", "frequency": "daily", "interval": 1, "number_of_payments": 2, "initial_charge_amount": "string" }, "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e", "tokenization_outcome": "not_requested", "vault_token": "string", "transaction_id": "0fec1e58-b197-4052-99cf-2218496c5482", "completed_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "rendering_mode": "redirect", "last_attempt": { "at": "2019-08-24T14:15:22Z", "reason": "reversed" }, "card": { "last4": "string", "expiry_month": 1, "expiry_year": 0, "brand": "string" }, "bank": { "account_type": "CHECKING", "account_last4": "string", "routing_last4": "string" }, "token_capture_failure": { "at": "2019-08-24T14:15:22Z", "reason": "string" }, "level3_data": { "ship_from_zip": "string", "destination_zip": "string", "destination_country_code": "string", "invoice_number": "string", "order_number": "string", "duty_amount": "string", "freight_amount": "string", "discount_amount": "string", "line_items": [ { "product_code": "string", "commodity_code": "string", "description": "string", "upc": "string", "invoice_number": "string", "tax_type": "string", "quantity": "string", "unit_of_measure": "string", "unit_price": "string", "discount_amount": "string", "total_amount": "string", "tax_amount": "string", "tax_rate": "string", "extended_amount": "string", "freight_amount": "string", "duty_amount": "string", "tax_included": true } ] }}Transactions
Process card sales, refunds, voids, authorizations and captures. Batch close operations for settlement timing.
Recurring
Manage recurring billing plans. First payment captures a gateway token via HPP; subsequent charges use the stored token. Retries are configurable per plan (soft decline + ACH R01).