Merchant credentials Authentication Plugin Connect Checkout Sessions Payment Links Payments Webhooks Settlements Production Errors

Yera Connect API v1

API reference for Yera Connect checkout, links, payments, and webhooks.

Use the actual implemented API routes from this codebase. Examples use Bearer authentication, Yera Connect key prefixes, and the live response shape returned by the current handlers.

Live base URL

https://app.yeraconnect.io/api/v1

Checkout host

https://checkout.yeraconnect.io

Merchant credentials

Every merchant gets one simple credential set, shown in Dashboard -> Developers -> API Credentials.

Merchant ID (MER_...): identifies your merchant account. Copy-only — it never regenerates.

Yera Live API Key (yera_live_...): for real payments. Locked until your account is approved; issued automatically on approval.

Security Code (XXXXXX-XXXXXX-XXXXXX-XXXXXX): only used when connecting or reconnecting a website plugin. Never required on payment API requests.

Regeneration: Live API keys can be regenerated from the dashboard — the old key keeps working for 24 hours so you can update integrations. Security Code regeneration replaces the old code immediately; already-connected websites keep working.

Legacy yera_test_sk_ / yera_live_sk_ / pk keys are retired and no longer authenticate. Migrate any old integration to your unified Yera API Key.

Authentication

All Yera Connect API requests require authentication using your Yera API Key from a server environment.

Send your key as Authorization: Bearer <api_key>.

Only yera_live_ keys authenticate new requests. Historical Test keys cannot be reused.

Live keys are rejected until the merchant account is approved for live payments.

Use the Live key only from an approved production server environment.

Never expose API keys in browser code, mobile apps, or public repositories.

Authenticated request

bash

curl https://app.yeraconnect.io/api/v1/checkout/sessions \
  -H "Authorization: Bearer yera_live_your_api_key" \
  -H "Content-Type: application/json"

Response codes

200Success

201Created

400Bad Request

401Unauthorized

403Forbidden

404Not Found

409Conflict

422Validation Error

429Rate Limited

500Server Error

Plugin Connect

The plugin connection handshake used by Yera plugins (WooCommerce v1.1.0 and later) when a merchant saves plugin settings. It validates the merchant credentials, registers the website, and auto-registers the webhook endpoint in one call.

POST/plugin/connectImplemented

Connect a website

Validates Merchant ID + Yera API Key + Security Code, creates or updates the site connection for the website, and returns the webhook signing secret the plugin should store. Reconnecting the same website updates the existing connection and returns the same secret.

Auth

Bearer API key

Scope

plugin:connect

Handler

apps/web/app/api/v1/plugin/connect/route.ts

Supported platforms: woocommerce, shopify, magento, prestashop, opencart, custom.
The API key travels in the request body for this endpoint. Only a Yera Live key is accepted.
The returned webhook_secret is what the plugin uses to verify Yera webhook signatures. Plugins store it automatically — merchants never configure webhook secrets manually, and the webhook URL is auto-detected by the plugin.
Connecting the same website again updates the existing site connection instead of creating a duplicate.
In live mode the callback URL must use HTTPS on a public host related to the site host.
Failed credential attempts are rate limited.

Request

bash

curl -X POST https://app.yeraconnect.io/api/v1/plugin/connect \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "MER_XXXXXXXXXXXX",
    "api_key": "yera_live_your_api_key",
    "security_code": "XXXXXX-XXXXXX-XXXXXX-XXXXXX",
    "platform": "woocommerce",
    "site_url": "https://store.com",
    "callback_url": "https://store.com/wp-json/yera-connect/v1/webhook",
    "plugin_version": "1.1.0"
  }'

Request body

json

{
  "merchant_id": "MER_XXXXXXXXXXXX",
  "api_key": "yera_live_your_api_key",
  "security_code": "XXXXXX-XXXXXX-XXXXXX-XXXXXX",
  "platform": "woocommerce",
  "site_url": "https://store.com",
  "callback_url": "https://store.com/wp-json/yera-connect/v1/webhook",
  "plugin_version": "1.1.0"
}

Response

json

