# HTTP API (/en/api)



import { Bot, CreditCard, Shield, Terminal, Webhook } from 'lucide-react';

Want your assistant to implement this? Use [Connect with AI](/en/agent-kit). For terminal operations, see the [CLI reference](/en/cli).

Base URL and API contract [#base-url-and-api-contract]

```text
https://app.yolfi.com/api
```

The deployed service exposes [OpenAPI JSON](https://app.yolfi.com/api/docs-json) and [Swagger UI](https://app.yolfi.com/api/docs). Use the endpoint references below for request fields, response semantics, and payment lifecycle rules. OpenAPI describes the deployed server; check that a required operation is present before depending on it.

Authentication [#authentication]

This section applies to direct HTTP requests. An agent already connected through MCP should keep using its authorized MCP tools without obtaining an additional API key. A separate server credential is needed only if the product itself will make private HTTP calls.

Private HTTP operations accept `Authorization: Bearer <organization API key>` or a valid dedicated agent credential. Obtain an organization key from [API key settings](https://app.yolfi.com/settings/api-keys) and configure it in server-side secret storage. Keep authenticated requests on your backend. Never include the key in a browser bundle, checkout URL, log, or chat message.

Host-managed MCP OAuth tokens are scoped to `/mcp` and are not HTTP API credentials for the merchant application. Provisioning an integration through an agent does not automatically configure a deployed server's credentials. Public Paylink redirects and public payment-status reads do not need a private credential.

Webhook signatures use a separate endpoint signing secret. An account API key does not verify a webhook.

Choose the payment flow [#choose-the-payment-flow]

| Goal                                                            | HTTP integration                                                                                    |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Sell a fixed-price product, plan, or contribution               | Create a reusable [Paylink](/en/paylinks/api-reference) and share its hosted checkout URL.          |
| Charge a dynamic cart or order total                            | Calculate the price on your server and create a [Checkout Session](/en/checkout/quickstart).        |
| Build a custom payment UI around an existing Paylink or session | Read public checkout data and use the [public payment API](/en/accept-payments#public-payment-api). |
| Fulfill an order or grant access after payment                  | Verify signed [webhook events](/en/webhooks) and make fulfillment idempotent.                       |

Create a reusable Paylink [#create-a-reusable-paylink]

```bash
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 [receiving wallets](/en/accept-payments/settlement-wallet) before sharing it. [Checkout URL parameters](/en/paylinks/checkout-parameters) can attach a customer reference and metadata.

For recurring links, use `type: "RECURRING"` and a supported `recurringInterval`, for example `"MONTH"`.

The [Paylinks API reference](/en/paylinks/api-reference) defines every creation field, editable fields, list pagination, response shape, and recurring intervals. Existing links should be reused where their price and billing terms match the requested product. Recurring customers authorize each renewal from their own wallet; a recurring plan does not authorize automatic wallet debits.

Create a dynamic Checkout Session [#create-a-dynamic-checkout-session]

Use `POST /api/checkout-sessions` with a stable `Idempotency-Key`. Keep pricing, tax, discounts, and order data in your application; send the final server-calculated amount as a decimal string. The [quickstart](/en/checkout/quickstart) gives a complete request and hosted redirect. The [API reference](/en/checkout/api-reference) defines all fields, responses, and retry behavior.

API entry points [#api-entry-points]

All paths below are relative to the API base URL. Private operations require the bearer credential described above.

| Operation                            | Method and path                                   | Request reference                                                                  |
| ------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Read organization                    | `GET /private/organization/current`               | [Organization settings](/en/accept-payments/settlement-wallet#http-configuration)  |
| Update organization details          | `PUT /private/organization/current`               | [Organization fields](/en/accept-payments/settlement-wallet#organization-fields)   |
| Update specified settlement networks | `PATCH /private/organization/settlement-accounts` | [Settlement patch](/en/accept-payments/settlement-wallet#update-selected-networks) |
| List Paylinks                        | `GET /private/paylinks`                           | [Pagination and filters](/en/paylinks/api-reference#list-paylinks)                 |
| Create Paylink                       | `POST /private/paylinks/create`                   | [Creation fields](/en/paylinks/api-reference#create-a-paylink)                     |
| Read Paylink                         | `GET /private/paylinks/{id}`                      | [Read response](/en/paylinks/api-reference#read-a-paylink)                         |
| Edit Paylink                         | `POST /private/paylinks/edit`                     | [Editable fields](/en/paylinks/api-reference#edit-a-paylink)                       |
| Disable Paylink                      | `POST /private/paylinks/disable`                  | [Disable request](/en/paylinks/api-reference#disable-a-paylink)                    |
| Create Checkout Session              | `POST /checkout-sessions`                         | [Session fields and idempotency](/en/checkout/api-reference)                       |
| Read Checkout Session                | `GET /checkout-sessions/{id}`                     | [Session response](/en/checkout/api-reference#retrieve-a-checkout-session)         |
| Manage webhook endpoints             | `/private/organization/webhook-endpoints`         | [Methods and fields](/en/webhooks#endpoint-management-api)                         |
| Read hosted Paylink                  | `GET /public/paylinks/{id}`                       | Public                                                                             |
| Read hosted Checkout Session         | `GET /public/checkout-sessions/{id}`              | [Public session data](/en/checkout/api-reference#public-hosted-checkout-endpoint)  |
| Create invoice                       | `POST /public/payments`                           | [Public payment fields](/en/accept-payments#public-payment-api)                    |
| Read payment status                  | `GET /public/payments/{id}`                       | Public                                                                             |

Responses and retries [#responses-and-retries]

Successful merchant operations generally return `{ "success": true, "data": ... }`; Paylink lists also include `total`. Inspect both the HTTP status and the response `success` field. Some domain errors return `success: false` with a `message` or `code`; validation and authentication errors can use non-2xx HTTP responses. Do not treat HTTP 200 alone as a successful mutation.

Reuse the same request and idempotency key when retrying Checkout Session creation. Paylink and webhook creation do not have that idempotency contract: after an uncertain result, list existing resources before retrying. Avoid creating duplicate links or endpoints.

Verify before fulfillment [#verify-before-fulfillment]

Verify `X-Yolfi-Signature` against the raw request body using the endpoint's signing secret. Fulfill from a confirmed payment event or verified payment status, with durable idempotency. A frontend redirect and `Checkout Session.status = COMPLETED` do not prove a blockchain payment is confirmed.

Stripe and Lemon Squeezy adapters change the payload envelope, but still require Yolfi signature verification. Read [webhook event details](/en/webhooks/webhook-details), [signature verification](/en/webhooks/webhook-signatures), and the [adapter reference](/en/adapters) for the selected payload format.

<Cards>
  <Card title="Checkout API reference" description="Request fields, immutable totals, responses, and idempotency." icon={<CreditCard />} href="/en/checkout/api-reference" />

  <Card title="Webhook events" description="Payment and subscription lifecycle payloads." icon={<Webhook />} href="/en/webhooks/webhook-details" />

  <Card title="Signature verification" description="Verify raw requests using the endpoint signing secret." icon={<Shield />} href="/en/webhooks/webhook-signatures" />

  <Card title="CLI and JavaScript helpers" description="Terminal commands and the existing package's integration helpers." icon={<Terminal />} href="/en/cli" />

  <Card title="AI onboarding" description="Describe the desired behavior and let a tool-capable assistant implement it." icon={<Bot />} href="/en/agent-kit" />
</Cards>