API integration

Use the API when you have a custom backend and want to create checkout sessions directly.

API integration gives merchants more control than payment links or plugin-only setup. It is best for custom ecommerce platforms, marketplaces, SaaS billing flows, or backend systems that need to attach internal order metadata.

Your credentials

Everything you need is in Dashboard -> Developers -> API Credentials:

1. Merchant ID (MER_...) - identifies your account. It never changes.
2. Yera Live API Key (yera_live_...) - locked until your account is approved, then issued automatically.
3. Security Code - only used when connecting a website plugin. Custom API integrations never need it.

Send your API key with every request:

Authorization: Bearer yera_live_your_api_key

Only yera_live_ keys authenticate new requests. Historical Test keys cannot be reused. Live keys are rejected until your account is approved.

If you regenerate an API key, the old key keeps working for 24 hours so you can update your integration without downtime. Legacy yera_test_sk_ / yera_live_sk_ keys are retired and no longer authenticate.

Basic flow

1. Create a server-side API key.
2. Send checkout session details from your backend.
3. Store the returned session ID.
4. Redirect the customer to the returned checkout URL.
5. Listen for webhooks.
6. Update your internal order status.

Create a checkout session

Direct API integrations create sessions with:

POST https://app.yeraconnect.io/api/v1/checkout-sessions
Authorization: Bearer yera_live_REPLACE_WITH_YOUR_KEY
Content-Type: application/json

Example payload:

{
  "amount": "100.00",
  "countryCode": "NL",
  "currency": "EUR",
  "destinationAsset": "USDC",
  "network": "Polygon",
  "customerEmail": "customer@example.com",
  "orderId": "order_10482",
  "redirectUrl": "https://merchant.example.com/checkout/complete"
}

amount, countryCode, and currency are required. Currency must be the authoritative three-letter currency stored on the order; it is never inferred from country.

WooCommerce plugins use a separate order-shaped route:

POST https://app.yeraconnect.io/api/v1/checkout/sessions

That route expects WooCommerce fields such as order_id, order_key, store_url, success_url, cancel_url, callback_url, and webhook_secret.

Create payment links

Server-side integrations can create reusable payment links with:

POST https://app.yeraconnect.io/api/v1/payment-links
Authorization: Bearer yera_live_REPLACE_WITH_YOUR_KEY
Content-Type: application/json

Fixed amount link:

{
  "type": "fixed_amount",
  "name": "Invoice 10482",
  "amount": "100.00",
  "countryCode": "NL",
  "currency": "EUR",
  "destinationAsset": "USDC",
  "network": "Polygon"
}

Open amount link:

{
  "type": "open_amount",
  "name": "Custom deposit",
  "minAmount": "10.00",
  "maxAmount": "5000.00",
  "suggestedAmount": "100.00",
  "countryCode": "NL",
  "currency": "EUR"
}

Subscription link:

{
  "type": "subscription",
  "name": "Monthly support",
  "amount": "29.00",
  "billingInterval": "monthly",
  "countryCode": "NL",
  "currency": "EUR",
  "collectEmail": true
}

Fixed amount links return an initial session_id. Open amount and subscription links return a reusable public checkout URL; the customer creates the checkout session from the hosted Yera Connect page.

Recommended backend data model

Store these references in the merchant backend:

1. Internal order ID
2. Yera payment session ID
3. Customer email
4. Amount
5. Fiat currency
6. Checkout URL
7. Session status
8. Transaction ID when available
9. Last webhook event ID

This makes support, reconciliation, and retry handling easier.

Security rules

1. Keep API keys server-side. Never expose them in frontend or public JavaScript.
2. Never share API keys or your Security Code publicly.
3. Use your Live API Key only after approval and only from trusted server-side code.
4. Validate webhook signatures.
5. Store session IDs with internal order IDs.
6. Do not trust browser-only status updates.

Webhook signature verification

Yera Connect sends merchant webhooks with these headers:

1. yera-delivery-id
2. yera-event-id
3. yera-event-type
4. yera-timestamp
5. yera-signature

The signature header format is:

t=<timestamp>,v1=<hex_digest>

Verify it by computing:

hex(hmac_sha256(webhook_secret, `${yera-timestamp}.${rawRequestBody}`))

Use the raw request body for verification. Parse JSON only after the signature matches.

API integration direction

1. Complete dashboard setup.
2. Obtain the approved Live API key.
3. Build server-side checkout session creation.
4. Redirect customers to the returned checkout URL.
5. Add webhook handling.
6. Update internal order status from webhook events.
7. Verify the webhook and checkout flow without submitting money.
8. Review dashboard sessions and transactions.
9. Submit a controlled Live payment only after separate authorization.

Common mistakes

Avoid:

1. Calling secret-key endpoints from browser JavaScript.
2. Creating orders without saving the Yera session ID.
3. Using redirects as the only proof of payment.
4. Ignoring webhook failures.
5. Reusing historical Test credentials.