API Integration
Use the Yolfi HTTP API for server-controlled checkout, reusable payment links, and verified payment events.
Choose the payment flow
| Goal | Integration |
|---|---|
| Ask a coding assistant to implement payments | Start with the AI onboarding prompt. |
| Charge a dynamic cart or order total | Create a Checkout Session from your backend. |
| Sell a fixed-price product, plan, or contribution | Create a reusable Paylink and share its hosted checkout URL. |
| Operate from a terminal or automation job | Use the CLI reference. |
The production API base URL is https://app.yolfi.com/api. Keep authenticated requests on your backend. Obtain an organization API key from your Yolfi settings and store it in a secret manager or ignored environment file. Never ship it in a browser bundle or paste it into chat.
Create a reusable Paylink
After the owner confirms the product and price, call the existing Paylink endpoint:
curl https://app.yolfi.com/api/private/paylinks/create \
-X POST \
-H "Authorization: Bearer $YOLFI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium download",
"type": "ONE_TIME",
"price": "29.00",
"currency": "USD",
"collectEmail": true
}'Use the returned data.id in https://pay.yolfi.com/{paylinkId}. Configure your receiving wallets before sharing it with customers. Checkout URL parameters can attach your customer reference and payment metadata.
For recurring links, use type: "RECURRING" and a supported recurringInterval, for example "MONTH". Customers pay renewals from their own wallet. Do not treat a recurring plan as permission to debit a wallet automatically.
Create a dynamic Checkout Session
For carts and server-calculated order totals, use POST /api/checkout-sessions with an organization API key and an Idempotency-Key. Send the final amount as a decimal string. Keep product pricing, discounts, tax, and order fulfillment in your own application.
The Checkout quickstart shows the full request and hosted redirect. The Checkout Sessions API reference defines fields, response data, and idempotency behavior. The current CLI does not have a Checkout Session command; call this endpoint from your backend.
API entry points
| Operation | Endpoint | Authentication |
|---|---|---|
| Read current organization | GET /api/private/organization/current | Bearer organization API key |
| Update organization and settlement addresses | PUT /api/private/organization/current | Bearer organization API key |
| List Paylinks | GET /api/private/paylinks | Bearer organization API key |
| Create Paylink | POST /api/private/paylinks/create | Bearer organization API key |
| Get Paylink | GET /api/private/paylinks/{id} | Bearer organization API key |
| Create Checkout Session | POST /api/checkout-sessions | Bearer organization API key and Idempotency-Key |
| Get Checkout Session | GET /api/checkout-sessions/{id} | Bearer organization API key |
| List or create webhook endpoints | GET or POST /api/private/organization/webhook-endpoints | Bearer organization API key |
| Read hosted Paylink information | GET /api/public/paylinks/{id} | Public |
| Create an invoice for an existing Paylink | POST /api/public/payments | Public; request contract |
| Read payment status | GET /api/public/payments/{id} | Public |
Verify before granting access
Configure a webhook endpoint and keep its returned signing secret separate from your API key. Verify X-Yolfi-Signature against the raw request body. Use confirmed payment events and idempotent fulfillment; browser redirects alone do not prove payment.
Stripe and Lemon Squeezy adapters change the payload format. They still use Yolfi signature verification. New integrations should choose an adapter currently available in the dashboard and follow its documented event mapping.