Hosted Checkout

Hosted Checkout keeps card collection on a Zentra page. Unlike the Payments API, your application never sends card data. Create a session, redirect to hosted_payment_url, and let Zentra complete the secure payment step.

1. POST /api/v1/payment/hosted/create (no card fields).
2. Get hosted_payment_url and expires_at.
3. Redirect the customer.
4. Customer enters card only. Amount and billing come from your request.
5. After pay/3DS, redirect to return_url.
6. Confirm via /api/v1/payment/status or webhooks.

The URL prefix selects the mode. Always redirect to the checkout URL returned by Zentra rather than constructing one in your application.

Generate a private key in Developers. Send it from your backend as a bearer token or X-API-Key header.

Authorization: Bearer zentra_xxxxxxxxxxxxxxxx

POST /api/v1/payment/hosted/create or test prefix. One-time URL. Expires in 30 minutes.

Request

Forbidden

curl -X POST https://api.zentra.solutions/api/v1/payment/hosted/create \
  -H "Authorization: Bearer zentra_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Luca",
    "last_name": "Moretti",
    "line1": "42 King Street",
    "country": "GB",
    "state": "Greater Manchester",
    "city": "Manchester",
    "postal_code": "M2 4WQ",
    "ip_address": "198.51.100.24",
    "email": "luca.moretti@atlas-demo.test",
    "phone": "+441614960180",
    "amount": "149.95",
    "currency": "GBP",
    "return_url": "https://shop.atlas-demo.test/order/complete",
    "merchant_transaction_id": "ATLAS-CHECKOUT-4096"
  }'

Redirect to hosted_payment_url. Do not build the URL.

{
  "status": "pending",
  "hosted_payment_url": "https://zentra.solutions/hosted-checkout/txn_znt_4Jq8Rc2Ny7Vs",
  "transaction_id": "txn_znt_4Jq8Rc2Ny7Vs",
  "merchant_transaction_id": "ATLAS-CHECKOUT-4096",
  "expires_at": "2026-10-26 05:30:00 UTC"
}

Declined

{
  "status": "declined",
  "reason": "Duplicate merchant transaction id.",
  "merchant_transaction_id": "ATLAS-CHECKOUT-4096"
}

Card fields sent

{
  "status": "blocked",
  "reason": "Card details must not be sent to hosted payment create. Collect card on the hosted page."
}

Validation failed

{
  "status": "blocked",
  "reason": "The return url field is required.",
  "merchant_transaction_id": "ATLAS-CHECKOUT-4096",
  "transaction_id": "txn_znt_4Jq8Rc2Ny7Vs"
}

Customer lands on Zentra's page at hosted_payment_url.

• Merchant name and charge amount
• Customer name and email (from your request)
• Card number, expiry, and CVV only

Zentra submits the card. You only call create from your server.

After pay or 3DS, redirect to return_url:

https://shop.atlas-demo.test/order/complete?status=success&transaction_id=txn_znt_9Hd3Wp6Kt1Bx&merchant_transaction_id=ATLAS-CHECKOUT-4096&reason=Payment%20completed

Confirm from your backend via status or webhooks — do not trust the browser redirect alone.

Use the same status endpoint as the Payments API. Match the live or test prefix used when creating the session.

curl -X POST https://api.zentra.solutions/api/v1/payment/status \
  -H "Authorization: Bearer zentra_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_transaction_id": "ATLAS-CHECKOUT-4096"
  }'

{
  "success": true,
  "data": {
    "transaction_id": "txn_znt_9Hd3Wp6Kt1Bx",
    "merchant_transaction_id": "ATLAS-CHECKOUT-4096",
    "status": "success",
    "amount": 149.95,
    "currency": "GBP",
    "message": "Payment completed.",
    "customer_info": {
      "phone": "+441614960180",
      "line1": "42 King Street",
      "postal_code": "M2 4WQ",
      "city": "Manchester",
      "state": "Greater Manchester",
      "name": "Luca Moretti",
      "email": "luca.moretti@atlas-demo.test",
      "country": "GB"
    },
    "created_at": "2026-10-26 05:00:00 UTC",
    "processed_at": "2026-10-26 05:01:12 UTC",
    "payment_info": {
      "card_number": "4242",
      "card_expiry_month": 1,
      "card_expiry_year": 2028
    }
  }
}

Same transactions / test_transactions tables. type is the source:

Create inserts a pending row with type: hosted_payment and no card data. Card entry completes the same record.

• Sessions expire 30 minutes after creation.
• Single-use after success, processing, or declined.
• merchant_transaction_id must be unique per merchant.
• Expired or used sessions error on the hosted page.

Create a test session, then enter these cards on the hosted page:

Hosted payments emit the same events as the Payments API (payment.completed, payment.declined, payment.blocked). See Payments API guide for setup and payloads.