{
  "ok": true,
  "status": "connected",
  "merchant_id": "MER_XXXXXXXXXXXX",
  "site_id": "site_123",
  "environment": "live",
  "platform": "woocommerce",
  "site_url": "https://store.com",
  "callback_url": "https://store.com/wp-json/yera-connect/v1/webhook",
  "webhook_secret": "whsec_yera_...",
  "message": "Yera Connect is connected."
}

Checkout Sessions

Create hosted checkout sessions and route customers to Yera Connect checkout.

POST/checkout/sessionsImplemented

Create checkout session

Create a hosted checkout session for a customer payment. This is the main server-side checkout API.

Auth

Bearer API key

Scope

checkout_sessions:create

Handler

apps/web/app/api/v1/checkout/sessions/route.ts

The current public API contract uses camelCase JSON fields.
countryCode is required so provider availability can be routed correctly.
The customer should be redirected to checkoutSession.checkoutUrl.

Request

bash

curl -X POST https://app.yeraconnect.io/api/v1/checkout/sessions \
  -H "Authorization: Bearer yera_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250,
    "currency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "countryCode": "DE",
    "customerEmail": "customer@example.com",
    "orderId": "ORDER-1001",
    "successUrl": "https://merchant.com/success",
    "cancelUrl": "https://merchant.com/cancel"
  }'

Request body

json

{
  "amount": 250,
  "currency": "EUR",
  "destinationAsset": "USDC",
  "network": "polygon",
  "countryCode": "DE",
  "customerEmail": "customer@example.com",
  "orderId": "ORDER-1001",
  "successUrl": "https://merchant.com/success",
  "cancelUrl": "https://merchant.com/cancel",
  "metadata": {
    "cartId": "cart_1001"
  }
}

Response

json

{
  "ok": true,
  "checkoutSession": {
    "id": "YC_0123456789ABC",
    "externalSessionId": "YC_0123456789ABC",
    "checkoutUrl": "https://checkout.yeraconnect.io/pay/YC_0123456789ABC",
    "status": "pending",
    "amount": "250",
    "currency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "mode": "test",
    "provider": "yera_checkout",
    "railType": "fiat_to_crypto",
    "createdAt": "2026-06-21T12:00:00.000Z",
    "expiresAt": null
  }
}

GET/checkout/sessions/{session_id}Customer route

Retrieve checkout session

Retrieve customer-facing checkout session details. This route is used by hosted checkout and status pages.

Auth

Not required

Handler

apps/web/app/api/v1/checkout/sessions/[session_id]/route.ts

This is a customer/session lookup route, not a secret-key merchant API route.

Response

json

{
  "id": "YC_0123456789ABC",
  "status": "pending",
  "amount": "250",
  "currency": "EUR",
  "destinationAsset": "USDC",
  "network": "polygon",
  "merchantName": "Example Merchant"
}

POST/checkout-sessionsImplemented

Create WooCommerce checkout session

Create a checkout session from the WooCommerce plugin compatibility endpoint.

Auth

Bearer API key

Scope

checkout_sessions:create

Handler

apps/web/app/api/v1/checkout-sessions/route.ts

This endpoint exists for WooCommerce and plugin integrations that use snake_case payloads.
Do not duplicate provider or settlement logic in the plugin; it reuses the hosted checkout session.

Request body

json

{
  "order_id": "1001",
  "order_key": "wc_order_key",
  "store_url": "https://merchant-store.com",
  "amount": 250,
  "currency": "EUR",
  "country_code": "DE",
  "customer_email": "customer@example.com",
  "crypto_asset": "USDC_POLYGON",
  "success_url": "https://merchant-store.com/order-received/1001",
  "cancel_url": "https://merchant-store.com/cart",
  "callback_url": "https://merchant-store.com/wp-json/yera/v1/webhook"
}

Response

json

{
  "success": true,
  "session_id": "YC_0123456789ABC",
  "checkout_url": "https://checkout.yeraconnect.io/pay/YC_0123456789ABC",
  "expires_at": "2026-06-21T13:00:00.000Z"
}

Payment Links

Create shareable payment links for invoices, WhatsApp, email, and direct merchant checkout flows.

POST/payment-linksImplemented

Create payment link

Create a fixed, open amount, or subscription-style Yera Connect payment link.

Auth

Bearer API key

Scope

payment_links:create

Handler

apps/web/app/api/v1/payment-links/route.ts

