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.

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://yeraconnect.io/api/v1/checkout-sessions
Authorization: Bearer yera_test_sk_REPLACE_WITH_SECRET
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 and countryCode are required. currency can be omitted when the country should decide the default checkout currency.

WooCommerce plugins use a separate order-shaped route:

POST https://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.

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 secret keys server-side.
2. Validate webhook signatures.
3. Store session IDs with internal order IDs.
4. 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. Create sandbox API keys.
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. Test sandbox payments.
8. Review dashboard sessions and transactions.
9. Rotate to live keys only after live approval.

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. Mixing sandbox keys with live checkout.