{"info":{"_postman_id":"0a887196-9c41-4c91-987b-983aa882d323","name":"CORALIX API","description":"

Welcome to the CORALIX API.

The CORALIX API lets you take payments, send payouts and issue refunds from your own backend through one REST interface, and tells you the outcome of each through signed webhooks.

Base URL

https://api.coralix.tech/v1\n

Every path in this documentation starts with /v1. All traffic is HTTPS, and all request and response bodies are JSON.

Environments

There is one base URL. Your API key decides the environment:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key prefix	Environment	What happens
`pk_test_…`	`test`	Payments go to sandbox providers. No real money moves. Use the cards in Testing.
`pk_production_…`	`production`	Real payments, real money.

The two environments are fully separate. A session, transaction or webhook endpoint created with a test key does not exist for a production key: reading it returns 404, the same as an identifier that was never created. Use the same API calls in both; only the key changes.

Conventions

Field names are snake_case, in requests and responses.
Amounts are decimal major units. Send them as a JSON number (15.20); responses return them as a string with two decimals (\"15.20\").
Currencies are ISO 4217 codes (USD, EUR, …).
Timestamps are ISO 8601 in UTC (2026-10-06T14:03:11.000Z).
Unknown fields in a request body are rejected with 400 validation_failed.
Errors always have the same shape, { \"error_code\", \"message\", \"request_id\" }. See Error Codes.

How this documentation is organized

Get your first test payment working:

Authentication: signing every request with your keys.
Payment Flow: from creating a session to knowing the outcome.
Testing: test cards and scenarios for the test environment.

Before going live:

Webhooks: receiving and verifying events. Required to know the real outcome of a payment.
Refunds: giving money back.
Withdrawals: sending money out, if payouts are enabled for your account.

Reference:

Endpoints: every endpoint, with examples.
Error Codes: everything the API can answer when a request fails.
Decline Reasons Reference: why a payment was declined.
Going Live: the checklist before switching to production keys.

Start with Authentication: every request must be signed.

\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":"

Every request to the CORALIX API is authenticated in its headers. There are no cookies, sessions or OAuth flows: each request carries your public key and an HMAC-SHA256 signature made with your secret key. The secret itself is never sent.

\n
Call the API from your backend only. Your secret key must never reach a browser or a mobile app.
\n

1. Your keys

Keys are issued in pairs, one pair per environment:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Key	Prefix	Where it goes	Rule
Public key	`pk_test_…` / `pk_production_…`	Sent in the `X-API-Key` header	Identifies you and the environment. Not secret.
Secret key	`sk_test_…` / `sk_production_…`	Never sent. Used only to compute `X-Signature`	Store it server-side, like a password.

The secret key is shown only once, when the pair is created. If it leaks, create a new pair and revoke the old one (see Endpoints → API keys).

2. Required headers

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Header	Required	Example	Description
`X-API-Key`	Yes	`pk_test_fecc9278094f9fa2b24197fed9d6647f`	Your public key
`X-Timestamp`	Yes	`1759759391`	Unix time in seconds, when you signed the request
`X-Signature`	Yes	`9f86d081884c7d65…`	Lowercase hex HMAC-SHA256 of the canonical string (see §3), keyed with your secret key
`Content-Type`	With a body	`application/json`	All bodies are JSON
`Idempotency-Key`	Recommended on `POST`; required on refunds	`order_123-pay-1`	Makes retries safe. See §6.
`X-Request-Id`	Optional	`your-trace-id`	If you send it, we use it as the `request_id` of the response

3. Building `X-Signature`

The signature is the HMAC-SHA256 of a canonical string of four lines joined by \\n:

METHOD         ← uppercase HTTP verb, e.g. POST\nPATH           ← request path including /v1, WITHOUT the query string\nTIMESTAMP      ← the same value you send in X-Timestamp\nSHA256(body)   ← lowercase hex SHA-256 of the exact raw request body\n

canonical = METHOD + \"\\n\" + PATH + \"\\n\" + TIMESTAMP + \"\\n\" + HEX(SHA256(body))\nsignature = HEX(HMAC_SHA256(secret_key, canonical))\n

These must match exactly, or the request is rejected with 401 invalid_authentication:

METHOD is uppercase (POST, GET, DELETE).
PATH starts with /v1 and excludes the scheme, the host and any ?query (e.g. /v1/sessions/3b1211a8-7316-44a9-9764-1cc9e2ab1ca3/pay).
TIMESTAMP is the same string you put in X-Timestamp.
The body is hashed byte for byte as it goes on the wire. Serialize it once, sign that string, and send that same string. Do not re-serialize, reorder keys or change whitespace after signing.
Requests without a body (GET, DELETE) hash the empty string, whose SHA-256 is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
Both hashes are lowercase hex.

Worked example

POST https://api.coralix.tech/v1/sessions, signed at 1759759391, with the body:

{\"order_id\":\"order_123\",\"amount\":15.20,\"currency\":\"USD\"}\n

The canonical string is:

POST\n/v1/sessions\n1759759391\n<sha256 hex of the exact body above>\n

and X-Signature = HMAC_SHA256(sk_test_…, canonical) in lowercase hex.

4. Timestamp and replay protection

X-Timestamp must be within ±300 seconds of our clock. Outside that window the request is rejected with 401 timestamp_out_of_window, so a captured request cannot be replayed later.

Send seconds, not milliseconds: Math.floor(Date.now() / 1000).
Keep your servers' clocks synchronized (NTP).
Use the same value in the header and in the canonical string.

5. Reference implementations

Node.js

const crypto = require('crypto');\n\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\n// Serialize once, sign that string, send that string.\nconst body = JSON.stringify({ order_id: 'order_123', amount: 15.2, currency: 'USD' });\nconst headers = {\n  'Content-Type': 'application/json',\n  'X-API-Key': process.env.CORALIX_PUBLIC_KEY,\n  ...signCoralixRequest({ method: 'POST', path: '/v1/sessions', body, secretKey: process.env.CORALIX_SECRET_KEY }),\n};\nconst res = await fetch('https://api.coralix.tech/v1/sessions', { method: 'POST', headers, body });\n

Postman pre-request script

Set the collection variables coralix_public_key and coralix_secret_key to your test keys, and put this in the collection's Pre-request Script tab so every request is signed:

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}\nconst method = pm.request.method.toUpperCase();\n// PATH including /v1, WITHOUT the query string\nconst path = pm.variables.replaceIn('/' + pm.request.url.path.join('/'));\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

A full signed request

POST /v1/sessions HTTP/1.1\nHost: api.coralix.tech\nContent-Type: application/json\nIdempotency-Key: order_123-create\nX-API-Key: pk_test_fecc9278094f9fa2b24197fed9d6647f\nX-Timestamp: 1759759391\nX-Signature: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\n\n{\"order_id\":\"order_123\",\"amount\":15.20,\"currency\":\"USD\",\"success_url\":\"https://yoursite.com/success\",\"failure_url\":\"https://yoursite.com/failure\"}\n

6. `Idempotency-Key`

Send a unique Idempotency-Key on POST /v1/sessions, /pay, /withdrawal and /capture so that a retry after a timeout never runs the operation twice.

Same key, same request: you get the stored response, with the same status and body, plus the header Idempotent-Replayed: true. Nothing runs again. This includes a declined payment: retrying it returns the same decline and does not charge again.
Same key, different request (another body or another endpoint): 409 idempotency_conflict, and nothing runs. Use a new key for every new operation.
Same key while the first request is still running: 409 idempotency_in_progress. Wait a moment and retry with the same key.
The first request failed (any 4xx or 5xx): nothing is stored, so you can retry with the same key.
Keys are scoped to your account and environment: the same value used with your test key and with your production key are two different keys.
A successful response is kept for 24 hours. After that, the key is treated as new.
503 idempotency_store_unavailable means we cannot honour the key right now. The request was not executed. Retry shortly with the same key.

\n
Refunds (POST /v1/transactions/{id}/refund) require Idempotency-Key and keep it permanently: repeating a key returns that refund's outcome, failure included.
\n

Independently of this header, order_id is unique per account and environment (see Payment Flow → Idempotency).

7. Authentication errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When
`400`	`invalid_request`	`X-Timestamp` is not Unix seconds, or `X-Signature` is not 64 lowercase hex characters
`401`	`invalid_authentication`	A header is missing, the key is unknown or revoked, or the signature does not match
`401`	`timestamp_out_of_window`	`X-Timestamp` is more than ±300 seconds from our clock

{\n  \"error_code\": \"invalid_authentication\",\n  \"message\": \"Invalid authentication\",\n  \"request_id\": \"b31ef3b8-5445-4046-abc1-3292389d6867\"\n}\n

An unknown key and a bad signature return the same error on purpose, so that nobody can probe which keys exist. When a request fails authentication, check in this order: the clock, the path (with /v1, without the query), and the body bytes.

\n","_postman_id":"e73419de-30d6-4059-8672-66ec02d790b2"},{"name":"PAYMENT FLOW","item":[],"id":"dee212b1-bb84-4779-8e35-50f05201d8eb","description":"

A payment goes through a session: you create it from your backend, the buyer pays it, and a webhook tells you the outcome.

your backend                 CORALIX                      buyer\n     │  POST /v1/sessions        │                            │\n     │──────────────────────────►│                            │\n     │  session + checkout_url   │                            │\n     │◄──────────────────────────│                            │\n     │                                                        │\n     │  Option A: redirect the buyer to checkout_url ────────►│\n     │  Option B: POST /v1/sessions/{id}/pay with card data   │\n     │──────────────────────────►│                            │\n     │                           │  (3-D Secure, if needed)   │\n     │                           │◄──────────────────────────►│\n     │  webhook: payment.success / payment.failed / …         │\n     │◄──────────────────────────│                            │\n

1. Create a session

POST /v1/sessions

{\n  \"order_id\": \"order_123\",\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\" }\n}\n

Only order_id, amount and currency are required. The response (201) is the session in pending, with:

checkout_url: a hosted payment page you can redirect the buyer to.
payment_methods: the methods available to you in this environment. Each has an id you pass to /pay as payment_method_config_id.
expires_at: a session expires 30 minutes after creation if it is not paid.

2. Process the payment

If you collect card data yourself instead of using checkout_url:

POST /v1/sessions/{sessionId}/pay

{\n  \"payment_method_config_id\": \"c0658ab5-0592-49e4-a6c4-b469b88091c3\",\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

Collecting card data yourself puts your systems in PCI DSS scope. If you are not certified, use checkout_url.

/pay answers 200 with one of these status values:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`status`	Meaning	What to do
`success`	The money moved	Fulfil the order (and confirm with the webhook)
`authorized`	Funds are held but not yet captured	Capture with `POST /v1/transactions/{id}/capture`
`requires_action`	The buyer must complete a step, usually 3-D Secure	Follow `action` (see §3)
`failed`	Declined	Show `decline_message` to the buyer. A declined payment is not an error.

Approved:

{\n  \"session_id\": \"ec00c38e-e3d7-4943-9ecd-172835c333bf\",\n  \"transaction_id\": \"b6eee137-2b06-4054-be27-3d81a1944249\",\n  \"status\": \"success\",\n  \"provider_ref\": \"PSP-1783967474304\",\n  \"payment_data\": {\n    \"card_number\": \"424242******4242\",\n    \"authorization_code\": \"GD2DA1\",\n    \"descriptor\": \"CORALIX*YOURSHOP\"\n  }\n}\n

Declined:

{\n  \"session_id\": \"ec00c38e-e3d7-4943-9ecd-172835c333bf\",\n  \"transaction_id\": \"b6eee137-2b06-4054-be27-3d81a1944249\",\n  \"status\": \"failed\",\n  \"error_code\": \"payment_declined\",\n  \"decline_reason\": \"insufficient_funds\",\n  \"decline_message\": \"Insufficient funds. Please try with another card.\"\n}\n

Branch on decline_reason, never on decline_message. Send Accept-Language: es to receive decline_message in Spanish. See Decline Reasons Reference.

Some payment methods require more payer data in payment_data: billing address, contact details or the buyer's IP address. If something required is missing, /pay answers 422 payer_data_required with missing_fields[], and the session stays pending so you can retry. See Endpoints → Pay a session for every field.

3. 3-D Secure and other actions

When /pay answers requires_action, the response carries an action object that says what the buyer must do. You have 15 minutes (action.expires_at).

{\n  \"session_id\": \"…\",\n  \"transaction_id\": \"…\",\n  \"status\": \"requires_action\",\n  \"action\": {\n    \"type\": \"redirect\",\n    \"url\": \"https://acs.bank.example/challenge\",\n    \"method\": \"POST\",\n    \"params\": { \"PaReq\": \"eJxVUts…\", \"MD\": \"…\" },\n    \"expires_at\": \"2026-10-06T14:18:11.000Z\"\n  }\n}\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`action.type`	What to do
`redirect`	Send the buyer to `url` with `method`. For `POST`, submit `params` as a form.
`voucher`	Show `voucher_code` (and `barcode_url` if present) to the buyer
`deposit`	Show the `address` (and `network`, `amount`, `memo`) to pay to
`otp`	Ask the buyer for the code sent to `sent_to`

When the buyer finishes, they come back to your success_url or failure_url. The redirect does not prove anything: wait for the webhook, or check GET /v1/sessions/{id}/status, before fulfilling the order.

If you lose the /pay response, GET /v1/sessions/{id}/status returns the pending action again.

4. Know the outcome

Two ways, and the first one is the source of truth:

Webhooks: we POST a signed event to your endpoint (payment.success, payment.failed, payment.authorized, payment.requires_action, payment.expired, …). See Webhooks.
Polling: GET /v1/sessions/{sessionId}/status returns the session status, any pending action, and its transactions.

5. Session and transaction statuses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Meaning
`pending`	Created, not paid yet
`processing`	A payment attempt is in progress
`requires_action`	Waiting for the buyer (3-D Secure, voucher, …)
`authorized`	Funds held, awaiting capture
`success`	The money moved
`failed`	Declined
`expired`	Not paid within 30 minutes, or the action was not completed in 15
`refunded`	Fully refunded
`chargebacked`	The buyer's bank reversed the payment

A session that is no longer pending cannot be paid again (400 session_invalid_state). To retry after a decline, create a new session with a new order_id.

6. Idempotency

order_id is unique per account and environment. Creating a session again with the same order_id, amount and currency returns the existing session: retries are safe and never create a duplicate. The same order_id with a different amount or currency returns 409 idempotency_conflict with the existing session_id.
Idempotency-Key protects /pay, /withdrawal and /capture against double execution. See Authentication → Idempotency-Key.

7. Errors

Errors always have the shape { \"error_code\", \"message\", \"request_id\" }. Declines are not errors: /pay answers them with 200 and status: \"failed\". See Error Codes.

\n","_postman_id":"dee212b1-bb84-4779-8e35-50f05201d8eb"},{"name":"TESTING","item":[],"id":"f806fbc5-df9f-42ca-92c5-4ae16ca9ed13","description":"

With a test key (pk_test_…), payments go to a simulated provider. The values below force each outcome, so you can test every branch of your integration without real money.

\n
Simulated providers are never reachable with a production key. The test cards below are declined in production, as any invalid card would be.
\n

Approved card

Use any future expiry date, any 3-digit CVV and any holder name.

\n\n\n\n\n\n\n\n\n\n\n\n\n

Card number	Result
`4242 4242 4242 4242`	`status: \"success\"` (or `authorized`, if your account captures manually)

Declined cards

Each card forces a specific decline. /pay answers 200 with status: \"failed\", a decline_reason and a decline_message.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Card number	`decline_reason`	`decline_message` (en)
`4000 0000 0000 9995`	`insufficient_funds`	Insufficient funds. Please try with another card.
`4000 0000 0000 0002`	`do_not_honor`	Your bank declined the payment. Please contact your bank.
`4000 0000 0000 0069`	`expired_card`	Your card has expired. Please use a valid card.
`4000 0000 0000 0127`	`incorrect_cvv`	Incorrect CVV. Please check your security code.
`4100 0000 0000 0019`	`fraud_suspected`	Transaction declined for security reasons.
`4000 0000 0000 4854`	`lost_card`	Card reported as lost.

Any other well-formed card number is declined as do_not_honor.

3-D Secure

\n\n\n\n\n\n\n\n\n\n\n\n\n

Card number	Result
`4000 0000 0000 3220`	`status: \"requires_action\"` with a `redirect` action to a simulated challenge page

On the challenge page, enter one of these codes:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Code	Result
`0000`	Authentication passes; the payment becomes `success` (or `authorized`)
`1111`	Declined: `3ds_failed`
`2222`	Declined: `do_not_honor`
`3333`	Declined: `insufficient_funds`

The outcome arrives by webhook, and the buyer is redirected to your success_url or failure_url. This is the flow to test that you wait for the webhook rather than trusting the redirect.

Invalid card data

Malformed payment_data never reaches the provider. /pay answers 422 invalid_payment_data, listing each problem in errors[], and the session stays pending, so you can fix the data and call /pay again.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Condition	Message in `errors[]`
Card number not 13 to 19 digits	`card_number must be 13 to 19 digits`
Month not between 1 and 12	`exp_month must be between 1 and 12`
Year not a four-digit year	`exp_year must be a four-digit year`
Expiry in the past	`exp_year: card has expired`
CVV not 3 or 4 digits	`cvv must be 3 or 4 digits`
Missing holder name	`holder_name is required`

{\n  \"error_code\": \"invalid_payment_data\",\n  \"message\": \"payment_data does not match the expected format\",\n  \"request_id\": \"6f1c2e0a-3b5d-4f8e-9a71-2c4d5e6f7a8b\",\n  \"errors\": [\"cvv must be 3 or 4 digits\"]\n}\n\n

Spaces and hyphens in card_number are accepted and removed. A two-digit exp_year such as 30 is read as 2030.

Withdrawals

In test, the cents of the session amount decide the outcome of a withdrawal:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Amount ends in	Result
`.13` (e.g. `25.13`)	`failed`
`.01` (e.g. `25.01`)	stays `processing`. Use it to test how you handle a payout that has not resolved yet.
anything else	`success`

Example: approved payment

POST /v1/sessions/{sessionId}/pay\n\n

{\n  \"payment_method_config_id\": \"<id from the session&#x27;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\n

Send Accept-Language: es to receive decline_message in Spanish.

\n","_postman_id":"f806fbc5-df9f-42ca-92c5-4ae16ca9ed13"},{"name":"WEBHOOKS","item":[],"id":"ab9bd348-84fa-4dd0-acb9-42709f5d8408","description":"

Coralix sends a signed POST to your endpoint whenever a payment, refund or withdrawal changes state. The webhook, not the browser redirect, is the source of truth for the outcome of a payment: the redirect to your success_url only means the buyer came back.

Configure your endpoint

POST /v1/webhooks/config\n{ \"endpoint_url\": \"https://yoursite.com/webhooks/coralix\" }\n\n

Each environment has its own endpoint. Configuring with a pk_test_… key sets the test endpoint; configuring with a pk_production_… key sets the production one. Test events never reach your production endpoint.
The first time you configure an endpoint, the response includes its signing_secret (whsec_…). It is shown only once. Store it like a password.
Changing the URL later keeps the same secret and does not return it.

{\n  \"id\": \"0c3f…\",\n  \"merchant_id\": \"25e2…\",\n  \"environment\": \"test\",\n  \"endpoint_url\": \"https://yoursite.com/webhooks/coralix\",\n  \"enabled\": true,\n  \"signing_secret\": \"whsec_4f1c…\"\n}\n\n

Events

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`event_type`	When
`payment.authorized`	Funds are held, awaiting capture
`payment.success`	The money moved
`payment.failed`	Declined; carries `decline_reason` and `decline_message`
`payment.requires_action`	The buyer must complete a step, such as 3-D Secure
`payment.expired`	The session expired unpaid
`payment.refunded`	A refund was completed; carries `refund_id` and `total_refunded`
`payment.refund_failed`	A refund was rejected
`withdrawal.completed` / `withdrawal.failed` / `withdrawal.expired`	The outcome of a payout

Payload

{\n  \"id\": \"9b2d…\",\n  \"event_type\": \"payment.success\",\n  \"api_version\": \"2024-01\",\n  \"created_at\": \"2026-10-06T14:03:11.000Z\",\n  \"environment\": \"production\",\n  \"data\": {\n    \"object\": \"payment_session\",\n    \"id\": \"44b45c13-…\",\n    \"merchant_id\": \"25e2…\",\n    \"order_id\": \"order_123\",\n    \"amount\": \"15.20\",\n    \"currency\": \"USD\",\n    \"status\": \"success\",\n    \"provider_ref\": \"…\",\n    \"metadata\": { \"plan\": \"premium\" }\n  }\n}\n\n

Check environment before touching any balance. A test event must never credit real money.

Verifying the signature

Every delivery carries these headers:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Header	Content
`X-Coralix-Signature`	`t=,v1=`. After a secret rotation it can carry two `v1` values.
`X-Coralix-Event`	The `event_type`
`X-Coralix-Delivery`	The delivery id. Deduplicate on it: a delivery can arrive more than once.

To verify a delivery:

Read t and every v1 from X-Coralix-Signature.
Compute HMAC-SHA256(signing_secret, t + \".\" + raw_body) in lowercase hex. Use the raw request body exactly as received; do not parse and re-serialize it.
Accept the delivery if your value equals any of the v1 values. Compare in constant time.
Reject it if t is more than 5 minutes from your clock, to stop replays.

const crypto = require('crypto');\nfunction verifyCoralixWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {\n  const parts = signatureHeader.split(',').map((p) => p.split('='));\n  const t = Number(parts.find(([k]) => k === 't')?.[1]);\n  const signatures = parts.filter(([k]) => k === 'v1').map(([, v]) => v);\n  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;\n  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');\n  return signatures.some(\n    (sig) =>\n      sig.length === expected.length &&\n      crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex')),\n  );\n}\n// Express: keep the raw body for this route\napp.post('/webhooks/coralix', express.raw({ type: 'application/json' }), (req, res) => {\n  const ok = verifyCoralixWebhook(\n    req.body.toString('utf8'),\n    req.get('X-Coralix-Signature'),\n    process.env.CORALIX_WEBHOOK_SECRET,\n  );\n  if (!ok) return res.status(400).end();\n  const event = JSON.parse(req.body);\n  // … handle event, deduplicating on X-Coralix-Delivery\n  res.status(200).end();\n});\n\n

Rotating the secret

POST /v1/webhooks/config/rotate-secret\n\n

The response returns the new signing_secret, once, and previous_secret_expires_at. For the next 24 hours every delivery is signed with both secrets, so you can deploy the new one without losing events. After that, only the new one signs.

Rotation applies to the endpoint of the key's environment.

Retries

Any 2xx answer counts as delivered. Answer quickly and process asynchronously; the timeout is 5 seconds.
A failed delivery is retried up to 5 times in total, after 1 minute, 5 minutes, 30 minutes and 2 hours.
GET /v1/webhooks lists your deliveries, GET /v1/webhooks/{id} shows one, and POST /v1/webhooks/{id}/retry sends one again. Retrying a delivery that already succeeded returns 400 webhook_already_delivered.

\n","_postman_id":"ab9bd348-84fa-4dd0-acb9-42709f5d8408"},{"name":"REFUNDS","item":[],"id":"156cd8d0-d5e1-4e75-bf78-8f14d7cb103d","description":"

A refund gives a captured card payment back to the buyer, in full or in part. It is accepted when you request it and completed later: the issuer resolves it, sometimes days afterwards, and a webhook tells you the outcome.

Request a refund

POST /v1/transactions/{transactionId}/refund. The Idempotency-Key header is required.

{\n  \"amount\": \"5.00\",\n  \"reason\": \"Customer returned one item\"\n}\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Required	Description
`amount`	No	A string with up to two decimals. If you omit it, we refund everything still available, which is not the whole payment if part of it was already refunded.
`reason`	No	Free text, up to 500 characters, for your records

The answer is 202 Accepted with the refund in pending:

{\n  \"id\": \"7d1f…\",\n  \"transaction_id\": \"b6eee137-2b06-4054-be27-3d81a1944249\",\n  \"amount\": \"5.00\",\n  \"currency\": \"USD\",\n  \"status\": \"pending\",\n  \"reason\": \"Customer returned one item\",\n  \"provider_ref\": null,\n  \"acquirer_reference_number\": null,\n  \"failure_reason\": null,\n  \"origin\": \"api\",\n  \"resolved_at\": null,\n  \"created_at\": \"2026-10-06T14:03:11.000Z\"\n}\n

Statuses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`status`	Meaning
`pending`	Accepted, not yet sent to the issuer
`submitted`	Sent to the issuer, awaiting its answer
`unknown`	We could not confirm whether the issuer received it. It is followed up; do not request it again.
`succeeded`	The money went back to the buyer
`failed`	The issuer rejected it. The amount becomes available to refund again.

Know the outcome

When the refund is resolved we send a webhook:

payment.refunded: data.amount is this refund's amount, data.refund_id identifies it, and data.total_refunded is everything returned on the payment so far. data.acquirer_reference_number is the reference the buyer can give their bank to trace the money, when the issuer provides one.
payment.refund_failed: data.decline_reason carries the issuer's reason.

A full refund moves the payment to refunded when it completes. A partial refund does not change the payment's status.

Rules

Only captured card payments can be refunded. A payment still authorized was never captured: there is nothing to give back.
You can refund in several parts, up to the captured amount. Amounts already requested count against that limit while they are pending; if a refund fails, its amount is freed again.
A payment with a chargeback cannot be refunded: the buyer's bank already reversed it, and refunding would return the money twice.
The key identifies one attempt. Repeating a key returns that refund as it stands, failure included. A new attempt, even for the same amount, needs a new key.

Errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When
`400`	`idempotency_key_required`	The `Idempotency-Key` header is missing
`404`	`resource_not_found`	The transaction does not exist, is not yours, or is of the other environment
`409`	`idempotency_conflict`	The key was used for another amount, another transaction, or a refund that failed
`422`	`refund_amount_invalid`	`amount` is not positive
`422`	`refund_amount_exceeded`	More than what is still available, or nothing is left
`409`	`refund_amount_exceeded`	Another refund took the available amount first
`422`	`refund_not_allowed`	The payment cannot be refunded; `reason` says why: `not_card`, `not_captured`, `invalid_status`, `acquirer_reversed` or `chargebacked`

","_postman_id":"156cd8d0-d5e1-4e75-bf78-8f14d7cb103d"},{"name":"WITHDRAWALS","item":[],"id":"43b3ba03-828b-41e6-bfc1-5b00744b506f","description":"

A withdrawal (payout) sends money from your account to a card, a bank account or a wallet. It uses the same sessions as payments, with type: \"withdrawal\", but it has its own endpoint, methods and events.

\n
Withdrawals must be enabled for your account. If no withdrawal method is configured in any environment, creating a withdrawal session returns 422 no_withdrawal_rails.
\n

1. Create a withdrawal session

POST /v1/sessions

{\n  \"order_id\": \"payout_789\",\n  \"type\": \"withdrawal\",\n  \"amount\": 25.00,\n  \"currency\": \"USD\",\n  \"metadata\": { \"beneficiary\": \"user_42\" }\n}\n

The response has no checkout_url, because there is no payer to send anywhere. Instead it lists the methods you can pay out through:

{\n  \"id\": \"5a0b…\",\n  \"type\": \"withdrawal\",\n  \"status\": \"pending\",\n  \"amount\": \"25.00\",\n  \"currency\": \"USD\",\n  \"withdrawal_methods\": [\n    { \"id\": \"9c7e…\", \"display_name\": \"Bank transfer\", \"withdrawal_method_type\": \"bank\" }\n  ],\n  \"withdrawal_methods_available\": true\n}\n

withdrawal_methods_available: false means no method is configured in this environment yet.

2. Send the payout

POST /v1/sessions/{sessionId}/withdrawal. Send an Idempotency-Key: a payout repeated by mistake is money sent twice to someone else.

{\n  \"withdrawal_method_config_id\": \"9c7e…\",\n  \"withdrawal_data\": {\n    \"account_holder_name\": \"Ada Lovelace\",\n    \"account_number\": \"000123456789\",\n    \"bank_code\": \"BANKUS33\",\n    \"country\": \"US\"\n  }\n}\n

withdrawal_data depends on the type of the method you chose:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Type	Required	Optional
`card`	`card_number`, `exp_month`, `exp_year`, `holder_name`
`bank`	`account_holder_name`, `account_number`, `bank_code`, `country`	`iban`, `routing_number`, `branch_code`
`wallet`	`wallet_id`	`provider`, `phone`

If something is missing, the answer is 422 withdrawal_data_invalid with errors[], and the session stays pending.

The response:

{\n  \"id\": \"e41c…\",\n  \"session_id\": \"5a0b…\",\n  \"status\": \"success\",\n  \"amount\": \"25.00\",\n  \"currency\": \"USD\",\n  \"provider_ref\": \"PO-88213\",\n  \"error_code\": null,\n  \"created_at\": \"2026-10-06T14:03:11.000Z\"\n}\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`status`	Meaning
`success`	The money was sent
`processing`	The provider accepted it and will confirm later. This is not a failure; wait for the webhook.
`failed`	Rejected. `error_code` carries the provider's code.

3. Know the outcome

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Event	When
`withdrawal.completed`	The money was sent
`withdrawal.failed`	The payout was rejected
`withdrawal.expired`	The session was not used within 30 minutes

A withdrawal in processing does not expire: it is waiting for the provider, and its outcome always arrives by webhook.

Errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When
`422`	`no_withdrawal_rails`	Withdrawals are not configured for your account
`422`	`session_type_mismatch`	`/withdrawal` on a payment session, or `/pay` on a withdrawal session
`422`	`withdrawal_method_unavailable`	The method does not exist, is disabled, or belongs to the other environment
`422`	`withdrawal_data_invalid`	`withdrawal_data` does not match the method's type; see `errors[]`
`400`	`session_invalid_state`	The session is no longer `pending`

","_postman_id":"43b3ba03-828b-41e6-bfc1-5b00744b506f"},{"name":"ENDPOINTS","item":[{"name":"1. CREATE PAYMENT SESSION","event":[{"listen":"prerequest","script":{"id":"0d98a74a-f277-4bfa-b3c6-2e64377393c8","exec":["/*"," * Coralix gateway — HMAC request signing (Postman Pre-request Script)"," * ------------------------------------------------------------------"," * Paste this into the \"Pre-request Script\" tab of your Collection (so it runs"," * for every gateway request) or a single request."," *"," * Define these variables (Collection/Environment — keep the secret as type \"secret\"):"," * coralix_public_key e.g. pk_test_bet365"," * coralix_secret_key e.g. sk_test_bet365_secret"," *"," * It signs METHOD\\nPATH\\nTIMESTAMP\\nSHA256(body) and injects X-API-Key,"," * X-Timestamp and X-Signature automatically — no manual header rows needed."," */","//const CryptoJS = require('crypto-js');","","const publicKey = pm.variables.get('coralix_public_key');","const secretKey = pm.variables.get('coralix_secret_key');","if (!publicKey || !secretKey) {"," throw new Error('Set the coralix_public_key and coralix_secret_key variables');","}","","// METHOD (uppercase)","const method = pm.request.method.toUpperCase();","","// PATH including /v1, WITHOUT query string; resolve any {{vars}} in the path","const path = pm.variables.replaceIn('/' + pm.request.url.path.join('/'));","","// Exact body Postman will send (resolve {{vars}}); empty string for GET/DELETE","const rawBody = pm.request.body && pm.request.body.raw ? pm.request.body.raw : '';","const body = rawBody ? pm.variables.replaceIn(rawBody) : '';","","const timestamp = Math.floor(Date.now() / 1000).toString();","const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);","const canonical = [method, path, timestamp, bodyHash].join('\\n');","const signature = CryptoJS.HmacSHA256(canonical, secretKey).toString(CryptoJS.enc.Hex);","","pm.request.headers.upsert({ key: 'X-API-Key', value: publicKey });","pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });","pm.request.headers.upsert({ key: 'X-Signature', value: signature });","","// Handy while debugging (open the Postman Console):","console.log('[coralix] canonical:\\n' + canonical);","console.log('[coralix] X-Signature: ' + signature);",""],"type":"text/javascript","packages":{}}}],"id":"6cd72966-2f76-4504-8f81-45411c127079","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"order_id\": \"merchx_order_00001\",\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\": {\n \"plan\": \"premium\",\n \"user_tier\": \"vip\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.coralix.tech/v1/sessions","urlObject":{"protocol":"https","path":["v1","sessions"],"host":["api","coralix","tech"],"query":[],"variable":[]}},"response":[{"id":"637f12a3-e77a-4042-8c07-b4f165e3110a","name":"1. CREATE PAYMENT SESSION - 201","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"order_id\": \"merchx_order_00001\",\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\": {\n \"plan\": \"premium\",\n \"user_tier\": \"vip\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.coralix.tech/v1/sessions"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 13 Jul 2026 18:18:01 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"688"},{"key":"Connection","value":"keep-alive"},{"key":"x-powered-by","value":"Express"},{"key":"vary","value":"Origin"},{"key":"x-ratelimit-limit","value":"100"},{"key":"x-ratelimit-remaining","value":"99"},{"key":"x-ratelimit-reset","value":"60"},{"key":"x-trace-id","value":"4973968a-ec1b-45ba-9e7d-94bc7986bd90"},{"key":"etag","value":"W/\"2b0-HDEAqfmEITCkKSwq2X/XDsVKiRc\""},{"key":"Server","value":"cloudflare"},{"key":"x-do-app-origin","value":"c322b499-09e8-4d15-94e7-8d66106abf95"},{"key":"Cache-Control","value":"private"},{"key":"x-do-orig-status","value":"201"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"set-cookie","value":"__cf_bm=9ER39WbIDfLB6RodOD.c0U0QAdJZZVzV05dCM4MdAS0-1783966681.3679717-1.0.1.1-ajZAeMf1QLSjpYoUB68CsmbiurW2dI.usJxJJXL1K_kmZcz6uPhR3iDl0fgTFLO5OiPxFyG8Hzr5ERCUIXiaEDbCHen_tw.MDT.jKjCp21AoxOBDAS5GGfzJQsZEOekg; HttpOnly; SameSite=None; Secure; Path=/; Domain=api.coralix.tech; Expires=Mon, 13 Jul 2026 18:48:01 GMT"},{"key":"CF-RAY","value":"a1aa49ae8e3bc646-SJO"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"44b45c13-8b0e-4697-af40-e1ae83d8c1f9\",\n \"merchant_id\": \"25e2cf6c-21bd-4e5e-bb7d-7f445fe80cbf\",\n \"order_id\": \"merchx_order_00001\",\n \"amount\": \"15.20\",\n \"currency\": \"USD\",\n \"status\": \"success\",\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\": {\n \"plan\": \"premium\",\n \"user_tier\": \"vip\"\n },\n \"expires_at\": \"2026-07-13T18:23:59.200Z\",\n \"created_at\": \"2026-07-13T17:53:59.204Z\",\n \"checkout_url\": \"http://localhost:3000/checkout/44b45c13-8b0e-4697-af40-e1ae83d8c1f9\",\n \"payment_methods\": [\n {\n \"id\": \"c0658ab5-0592-49e4-a6c4-b469b88091c3\",\n \"display_name\": \"Tarjeta (MockCard)\",\n \"payment_method_type\": \"card\"\n }\n ]\n}"},{"id":"65b232cb-b903-45d1-8d9a-2b3d13d596a2","name":"1. CREATE PAYMENT SESSION - 401","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"order_id\": \"merchx_order_00002\",\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\": {\n \"plan\": \"premium\",\n \"user_tier\": \"vip\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://api.coralix.tech/v1/sessions"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 13 Jul 2026 18:20:40 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"126"},{"key":"Connection","value":"keep-alive"},{"key":"x-powered-by","value":"Express"},{"key":"vary","value":"Origin"},{"key":"x-ratelimit-limit","value":"100"},{"key":"x-ratelimit-remaining","value":"98"},{"key":"x-ratelimit-reset","value":"33"},{"key":"etag","value":"W/\"7e-Gy6ZYenT4Ac+RqTLTJ1Xa1y+Abc\""},{"key":"Server","value":"cloudflare"},{"key":"x-do-app-origin","value":"c322b499-09e8-4d15-94e7-8d66106abf95"},{"key":"Cache-Control","value":"private"},{"key":"x-do-orig-status","value":"401"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"CF-RAY","value":"a1aa4d8fb81fc646-SJO"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"error_code\": \"invalid_authentication\",\n \"message\": \"Invalid authentication\",\n \"request_id\": \"b31ef3b8-5445-4046-abc1-3292389d6867\"\n}"}],"_postman_id":"6cd72966-2f76-4504-8f81-45411c127079"},{"name":"2. PAY PAYMENT SESSION","event":[{"listen":"prerequest","script":{"id":"ab43e383-fe92-40b6-a314-25db2cfc240c","exec":["/*"," * Coralix gateway — HMAC request signing (Postman Pre-request Script)"," * ------------------------------------------------------------------"," * Paste this into the \"Pre-request Script\" tab of your Collection (so it runs"," * for every gateway request) or a single request."," *"," * Define these variables (Collection/Environment — keep the secret as type \"secret\"):"," * coralix_public_key e.g. pk_test_bet365"," * coralix_secret_key e.g. sk_test_bet365_secret"," *"," * It signs METHOD\\nPATH\\nTIMESTAMP\\nSHA256(body) and injects X-API-Key,"," * X-Timestamp and X-Signature automatically — no manual header rows needed."," */","//const CryptoJS = require('crypto-js');","","const publicKey = pm.variables.get('coralix_public_key');","const secretKey = pm.variables.get('coralix_secret_key');","if (!publicKey || !secretKey) {"," throw new Error('Set the coralix_public_key and coralix_secret_key variables');","}","","// METHOD (uppercase)","const method = pm.request.method.toUpperCase();","","// PATH including /v1, WITHOUT query string; resolve any {{vars}} in the path","const path = pm.variables.replaceIn('/' + pm.request.url.path.join('/'));","","// Exact body Postman will send (resolve {{vars}}); empty string for GET/DELETE","const rawBody = pm.request.body && pm.request.body.raw ? pm.request.body.raw : '';","const body = rawBody ? pm.variables.replaceIn(rawBody) : '';","","const timestamp = Math.floor(Date.now() / 1000).toString();","const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Hex);","const canonical = [method, path, timestamp, bodyHash].join('\\n');","const signature = CryptoJS.HmacSHA256(canonical, secretKey).toString(CryptoJS.enc.Hex);","","pm.request.headers.upsert({ key: 'X-API-Key', value: publicKey });","pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });","pm.request.headers.upsert({ key: 'X-Signature', value: signature });","","// Handy while debugging (open the Postman Console):","console.log('[coralix] canonical:\\n' + canonical);","console.log('[coralix] X-Signature: ' + signature);",""],"type":"text/javascript","packages":{}}}],"id":"6b64dbef-981b-43bf-a968-1e99162eead8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer pk_test_bet365:sk_test_bet365_secret","type":"text"}],"body":{"mode":"raw","raw":"{\n \"payment_method_config_id\": \"c0658ab5-0592-49e4-a6c4-b469b88091c3\",\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 }","options":{"raw":{"language":"json"}}},"url":"https://api.coralix.tech/v1/sessions/44b45c13-8b0e-4697-af40-e1ae83d8c1f9/pay","urlObject":{"protocol":"https","path":["v1","sessions","44b45c13-8b0e-4697-af40-e1ae83d8c1f9","pay"],"host":["api","coralix","tech"],"query":[],"variable":[]}},"response":[{"id":"0b98c517-fa5e-4f28-8587-5d865086daf4","name":"2. PAY PAYMENT SESSION - 200","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer pk_test_bet365:sk_test_bet365_secret","type":"text"}],"body":{"mode":"raw","raw":"{\n \"payment_method_config_id\": \"c0658ab5-0592-49e4-a6c4-b469b88091c3\",\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 }","options":{"raw":{"language":"json"}}},"url":"https://api.coralix.tech/v1/sessions/ec00c38e-e3d7-4943-9ecd-172835c333bf/pay"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 13 Jul 2026 18:31:14 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"x-powered-by","value":"Express"},{"key":"vary","value":"Origin"},{"key":"x-ratelimit-limit","value":"100"},{"key":"x-ratelimit-remaining","value":"99"},{"key":"x-ratelimit-reset","value":"60"},{"key":"x-trace-id","value":"83e63750-dff0-4281-ab73-47cfc029214f"},{"key":"etag","value":"W/\"b1-hsGqSNqcDBBJP3JG75MR04cSduk\""},{"key":"Server","value":"cloudflare"},{"key":"x-do-app-origin","value":"c322b499-09e8-4d15-94e7-8d66106abf95"},{"key":"Cache-Control","value":"private"},{"key":"x-do-orig-status","value":"200"},{"key":"cf-cache-status","value":"DYNAMIC"},{"key":"Content-Encoding","value":"br"},{"key":"CF-RAY","value":"a1aa5d089e17eb6f-SJO"},{"key":"alt-svc","value":"h3=\":443\"; ma=86400"}],"cookie":[],"responseTime":null,"body":"{\n \"session_id\": \"ec00c38e-e3d7-4943-9ecd-172835c333bf\",\n \"transaction_id\": \"b6eee137-2b06-4054-be27-3d81a1944249\",\n \"status\": \"success\",\n \"provider_ref\": \"MOCKCARD-1783967474304-ec00c38e\"\n}"}],"_postman_id":"6b64dbef-981b-43bf-a968-1e99162eead8"}],"id":"298c6e0f-3b58-490b-a923-225dcc17b0c5","description":"

Every endpoint below is under https://api.coralix.tech, must be signed (see Authentication), and acts only on your own resources in the environment of your key. A resource of another account or of the other environment answers 404, the same as one that does not exist.

Sessions

Create a session

POST /v1/sessions → 201. Accepts Idempotency-Key.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Type	Required	Description
`order_id`	string (1 to 200)	Yes	Your reference. Unique per account and environment.
`amount`	number	Yes	Greater than zero, in major units (`15.20`)
`currency`	string	Yes	ISO 4217 code
`type`	`payment` \| `withdrawal`	No	Default `payment`. See Withdrawals.
`customer_id`	string	No	Your customer reference
`success_url`, `failure_url`, `cancel_url`	URL	No	Where the buyer returns after the hosted page or 3-D Secure
`metadata`	object	No	Free key-value data, returned in the session and in webhooks

Response:

{\n  \"id\": \"44b45c13-8b0e-4697-af40-e1ae83d8c1f9\",\n  \"merchant_id\": \"25e2cf6c-21bd-4e5e-bb7d-7f445fe80cbf\",\n  \"environment\": \"test\",\n  \"order_id\": \"order_123\",\n  \"type\": \"payment\",\n  \"amount\": \"15.20\",\n  \"currency\": \"USD\",\n  \"status\": \"pending\",\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\" },\n  \"expires_at\": \"2026-10-06T14:33:11.000Z\",\n  \"created_at\": \"2026-10-06T14:03:11.000Z\",\n  \"checkout_url\": \"https://<checkout-host>/checkout/44b45c13-8b0e-4697-af40-e1ae83d8c1f9\",\n  \"payment_methods\": [\n    { \"id\": \"c0658ab5-0592-49e4-a6c4-b469b88091c3\", \"display_name\": \"Card\", \"payment_method_type\": \"card\" }\n  ]\n}\n

Errors: 400 validation_failed, 409 idempotency_conflict (same order_id, different amount or currency; carries session_id), 422 no_withdrawal_rails.

Get a session

GET /v1/sessions/{sessionId} → 200, the same shape as above. Errors: 404 session_not_found.

Get a session's status

GET /v1/sessions/{sessionId}/status → 200

{\n  \"status\": \"requires_action\",\n  \"session_id\": \"44b45c13-…\",\n  \"order_id\": \"order_123\",\n  \"action\": { \"type\": \"redirect\", \"url\": \"…\", \"method\": \"POST\", \"params\": { }, \"expires_at\": \"…\" },\n  \"action_expires_at\": \"2026-10-06T14:18:11.000Z\",\n  \"transactions\": [\n    {\n      \"id\": \"b6eee137-…\",\n      \"session_id\": \"44b45c13-…\",\n      \"merchant_id\": \"25e2…\",\n      \"amount\": \"15.20\",\n      \"currency\": \"USD\",\n      \"status\": \"requires_action\",\n      \"provider_id\": \"…\",\n      \"provider_ref\": \"…\",\n      \"settled_at\": null,\n      \"created_at\": \"…\"\n    }\n  ]\n}\n

action is null unless a payment is waiting for the buyer. Use this endpoint to resume a payment whose /pay response you lost.

Pay a session

POST /v1/sessions/{sessionId}/pay → 200. Accepts Idempotency-Key and Accept-Language.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Required	Description
`payment_method_config_id`	Yes	An `id` from the session's `payment_methods`
`payment_data`	Yes	The payment details, by method type (below)

payment_data for card:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Required	Rule
`card_number`	Always	13 to 19 digits; spaces and hyphens are removed
`exp_month`	Always	1 to 12
`exp_year`	Always	Four digits (a two-digit year is read as 20xx); not expired
`cvv`	Always	3 or 4 digits
`holder_name`	Always	1 to 100 characters
`first_name`, `last_name`, `email`, `phone`	If the method requires contact data	`phone` in E.164 (`+34600123456`)
`address_line1`, `city`, `state`, `postal_code`, `country`	If the method requires billing data	`country` is ISO 3166-1 alpha-2
`ip_address`	If the method requires fraud data	The buyer's IP address
`address_line2`, `date_of_birth`	Never	`date_of_birth` as `YYYY-MM-DD`

Unknown keys in payment_data are ignored. Which optional groups a method requires depends on its configuration; if one is missing, the answer is 422 payer_data_required with missing_fields[]. Sending them always is harmless and avoids that error.

Responses: see Payment Flow → Process the payment.

Errors: 400 session_expired, 400 session_invalid_state, 422 session_type_mismatch, 422 payment_method_unavailable, 422 invalid_payment_data (errors[]), 422 payer_data_required (missing_fields[]), 502 provider_error.

Send a payout

POST /v1/sessions/{sessionId}/withdrawal → 200. See Withdrawals.

Transactions

List transactions

GET /v1/transactions?status=success&page=1&limit=20 → 200. limit is 1 to 100, default 20. Newest first.

{\n  \"data\": [\n    {\n      \"id\": \"b6eee137-…\",\n      \"session_id\": \"44b45c13-…\",\n      \"merchant_id\": \"25e2…\",\n      \"amount\": \"15.20\",\n      \"currency\": \"USD\",\n      \"status\": \"success\",\n      \"provider_id\": \"…\",\n      \"provider_ref\": \"…\",\n      \"settled_at\": \"2026-10-06T14:03:12.000Z\",\n      \"created_at\": \"2026-10-06T14:03:11.000Z\"\n    }\n  ],\n  \"page\": 1,\n  \"limit\": 20\n}\n

Get a transaction

GET /v1/transactions/{transactionId} → 200, one element of the list above. Errors: 404 resource_not_found.

Get a transaction's attempts

GET /v1/transactions/{transactionId}/attempts → 200. Accepts Accept-Language.

[\n  {\n    \"id\": \"…\",\n    \"transaction_id\": \"b6eee137-…\",\n    \"status\": \"failed\",\n    \"error_code\": \"insufficient_funds\",\n    \"latency_ms\": 412,\n    \"created_at\": \"…\",\n    \"decline_reason\": \"insufficient_funds\",\n    \"decline_message\": \"Insufficient funds. Please try with another card.\"\n  }\n]\n

Capture an authorized payment

POST /v1/transactions/{transactionId}/capture → 200. Accepts Idempotency-Key. Only for accounts that capture manually: it turns an authorized payment into success.

{ \"id\": \"b6eee137-…\", \"session_id\": \"44b45c13-…\", \"status\": \"success\", \"provider_ref\": \"…\", \"settled_at\": \"…\" }\n

Capturing a payment that is already captured answers 200 with its current state. Errors: 409 capture_not_allowed (with status), 409 authorization_expired, 502 provider_error.

Refund a payment

POST /v1/transactions/{transactionId}/refund → 202. Idempotency-Key is required. See Refunds.

Your account

Get your profile

GET /v1/merchants/me → 200

{\n  \"id\": \"25e2…\",\n  \"name\": \"Your Shop\",\n  \"parent_merchant_id\": null,\n  \"country_code\": [\"US\"],\n  \"timezone\": \"America/New_York\",\n  \"base_currency\": [\"USD\"],\n  \"status\": \"active\",\n  \"created_at\": \"…\",\n  \"environment\": \"test\"\n}\n

environment is the environment of the key you used, which helps when debugging which key is in use.

List your payment methods

GET /v1/merchants/me/payment-methods → 200. The methods available in your key's environment, in display order, with the same shape as a session's payment_methods.

API keys

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Request	Response
`GET /v1/merchants/me/api-keys`	`200`, `[{ id, public_key, environment, last_used_at, revoked_at, created_at }]`
`POST /v1/merchants/me/api-keys`	`201`, `{ id, public_key, environment, created_at, secret_key }`. `secret_key` is shown only this once.
`DELETE /v1/merchants/me/api-keys/{id}`	`200`, `{ id, revoked_at }`

A key lists, creates and revokes keys of its own environment only. To rotate: create a new pair, deploy it, then revoke the old one.

Settlements

Settlement batches exist only in production. With a test key, the list is empty and a batch answers 404.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Request	Response
`GET /v1/settlements`	`200`, a list of batches, newest first
`GET /v1/settlements/{id}`	`200`, one batch
`GET /v1/settlements/{id}/export`	`200`, the same batch (JSON)

{\n  \"id\": \"…\",\n  \"merchant_id\": \"25e2…\",\n  \"period_start\": \"2026-09-01\",\n  \"period_end\": \"2026-09-30\",\n  \"gross_amount\": \"10000.00\",\n  \"fees_amount\": \"300.00\",\n  \"refunds_amount\": \"120.00\",\n  \"chargebacks_amount\": \"0.00\",\n  \"net_amount\": \"9580.00\",\n  \"currency\": \"USD\",\n  \"status\": \"paid\",\n  \"paid_at\": \"2026-10-02T00:00:00.000Z\",\n  \"created_at\": \"2026-10-01T00:00:00.000Z\"\n}\n

Webhooks

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Request	Description
`POST /v1/webhooks/config`	Set your endpoint for this environment. The first time, returns `signing_secret`.
`POST /v1/webhooks/config/rotate-secret`	New signing secret; the old one keeps signing for 24 hours
`GET /v1/webhooks?page=1&limit=20`	Your deliveries in this environment
`GET /v1/webhooks/{id}`	One delivery
`POST /v1/webhooks/{id}/retry`	Send a delivery again. `400 webhook_already_delivered` if it already succeeded.

A delivery record:

{\n  \"id\": \"…\",\n  \"event_type\": \"payment.success\",\n  \"transaction_id\": \"b6eee137-…\",\n  \"endpoint_url\": \"https://yoursite.com/webhooks/coralix\",\n  \"attempts_count\": 2,\n  \"last_response_status\": 503,\n  \"next_retry_at\": \"…\",\n  \"delivered_at\": null,\n  \"created_at\": \"…\",\n  \"payload\": { \"...\": \"the exact body that was sent\" }\n}\n

See Webhooks for events, payloads and signature verification.

Rate limits

Up to 100 requests per minute per IP address. Beyond that the answer is 429 rate_limited, with a Retry-After header saying how many seconds to wait.

\n","_postman_id":"298c6e0f-3b58-490b-a923-225dcc17b0c5"},{"name":"ERROR CODES","item":[],"id":"125e4f76-9c67-444d-ad34-9334d0d36cfd","description":"

Every error response has the same shape, and every one carries a specific error_code. Branch your logic on error_code, never on message: the code is stable, the wording is not.

{\n  \"error_code\": \"refund_not_allowed\",\n  \"message\": \"A chargeback is recorded against this payment; refunding it would cost the merchant the amount twice\",\n  \"request_id\": \"6f1c2e0a-3b5d-4f8e-9a71-2c4d5e6f7a8b\",\n  \"reason\": \"chargebacked\"\n}\n

message is always a string, meant for your logs, not for your buyer.
request_id identifies the request in our logs. Quote it when contacting support. If you send an X-Request-Id header, we use your value.
Some codes carry extra fields, listed below.

\n
Declines are not errors. POST /v1/sessions/{sessionId}/pay answers a declined payment with 200 and status: \"failed\". See Decline Reasons Reference.
\n

Authentication

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When
`400`	`invalid_request`	`X-Timestamp` is not Unix seconds, or `X-Signature` is not 64 lowercase hex characters
`401`	`invalid_authentication`	A header is missing, the API key is unknown or revoked, or the signature does not match. These cases are deliberately not told apart.
`401`	`timestamp_out_of_window`	`X-Timestamp` is more than ±300 seconds from server time

Request shape and limits

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When	Extra fields
`400`	`validation_failed`	The body is missing a field, has a wrong type, or contains a field the endpoint does not accept	`errors[]`: one line per failed constraint
`404`	`resource_not_found`	The transaction, settlement batch, webhook delivery or API key does not exist, is not yours, or belongs to the other environment
`429`	`rate_limited`	Too many requests. The `Retry-After` header says how many seconds to wait.

Sessions and payments

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When	Extra fields
`404`	`session_not_found`	The session does not exist, is not yours, or belongs to the other environment
`400`	`session_expired`	The session passed its 30-minute expiry
`400`	`session_invalid_state`	The session is no longer `pending`, for example because it was already paid
`409`	`idempotency_conflict`	The `order_id` was already used with a different `amount` or `currency`	`session_id`: the session that `order_id` belongs to
`409`	`idempotency_conflict`	The `Idempotency-Key` was already used for a different request (another body or endpoint)
`409`	`idempotency_in_progress`	A request with the same `Idempotency-Key` is still running. Retry shortly with the same key.
`503`	`idempotency_store_unavailable`	The `Idempotency-Key` cannot be honoured right now. The request was not executed; retry shortly.
`422`	`session_type_mismatch`	`/pay` was called on a withdrawal session, or `/withdrawal` on a payment session
`422`	`payment_method_unavailable`	The `payment_method_config_id` is not available to you in this environment
`422`	`invalid_payment_data`	`payment_data` does not match the format for this payment method	`errors[]`
`422`	`payer_data_required`	Payer fields required by this payment method are missing	`missing_fields[]`
`409`	`capture_not_allowed`	The transaction is not in `authorized` and cannot be captured	`status`
`409`	`authorization_expired`	The authorization expired before capture
`502`	`provider_error`	The payment provider failed

Withdrawals

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When	Extra fields
`422`	`no_withdrawal_rails`	Your account has no withdrawal methods in any environment
`422`	`withdrawal_method_unavailable`	The `withdrawal_method_config_id` is not available to you
`422`	`withdrawal_data_invalid`	`withdrawal_data` does not match the selected method	`errors[]`

Refunds

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When	Extra fields
`400`	`idempotency_key_required`	The `Idempotency-Key` header is missing. It is required on refunds.
`409`	`idempotency_conflict`	The `Idempotency-Key` was already used for another amount or another transaction, or for a refund that failed. A new attempt needs a new key.
`422`	`refund_amount_invalid`	`amount` is not positive
`422`	`refund_amount_exceeded`	`amount` is more than what is still available to refund, or nothing is left
`409`	`refund_amount_exceeded`	Another refund took the available amount first
`422`	`refund_not_allowed`	The transaction cannot be refunded at all	`reason`, one of the values below

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`reason`	Meaning
`not_card`	Only card payments can be refunded
`not_captured`	The payment was authorized and never captured: there is nothing to give back. Release the authorization instead.
`invalid_status`	The payment did not succeed, so there is no money to return
`acquirer_reversed`	The acquirer already reversed this payment
`chargebacked`	A chargeback is recorded against this payment

Webhooks

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When
`400`	`webhook_already_delivered`	You asked to retry a delivery that already succeeded

Server errors

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`	When
`500`	`internal_error`	An unexpected error on our side. Retry with the same `Idempotency-Key`, and quote the `request_id` if it persists.
`500`	`adapter_not_found`	A configuration error on our side. Contact support with the `request_id`.

Other codes

These come from rejections that have no more specific code:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

HTTP	`error_code`
`403`	`forbidden`
`409`	`conflict`
`422`	`unprocessable_request`

","_postman_id":"125e4f76-9c67-444d-ad34-9334d0d36cfd"},{"name":"DECLINE REASONS REFERENCE","item":[],"id":"ab621510-1780-476f-95ad-66f27b31afbe","description":"

When a payment is declined, POST /v1/sessions/{sessionId}/pay answers 200 with status: \"failed\", a machine-readable decline_reason and a buyer-facing decline_message. The same two fields appear on GET /v1/transactions/{id}/attempts and in the payment.failed webhook.

Branch your logic on decline_reason, which is stable. Show decline_message to the buyer, but never parse it: its wording can change.
Language: decline_message is in English by default. Send Accept-Language: es (any es-* value works) to receive it in Spanish on /pay and /attempts. Webhooks always carry the English message.
Any provider code we do not recognize maps to unknown_decline, so your integration must handle that value.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

`decline_reason`	Category	`decline_message` (en)
`insufficient_funds`	card	Insufficient funds. Please try with another card.
`invalid_card`	card	Invalid card. Please check your card details and try again.
`expired_card`	card	Your card has expired. Please use a valid card.
`incorrect_cvv`	card	Incorrect CVV. Please check your security code.
`do_not_honor`	issuer	Your bank declined the payment. Please contact your bank.
`card_blocked`	issuer	Card blocked. Please contact your bank.
`lost_card`	issuer	Card reported as lost.
`stolen_card`	issuer	Card reported as stolen.
`limit_exceeded`	issuer	Credit limit exceeded.
`card_velocity_exceeded`	issuer	Too many recent transactions. Please wait and try again.
`invalid_amount`	gateway	Invalid amount.
`currency_not_supported`	gateway	Currency not supported by this card.
`duplicate_transaction`	gateway	Duplicate transaction.
`fraud_suspected`	risk	Transaction declined for security reasons.
`3ds_failed`	3ds	Authentication failed. Please try again.
`3ds_not_supported`	3ds	Your bank does not support the required authentication.
`bank_unreachable`	network	Your bank is currently unavailable. Please try again later.
`processing_error`	network	Processing error. Please try again.
`country_not_supported`	compliance	Country not supported for this payment method.
`card_type_not_supported`	compliance	Card type not accepted.
`amount_too_small`	limits	Amount is below the minimum allowed.
`unknown_decline`	fallback	Payment not processed. Please contact your bank.

Notes

The Category column groups the reasons for your own reporting. It is not returned by the API.
Reasons in the network category are usually temporary: it is reasonable to let the buyer try again. Reasons in card, issuer and risk will not change with a retry of the same card.
A failed refund reports its own reason in the payment.refund_failed webhook. That value comes from the provider and may not be one of the codes above.

\n","_postman_id":"ab621510-1780-476f-95ad-66f27b31afbe"},{"name":"GOING LIVE","item":[],"id":"b14ca743-0bce-493a-b0b9-86e22b006734","description":"

Before you switch from pk_test_… to pk_production_…, go through this list. Each item is something that works in testing and fails, or costs money, in production.

Keys and security

Your production secret key is stored server-side only, in a secret manager or environment variable. It is never in source control, a mobile app or a browser.
You call the API only from your backend.
Your servers' clocks are synchronized (NTP). A drift beyond 300 seconds rejects every request.
You know how to rotate keys: create a new pair, deploy it, revoke the old one.

Payments

Every order_id is unique per purchase attempt. After a decline, a new attempt uses a new order_id.
Every POST sends an Idempotency-Key, and a retry after a timeout reuses the same key.
You branch on status and decline_reason, never on message text, and you handle unknown_decline.
You handle requires_action: 3-D Secure is common in production even if your tests rarely hit it.
If your account captures manually, you capture authorized payments before the authorization expires.
If you collect card data yourself, you are PCI DSS compliant. Otherwise you use checkout_url.

Webhooks

You configured a webhook endpoint with your production key. The test endpoint is separate and is not copied over.
You stored the production signing_secret, and you verify the signature of every delivery.
You check environment in the payload before touching any balance.
You fulfil orders from the webhook, not from the buyer's redirect to success_url.
You deduplicate on X-Coralix-Delivery: a delivery can arrive more than once.
Your endpoint answers 2xx within 5 seconds and does its work asynchronously.

Operations

You log the request_id of every error, to quote it to support.
You handle 429 rate_limited by waiting Retry-After seconds.
You retry 5xx errors and 503 idempotency_store_unavailable with backoff and the same Idempotency-Key.
You tested a refund and, if you use them, a withdrawal, including the processing case.

\n","_postman_id":"b14ca743-0bce-493a-b0b9-86e22b006734"}],"event":[{"listen":"prerequest","script":{"id":"7be3f853-e74a-4edc-9e3d-b1f091241cb9","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"e9e53639-69b5-4e9d-b713-7e34e863026d","type":"text/javascript","packages":{},"exec":[""]}}],"variable":[{"key":"coralix_public_key","value":"pk_test_fecc9278094f9fa2b24197fed9d6647f4","type":"string"},{"key":"coralix_secret_key","value":"sk_test_50cba8238dae1f7211bfbd6d8e165dc85ef96b52b7d17f9f4","type":"string"}]}

Base URL

Environments

Conventions

How this documentation is organized

1. Your keys

2. Required headers

3. Building X-Signature

Worked example

4. Timestamp and replay protection

5. Reference implementations

Node.js

Postman pre-request script

A full signed request

6. Idempotency-Key

7. Authentication errors

1. Create a session

2. Process the payment

3. 3-D Secure and other actions

4. Know the outcome

5. Session and transaction statuses

6. Idempotency

7. Errors

Approved card

Declined cards

3-D Secure

Invalid card data

Withdrawals

Example: approved payment

Configure your endpoint

Events

Payload

Verifying the signature

Rotating the secret

Retries

Request a refund

Statuses

Know the outcome

Rules

Errors

1. Create a withdrawal session

2. Send the payout

3. Know the outcome

Errors

Sessions

Create a session

Get a session

Get a session's status

Pay a session

Send a payout

Transactions

List transactions

Get a transaction

Get a transaction's attempts

Capture an authorized payment

Refund a payment

Your account

Get your profile

List your payment methods

API keys

Settlements

Webhooks

Rate limits

Authentication

Request shape and limits

Sessions and payments

Withdrawals

Refunds

Webhooks

Server errors

Other codes

Keys and security

Payments

Webhooks

Operations

3. Building `X-Signature`

6. `Idempotency-Key`