Your Webpage, index.html (Example):
This index.html example above (from `/examples/`) would include a mock `raylay.js` (formerly `raylay.js`) and register `sw.js` (mock Service Worker) to handle the fetch calls to /api/raylay/... endpoints, allowing the button interactions to be demonstrated fully on the frontend if you serve these files from a local server. The paths in the example HTML (`raylay.js`, `sw.js`) might need adjustment to `v1/raylay.js` and `v1/sw.js` if those are the final locations and this HTML example is run directly from the `examples` folder.
Step 1: Backend - Your server creates a RayLay Checkout Session.
See Backend Node.js example for raylay.checkout.sessions.create call.
Step 2: Frontend - Your webpage redirects the user.
After payment, RayLay redirects the user to your success_url or cancel_url. You must verify the payment status on your backend using webhooks or by fetching the session/payment details.
1. Your Backend: Creates a RayLay PaymentIntent (see Backend HTTP example for POST /v1/payment_intents). Returns client_secret and id to your frontend.
2. Your Frontend: Collects payment details (e.g., using a third-party tokenizer for cards to get a payment_method_token).
3. Your Frontend to Your Backend: Sends payment_intent_id and payment_method_token (or other payment data) to a dedicated endpoint on your server.
4. Your Backend to RayLay: Your server securely calls RayLay's POST /v1/payment_intents/:id/confirm API with the payment method details.
5. Your Backend to Your Frontend: Your server returns the confirmation result (success, failure, requires_action) to your frontend.
Example: Frontend JS sending data to YOUR backend (Step 3)
Authentication: Include your secret API key in the Authorization header as a Bearer token:Authorization: Bearer sk_test_YOUR_SECRET_KEY
Example: Create a PaymentIntent (Server-Side)
Example: Create Payout (Server-Side)
Core API Endpoints Reference
A summary of key RayLay API resources. For complete details, please refer to our full Interactive API Documentation (OpenAPI/Swagger).
PaymentIntents
A PaymentIntent object tracks the lifecycle of a customer payment, from creation through to success or failure. It contains a client_secret which is used by client-side SDKs (like RayLay.js) to securely complete the payment.
Creates a new PaymentIntent to initiate a payment flow.
Retrieves the details and current status of a specific PaymentIntent by its ID.
Confirms a PaymentIntent with payment method details, typically when using a custom server-side flow without RayLay.js or Checkout handling the confirmation directly.
Checkout Sessions
Checkout Sessions provide a streamlined way to use RayLay's hosted payment page (RayLay Checkout). You create a session on your backend, then redirect the user to the RayLay-hosted URL.
Creates a new RayLay Checkout session.
Retrieves a Checkout session to check its status (e.g., after the user returns to your site).
Payouts
Payouts allow you to transfer funds from your RayLay balance (e.g., accumulated USDC) to an external destination, such as your corporate Solana wallet on an exchange (for subsequent fiat withdrawal) or directly to a bank account via a partner rail (future capability).
Creates a Payout to transfer funds.
Retrieves the details and status of a specific Payout.
Balance
Retrieve your RayLay account balance information.
Retrieves your available and pending balances, typically broken down by currency (e.g., USDC, SOL, and fiat equivalents if held directly by RayLay in future).
Webhooks
Use webhooks to receive asynchronous event notifications from RayLay, such as payment success, payout completion, or disputes. This is crucial for reliable backend integration.
Creates a new webhook endpoint configuration.
Lists your configured webhook endpoints.
Deletes a webhook endpoint.
Example Event Payload (payment_intent.succeeded):