Checkout Sessions

Checkout Sessions provide a unique ID and hosted URL for one checkout attempt. Use them when your backend needs to attach trusted metadata, a customer reference, and return URLs before the buyer opens Yolfi.

Create a session

Call the authenticated endpoint with your organization API key:

curl https://app.yolfi.com/api/checkout-sessions \
  -H "Authorization: Bearer $YOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paylinkId": "120e3400-e12b-04d4-a716-446417440031",
    "customerEmail": "buyer@example.com",
    "clientReferenceId": "customer_123",
    "successUrl": "https://merchant.example/thanks?session_id={CHECKOUT_SESSION_ID}",
    "cancelUrl": "https://merchant.example/pricing",
    "metadata": {
      "order_id": "order_123"
    }
  }'

The response contains a unique ycs_... ID, hosted url, and expiresAt. Redirect the buyer to url. Yolfi reuses the same invoice if the create-payment request is retried for that session.

Return and webhook correlation

successUrl overrides the Payment Link's Redirect URL for this Checkout Session. It can be a normal URL, or it can include the literal {CHECKOUT_SESSION_ID} placeholder:

https://merchant.example/thanks?session_id={CHECKOUT_SESSION_ID}

After a successful payment, Yolfi replaces it with the current ycs_... identifier:

https://merchant.example/thanks?session_id=ycs_0123456789abcdef0123456789abcdef

The signed payment.confirmed event contains the same value as checkoutSessionId. This lets you match the browser return to the verified payment and its metadata. The return URL is useful for analytics and page state, but must not be used to fulfill an order.

Direct Paylinks also create a Checkout Session automatically when the buyer starts a payment, so the same placeholder works without calling the Checkout Sessions API first. See After a Payment for the complete redirect behavior and safety guidance.

Metadata precedence

Checkout Session metadata is created by your authenticated backend and overrides browser query metadata. Server-controlled Paylink paymentMetadata has the final priority. This prevents a buyer from changing routing or tenant metadata in the checkout URL.