Authentication Checkout Sessions Payment Links Payments Webhooks Settlements Sandbox 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

Sandbox base URL

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

Checkout host

https://checkout.yeraconnect.io

Authentication

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

Use sandbox keys for testing and live keys only in production.

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

Merchant API keys currently use yera_test_sk_ and yera_live_sk_ secret prefixes.

Authenticated request

bash

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

Response codes

200Success

201Created

400Bad Request

401Unauthorized

403Forbidden

404Not Found

409Conflict

422Validation Error

429Rate Limited

500Server Error

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_test_sk_your_secret_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_sess_123456",
    "externalSessionId": "yc_sess_123456",
    "checkoutUrl": "https://checkout.yeraconnect.io/pay/yc_sess_123456",
    "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_sess_123456",
  "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 Coindisco 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_sess_123456",
  "checkout_url": "https://checkout.yeraconnect.io/pay/yc_sess_123456",
  "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_test_sk_your_secret_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_sess_123456",
  "checkout_url": "https://checkout.yeraconnect.io/pay/yc_sess_123456",
  "sessionId": "yc_sess_123456",
  "session_id": "yc_sess_123456",
  "paymentLink": {
    "id": "plink_123456",
    "type": "fixed_amount",
    "name": "Invoice payment",
    "checkoutUrl": "https://checkout.yeraconnect.io/pay/yc_sess_123456",
    "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_sess_123456",
    "checkoutUrl": "https://checkout.yeraconnect.io/pay/yc_sess_123456",
    "status": "completed",
    "amount": "250",
    "currency": "EUR",
    "destinationAsset": "USDC",
    "network": "polygon",
    "orderId": "ORDER-1001",
    "provider": "coindisco",
    "railType": "fiat_to_crypto"
  }
}

GET/transactions/{id}Implemented

Retrieve transaction

Retrieve transaction records, merchant settlement fields, provider references, and blockchain references when available.

Auth

Bearer API key

Scope

transactions:read

Handler

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

Response

json

{
  "ok": true,
  "transaction": {
    "id": "txn_123456",
    "paymentSessionId": "yc_sess_123456",
    "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_sess_123456",
  "transactionId": "txn_123456",
  "provider": "coindisco",
  "externalSessionId": "yc_sess_123456",
  "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.

Sandbox

Use sandbox mode to test checkout sessions, payment links, webhook delivery, and payment status updates before going live.

Sandbox secret key prefix: yera_test_sk_

Live secret key prefix: yera_live_sk_

Use live keys only in production server environments.

Create a sandbox checkout session

bash

curl -X POST https://sandbox.yeraconnect.io/api/v1/checkout/sessions \
  -H "Authorization: Bearer yera_test_sk_your_secret_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	id path parameter	transaction	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.

Authentication

Response codes

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

Sandbox

Errors

Response codes

Implementation map

We use cookies