Hosted Checkout

Create a Checkout Session

Create a session and store it in your database:

Code
 
curl https://api.payonify.com/v1/checkout/sessions \
  -u "pk_test_abc123...:sk_test_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "unit_amount": 1500,
        "name": "Premium Subscription",
        "quantity": 1
      }
    ],
    "mode": "payment",
    "success_url": "https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://yoursite.com/cancel",
    "currency": "usd"
  }'

Response:

Response
 
{
  "id": "cs_f66c6vqvbbhqxe35gbq7",
  "object": "checkout_session",
  "status": "requires_payment_method",
  "mode": "payment",
  "amount": {
    "value": 1500,
    "currency": "usd"
  },
  "line_items": [
    {
      "unit_amount": 1500,
      "name": "Premium Subscription",
      "quantity": 1
    }
  ],
  "url": "https://checkout.payonify.com/c/cs_f66c6vqvbbhqxe35gbq7",
  "success_url": "https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://yoursite.com/cancel",
  "customer_email": null,
  "metadata": null,
  "client_secret": "cs_f66c6vqvbbhqxe35gbq7_secret_gv4vr5e5qcfbfv6w53fp7jn3g7qp62eh",
  "submit_type": null,
  "livemode": false,
  "created": 1732437738,
  "expires_at": 1732524138
}

Store the session ID and initial status (requires_payment_method) in your database for later verification.

Redirect to Checkout

Redirect your customer to the url from the response:

Code
 
window.location.href = session.url;

The customer completes payment on the Payonify-hosted page.

Handle Webhooks

Payonify sends a webhook when payment status changes. Update your stored session:

Code
 
app.post('/webhook', (req, res) => {
  const { type, data } = req.body;

  if (type === 'checkout.session.completed') {
    const session = data.object;
    // Update stored session status
    await updateStoredSession(session.id, session.payment_status);

    if (session.payment_status === 'succeeded') {
      await fulfillOrder(session.metadata.order_id);
    }
  }

  res.sendStatus(200);
});

Handle Customer Return

When the customer returns to your success_url, check your stored session first:

Code
 
app.get('/success', async (req, res) => {
  const sessionId = req.query.session_id;

  // Check stored session first (webhook may have updated it)
  const storedSession = await getStoredSession(sessionId);

  if (storedSession.status === 'succeeded') {
    // Webhook already arrived - show success
    return res.render('success');
  }

  if (storedSession.status === 'requires_payment_method') {
    // Webhook hasn't arrived yet - fetch from API
    const session = await fetchCheckoutSession(sessionId);
    await updateStoredSession(sessionId, session.payment_status);

    if (session.payment_status === 'succeeded') {
      await fulfillOrder(session.metadata.order_id);
      return res.render('success');
    }
  }

  return res.render('pending');
});

See the Webhooks Guide for detailed implementation.