Build on Payblis

1 Create a merchant account (sandbox + live API keys).
2 Set your USDC Polygon wallet in Settings → Crypto Wallet.
3 POST /api/sandbox/payment/create → open checkout_url.
4 POST /api/sandbox/payment/{RefOrder}/complete to simulate success.

Authentication

X-API-Key: YOUR_API_KEY

Sandbox key → /api/sandbox/… · Live key → /api/…. Do not pass ?environment=.

All POST requests also need the secret key (sk_…):

X-Payblis-Timestamp: <unix seconds>
X-Payblis-Signature: <hmac-sha256 hex of "timestamp.body">
X-Payblis-Nonce: <unique per request>

Empty body → sign timestamp + '.'. In the console, set API key + secret under Environment (auto-signed on Send).

Webhooks

Payblis POSTs JSON to ipnURL (or your default webhook URL). Verify with HMAC-SHA256 of the body without the signature field.

X-Payblis-Signature: <hex hmac-sha256>

Payment events: payment.completed, payment.failed, payment.cancelled, payment.expired. Compact payload: event, merchant_reference, amount, currency, status, environment, signature.

After a successful live PayGate settlement, you also receive settlement.completed with net crypto amount, wallet, network, txid, and environment.

POST your endpoint Outbound

Payment webhook fields

Field	Type	Description
`event`	string	e.g. `payment.completed`
`merchant_reference`	string	Your order reference (`RefOrder` at create)
`amount`	string	Fiat amount (2 decimals), e.g. `"14.17"`
`currency`	string	Original fiat currency (`EUR` / `USD` / `CAD`)
`status`	string	`SUCCESS`, `FAILED`, `CANCELLED`, or `EXPIRED`
`environment`	string	`sandbox` / `live`
`signature`	string	HMAC hex

{
  "event": "payment.completed",
  "merchant_reference": "Order-xxxxxxx",
  "amount": "14.17",
  "currency": "USD",
  "status": "SUCCESS",
  "environment": "sandbox",
  "signature": "…"
}

settlement.completed fields

Field	Type	Description
`event`	string	`settlement.completed`
`merchant_reference`	string	Linked payment order (`RefOrder`)
`amount_crypto`	string	Net crypto amount credited to your wallet
`crypto_currency`	string	e.g. `USDC`
`wallet_address`	string	Destination payout wallet
`network`	string	`polygon`
`txid_out`	string	Outbound chain transaction id
`environment`	string	`sandbox` / `live`
`signature`	string	HMAC hex

{
  "event": "settlement.completed",
  "merchant_reference": "Order-xxxxxxx",
  "amount_crypto": "9.5",
  "crypto_currency": "USDC",
  "wallet_address": "0x…",
  "network": "polygon",
  "txid_out": "…",
  "environment": "live",
  "signature": "…"
}

Base URL

Production

https://payblis.com

Local: http://localhost:8888/payblis_app · Paths: /api/sandbox/… or /api/…

Payments

POST /api/payment/create Auth

Returns RefOrder + checkout_url. Sandbox: /api/sandbox/payment/create.

Body

Field	Type	Description
`amount`	number	Fiat amount (> 0)
`currency`	string	`EUR`, `USD`, `CAD`
`product_name`	string	Product label
`method`	string	Optional. Preselects the checkout method tab. Alias: `payment_method`. See Payment methods.
`provider`	string	Optional. Provider slug.
`RefOrder`	string	Unique order reference
`Customer_Email`	string	Buyer email
`Customer_Name`	string	First name
`Customer_LastName`	string	Last name
`country`	string	ISO country
`store_name`	string	Store name
`urlOK`	url	Success redirect
`urlKO`	url	Failure redirect
`ipnURL`	url	Webhook URL

Payment methods

Codes accepted by method / payment_method on create. The checkout shows the same list (methods without a routed provider for that session are hidden).

Available methods

Code	Checkout label	Notes
`credit_cards`	Credit cards	Visa, Mastercard, Amex
`apple_pay`	Apple Pay	Pay with Apple Pay
`google_pay`	Google Pay	Pay with Google Pay
`paypal`	PayPal	Pay with PayPal
`revolut_pay`	Revolut Pay	Pay with Revolut
`bank_transfer`	Bank transfer	SEPA, wire transfer
`open_banking`	Open banking	Instant bank payment
`cash_app`	Cash App	Pay with Cash App
`ideal`	iDEAL	Pay with iDEAL
`klarna`	Klarna	Pay later with Klarna

If method is set, checkout opens on that tab when a provider is available for it; the buyer can still switch. Omit method to let the buyer choose (first available method is selected by default).

If provider is set, checkout shows only that provider. Create fails with code: provider_not_available (or provider_not_found) and a reason such as currency_not_supported, amount_outside_limits, amount_outside_currency_limits, country_not_supported, method_not_supported, or provider_disabled_by_merchant.

GET /api/payment/{RefOrder} Auth

RefOrder, amount, status, environment, timestamps.

GET /api/payment/{RefOrder}/status Auth

RefOrder + status.

POST /api/payment/{RefOrder}/cancel Auth

Cancel a non-terminal payment. Requires HMAC headers.

GET /api/transactions Auth

Query

Field	Type	Description
`page`	integer	Default 1
`per_page`	integer	Default 20, max 100
`status`	string	Optional filter
`q`	string	Search RefOrder / email

Balance

GET /api/balance Auth

Pending / in-settlement / paid-out.

Sandbox tools

POST /api/sandbox/payment/{RefOrder}/complete Auth

Mark sandbox payment completed. HMAC required.

POST /api/sandbox/payment/{RefOrder}/fail Auth

Mark sandbox payment failed. HMAC required.

POST /api/webhook/test Auth

Send webhook.test to your URL. Body: optional url, event.