The route uses the merchant verified default wallet for the selected asset and network.
Payment links are created from server-side API keys only.

Request

bash

curl -X POST https://app.yeraconnect.io/api/v1/payment-links \
  -H "Authorization: Bearer yera_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice payment",
    "type": "fixed_amount",
    "amount": 100,
    "currency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "countryCode": "DE"
  }'

Request body

json

{
  "name": "Invoice payment",
  "type": "fixed_amount",
  "amount": 100,
  "currency": "EUR",
  "destinationAsset": "USDC",
  "network": "polygon",
  "countryCode": "DE",
  "paymentMethod": "any",
  "description": "Invoice INV-1001",
  "successUrl": "https://merchant.com/success",
  "cancelUrl": "https://merchant.com/cancel"
}

Response

json

{
  "ok": true,
  "checkoutUrl": "https://checkout.yeraconnect.io/pay/YC_0123456789ABC",
  "checkout_url": "https://checkout.yeraconnect.io/pay/YC_0123456789ABC",
  "sessionId": "YC_0123456789ABC",
  "session_id": "YC_0123456789ABC",
  "paymentLink": {
    "id": "YC_0ABCDEF123456",
    "type": "fixed_amount",
    "name": "Invoice payment",
    "checkoutUrl": "https://checkout.yeraconnect.io/pay/YC_0123456789ABC",
    "status": "active",
    "amount": "100",
    "currency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "provider": "yera_checkout"
  }
}

Payments

Retrieve payment session and transaction details after checkout activity has started.

GET/payment-sessions/{id}Implemented

Retrieve payment session

Retrieve checkout session status, provider status, destination asset, and customer payment metadata for your merchant account.

Auth

Bearer API key

Scope

transactions:read

Handler

apps/web/app/api/v1/payment-sessions/[id]/route.ts

Response

json

{
  "ok": true,
  "paymentSession": {
    "id": "YC_0123456789ABC",
    "checkoutUrl": "https://checkout.yeraconnect.io/pay/YC_0123456789ABC",
    "status": "completed",
    "amount": "250",
    "currency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "orderId": "ORDER-1001",
    "provider": "unconfigured",
    "railType": "fiat_to_crypto"
  }
}

GET/transactions/{id}Implemented

Retrieve transaction

Retrieve the latest transaction row for a canonical YC payment id, including merchant settlement fields, provider references, and blockchain references when available. Internal database row ids are not accepted.

Auth

Bearer API key

Scope

transactions:read

Handler

apps/web/app/api/v1/transactions/[id]/route.ts

Response

json

{
  "ok": true,
  "transaction": {
    "id": "YC_0123456789ABC",
    "paymentSessionId": "YC_0123456789ABC",
    "status": "completed",
    "sourceAmount": "250",
    "sourceCurrency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "merchantSettlementAmount": "247.50",
    "platformCommissionAmount": "2.50",
    "transactionHash": "0xabcd1234...",
    "completedAt": "2026-06-21T12:30:00.000Z"
  }
}

Webhooks

Receive signed merchant webhook deliveries when payment status changes.

Merchant webhook endpoints and signing secrets are configured in the Yera Connect dashboard.

Yera signs outgoing merchant webhooks with HMAC SHA-256 over `${timestamp}.${rawBody}`.

Use the event id for idempotency and do not process the same event twice.

Webhook headers

txt

user-agent: Yera-Connect-Webhooks/1.0
content-type: application/json
yera-delivery-id: whd_123456
yera-event-id: evt_yera_123456
yera-event-type: payment.completed
yera-signature: t=1760000000,v1=3f2a...
yera-timestamp: 1760000000

Webhook payload

json

{
  "event": "payment.completed",
  "eventId": "evt_yera_123456",
  "eventSource": "provider_webhook",
  "merchantId": "merchant_123",
  "sessionId": "YC_0123456789ABC",
  "transactionId": "YC_0123456789ABC",
  "provider": "unconfigured",
  "externalSessionId": "YC_0123456789ABC",
  "externalTransactionId": "provider_txn_123",
  "railType": "fiat_to_crypto",
  "status": "completed",
  "amount": "250",
  "currency": "EUR",
  "destinationAsset": "USDC",
  "network": "polygon",
  "walletAddress": "0x1234...abcd",
  "orderId": "ORDER-1001",
  "wooCommerce": {
    "orderStatus": "processing"
  },
  "createdAt": "2026-06-21T12:30:00.000Z"
}

