Welcome to the CORALIX API.
\nOur API allows you to integrate payment processing into your application quickly and securely. Through a simple REST interface, you can create payment sessions, process transactions, manage refunds, tokenize payment methods, and receive real-time transaction updates via webhooks.
\nThis documentation includes:
\nAll API communication is performed over HTTPS, and all request and response bodies are formatted as JSON.
\nWhether you are building a custom checkout, integrating a hosted payment page, or automating payment operations, this guide provides everything you need to complete your integration.
\nWe look forward to helping you build a reliable and secure payment experience.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"547480","collectionId":"0a887196-9c41-4c91-987b-983aa882d323","publishedId":"2sBXwyGnNB","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-06-29T08:53:48.000Z"},"item":[{"name":"AUTHENTICATION","item":[],"id":"e73419de-30d6-4059-8672-66ec02d790b2","description":"All CORALIX API traffic is authenticated at the HTTP header level. There is no****session cookie and no OAuth flow for the core gateway — every request carries
its own credentials in the headers and (for server-to-server calls) is
cryptographically signed.
The Gateway API (/v1/sessions) is consumed backend-to-backend and is
authenticated with an API key plus an HMAC request signature:
\n\nAll requests must be sent over HTTPS. Request and response bodies are
\n
alwaysapplication/json.
Every call to the Gateway API must include the three headers below. The
signature proves that the caller holds the secret key without ever
transmitting the secret over the wire, and the timestamp protects against replay
attacks.
Keys are issued as a pair (the secret is shown only once, at creation). Rotate
or revoke a compromised pair from the merchant dashboard.
X-Signature is builtThe signature is the HMAC-SHA256 of a canonical string made of four lines
joined by newline (\\n) characters:
METHOD ← uppercase HTTP verb, e.g. POST\nPATH ← request path including /v1, WITHOUT the query string\nTIMESTAMP ← the same value sent in X-Timestamp (unix seconds)\nSHA256(body) ← lowercase hex SHA-256 of the exact raw request body\n\nConcretely:
\ncanonical = METHOD + \"\\n\" + PATH + \"\\n\" + TIMESTAMP + \"\\n\" + HEX(SHA256(body))\nsignature = HEX( HMAC_SHA256( canonical, secret_key ) )\n\nRules that must match exactly, or the server will return 401:
POST, GET, DELETE, …)./ and includes the /v1 prefix/v1/sessions/3b1211a8-7316-44a9-9764-1cc9e2ab1ca3/pay).?query=string.X-Timestamp header.GET, DELETE), hash the empty string.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.SHA256(body) and the final HMAC are encoded as lowercase hex.For POST https://api.coralix.tech/v1/sessions with the body
{\"order_id\":\"order_pm_2\",\"amount\":15.20,\"currency\":\"USD\"}\n\nsigned at 1753081200, the canonical string is:
POST\n/v1/sessions\n1753081200\n<sha256-hex-of-the-exact-body-above>\n\nand X-Signature = HMAC_SHA256(canonical, sk_live_…) in lowercase hex.
X-Timestamp and replay protectionX-Timestamp binds each request to a moment in time. The server rejects a
request whose timestamp is too far from server time (outside the allowed
clock-skew window), which prevents an intercepted request from being replayed
later.
Math.floor(Date.now()/1000)).401.\n\n⚠️ To document per the backend: the exact allowed clock-skew window (the
\n
maximum seconds a request may be old/future before it is rejected). A common
default is ±300 s. Confirm the real value with the gateway team and state
it here.
This is the exact signer used in the CORALIX Postman collection. Drop it into
the Pre-request Script tab so it runs for every gateway request and injects
the three headers automatically.
const publicKey = pm.variables.get('coralix_public_key');\nconst secretKey = pm.variables.get('coralix_secret_key');\nif (!publicKey || !secretKey) {\n throw new Error('Set the coralix_public_key and coralix_secret_key variables');\n}\n// METHOD (uppercase)\nconst method = pm.request.method.toUpperCase();\n// PATH including /v1, WITHOUT query string; resolve any {{vars}} in the path\nconst path = pm.variables.replaceIn('/' + pm.request.url.path.join('/'));\n// Exact body Postman will send (resolve {{vars}}); empty string for GET/DELETE\nconst rawBody = pm.request.body && pm.request.body.raw ? pm.request.body.raw : '';\nconst body = rawBody ? pm.variables.replaceIn(rawBody) : '';\nconst timestamp = Math.floor(Date.now() / 1000).toString();\nconst bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);\nconst canonical = [method, path, timestamp, bodyHash].join('\\n');\nconst signature = CryptoJS.HmacSHA256(canonical, secretKey).toString(CryptoJS.enc.Hex);\npm.request.headers.upsert({ key: 'X-API-Key', value: publicKey });\npm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });\npm.request.headers.upsert({ key: 'X-Signature', value: signature });\n\nEquivalent server-side (plain Node.js, no Postman):
\nconst crypto = require('crypto');\nfunction signCoralixRequest({ method, path, body = '', secretKey }) {\n const timestamp = Math.floor(Date.now() / 1000).toString();\n const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('hex');\n const canonical = [method.toUpperCase(), path, timestamp, bodyHash].join('\\n');\n const signature = crypto.createHmac('sha256', secretKey).update(canonical).digest('hex');\n return { 'X-Timestamp': timestamp, 'X-Signature': signature };\n}\n\nPOST /v1/sessions HTTP/1.1\nHost: api.coralix.tech\nContent-Type: application/json\nIdempotency-Key: order_pm_2\nX-API-Key: pk_live_fecc9278094f9fa2b24197fed9d6647f\nX-Timestamp: 1753081200\nX-Signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\n{\n \"order_id\": \"order_pm_2\",\n \"amount\": 15.20,\n \"currency\": \"USD\",\n \"customer_id\": \"cust_abc123\",\n \"success_url\": \"https://yoursite.com/success\",\n \"failure_url\": \"https://yoursite.com/failure\",\n \"cancel_url\": \"https://yoursite.com/cancel\",\n \"metadata\": { \"plan\": \"premium\", \"user_tier\": \"vip\" }\n}\n\nSome older examples and the sandbox authenticate the Gateway with a single
header instead of the HMAC triple:
Authorization: Bearer <public_key>:<secret_key>\n\nThe server splits the value on :, looks the merchant up by public key, and
verifies the secret against its stored SHA-256 hash.
\n\n⚠️ This form transmits the secret key in plaintext on every request and
\n
offers no replay protection. Prefer the signedX-API-Key/X-Timestamp/X-Signaturescheme (§1) for anything beyond local testing,
and confirm with the gateway team whether the Bearer form is still accepted inlive.
When header authentication fails, the API responds with 401 Unauthorized and a
JSON body that always carries an error_code and a request_id (quote therequest_id when contacting support):
{\n \"error_code\": \"invalid_signature\",\n \"message\": \"Signature verification failed\",\n \"request_id\": \"req_a1b2c3d4\"\n}\n\n\n\n⚠️ To document per the backend: the canonical list and exact spelling of
\nerror_codevalues. The table above lists the expected cases — align the
strings with what the gateway actually returns.
1. Create a payment session — POST /v1/sessions
{ \"order_id\": \"order_123\", \"amount\": 15.00, \"currency\": \"USD\" }\n\nReturns the session (status: \"pending\"), a checkout_url, and the available payment_methods. Sessions expire after 30 minutes.
2. Process the payment — POST /v1/sessions/{sessionId}/pay
{\n \"payment_method_config_id\": \"<id from payment_methods>\",\n \"payment_data\": {\n \"card_number\": \"4242424242424242\",\n \"exp_month\": 12, \"exp_year\": 2030,\n \"cvv\": \"123\", \"holder_name\": \"John Doe\"\n }\n}\n\nReturns { status: \"success\", transaction_id, provider_ref }, or on a decline { status: \"failed\", decline_reason, decline_message }. Use Accept-Language: es or en to choose the message language.
3. Receive the webhook — Coralix POSTs a signed payment.success / payment.failed event to your configured endpoint. You don't call this; it's pushed.
GET /v1/sessions/{sessionId}/status — check a session and its transactions.GET /v1/transactions/{id}/attempts — see each attempt and its decline reason.order_id is unique per merchant. Retrying with the same order_id + amount + currency returns the same session (safe retries, no double charge). Reusing an order_id with a different amount or currency returns 409.
Errors return { \"error_code\", \"message\", \"request_id\" }. Declines are not errors — /pay returns 200 with status: \"failed\" and a decline_message.
Use these test cards as payment_data.card_number in POST /v1/sessions/{sessionId}/pay. Any card needs a future expiry, a 3-digit CVV, and a non-empty holder name.
Each card forces a specific decline. The response is 200 with status: \"failed\", a decline_reason and a localized decline_message.
Any other well-formed card number that isn't 4242… is declined as do_not_honor.
Malformed card data is rejected (also status: \"failed\"):
POST /v1/sessions/{sessionId}/pay\n{\n \"payment_method_config_id\": \"<id from the session's payment_methods>\",\n \"payment_data\": {\n \"card_number\": \"4242424242424242\",\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"cvv\": \"123\",\n \"holder_name\": \"John Doe\"\n }\n}\n\nSend Accept-Language: es to receive Spanish decline_messages.
\n\n","_postman_id":"f806fbc5-df9f-42ca-92c5-4ae16ca9ed13"},{"name":"DECLINE REASONS REFERENCE","item":[],"id":"ab621510-1780-476f-95ad-66f27b31afbe","description":"These cards are sandbox-only. Production requires a real PSP adapter.
\n
When a payment is declined, POST /v1/sessions/{sessionId}/pay returns 200 with status: \"failed\", a machine-readable decline_reason and a customer-facing decline_message. The same decline_reason / decline_message appear on GET /v1/transactions/{id}/attempts and inside the payment.failed webhook payload.
Messages are returned in English by default; send Accept-Language: es for Spanish.
Notes
\ncategory is informational (groups the reason: card, issuer, gateway, risk, 3ds, network, compliance, limits, fallback).
Any unrecognized provider code maps to unknown_decline (the fallback), so your integration should always handle that case.
Show decline_message to the buyer; branch your logic on the stable decline_reason code, never on the message text.