Verify webhook signature

import crypto from "node:crypto";

export function verifyYeraWebhook({
  rawBody,
  signatureHeader,
  secret,
}: {
  rawBody: string;
  signatureHeader: string;
  secret: string;
}) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => {
      const [key, value] = part.trim().split("=");
      return [key, value];
    }),
  );

  const timestamp = parts.t;
  const signature = parts.v1;

  if (!timestamp || !signature) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Settlements

Stablecoin settlement details are available when a payment completes and settlement fields are present on transaction records.

GET/settlements/{id}Coming soon

Retrieve settlement

A dedicated settlement lookup endpoint is not currently implemented. Use /transactions/{id} for available merchant settlement details today.

Auth

Bearer API key

Scope

transactions:read

Settlement availability depends on merchant account setup, supported network, provider availability, and approval status.
Current transaction responses include settlement-related fields such as merchantSettlementAmount, platformCommissionAmount, transactionHash, and explorerUrl when available.

Production

Yera accepts new checkout sessions, payment links, webhooks, and plugin connections in Live mode only.

Live API key prefix: yera_live_

Historical Test records remain read-only and Test credentials cannot authenticate.

The platform payment kill switch can block new payments without switching to Test.

Create a Live checkout session

bash

curl -X POST https://app.yeraconnect.io/api/v1/checkout/sessions \
  -H "Authorization: Bearer yera_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "currency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "countryCode": "DE"
  }'

Errors

Yera Connect API errors return a status code and a machine-readable error payload where possible.

Error response

json

{
  "ok": false,
  "error": "Unauthorized",
  "message": "Invalid or missing API key.",
  "requestId": "req_123456"
}

Response codes

200Success

201Created

400Bad Request

401Unauthorized

403Forbidden

404Not Found

409Conflict

422Validation Error

429Rate Limited

500Server Error

Implementation map

This table maps each documented route to the handler found during the repo audit.

Route	Handler	Auth	Request	Response	Status
POST`/checkout/sessions`	`apps/web/app/api/v1/checkout/sessions/route.ts`	Bearer API key, checkout_sessions:create scope	CheckoutSessionApiRequestSchema	ok + checkoutSession	Implemented
POST`/checkout-sessions`	`apps/web/app/api/v1/checkout-sessions/route.ts`	Bearer API key, checkout_sessions:create scope	WooCommerceCheckoutSessionRequestSchema	success + session_id + checkout_url	Implemented
GET`/checkout/sessions/{session_id}`	`apps/web/app/api/v1/checkout/sessions/[session_id]/route.ts`	Public customer/session route	session_id path parameter	checkout session details	Customer route
POST`/payment-links`	`apps/web/app/api/v1/payment-links/route.ts`	Bearer API key, payment_links:create scope	PaymentLinkApiRequestSchema	ok + paymentLink + checkoutUrl	Implemented
GET`/payment-sessions/{id}`	`apps/web/app/api/v1/payment-sessions/[id]/route.ts`	Bearer API key, transactions:read scope	id path parameter	paymentSession	Implemented
GET`/transactions/{id}`	`apps/web/app/api/v1/transactions/[id]/route.ts`	Bearer API key, transactions:read scope	canonical YC payment id path parameter	latest transaction row for the payment	Implemented
POST`/plugin/connect`	`apps/web/app/api/v1/plugin/connect/route.ts`	Merchant ID + Yera API key + Security Code in the request body; plugin:connect scope	PluginConnectRequestSchema	ok + site_id + webhook_secret + environment + platform	Implemented
GET`/settlements/{id}`	`No dedicated route currently implemented`	Planned	id path parameter	settlement	Coming soon

API reference for Yera Connect checkout, links, payments, and webhooks.

Merchant credentials

Authentication

Response codes

Plugin Connect

Connect a website

Checkout Sessions

Create checkout session

Retrieve checkout session

Create WooCommerce checkout session

Payment Links

Create payment link

Payments

Retrieve payment session

Retrieve transaction

Webhooks

Settlements

Retrieve settlement

Production

Errors

Response codes

Implementation map

We use cookies