Skip to main content

Accept your first payment with hosted checkout

What you will have working​

A payment taken on a platform-hosted, merchant-branded page, with your server notified by a payment.succeeded webhook. About ten minutes end to end in sandbox.

Prerequisites​

  • A sandbox secret key (sk_test_...) and publishable key (pk_test_...) from your dashboard. The environment is in the key prefix, never the host.
  • Your return origins on the allowlist.

Steps​

1. Create a checkout session, server-side, with your secret key.

curl https://api.blackjackpayments.com/v1/checkout_sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "1250",
    "currency": "USD",
    "success_url": "https://your.site/done",
    "cancel_url": "https://your.site/cart"
  }'

The response is the session plus a session_token -- a short-lived, single-session client secret.

2. Send the payer to the hosted page. Hand the browser your publishable key and the session_token -- never the secret key -- and redirect to the hosted checkout for the session. The payer enters their card in Evervault-hosted fields; your checkout domain never touches card data.

3. Let the session finish. On success the payer returns to your success_url; on cancel, to your cancel_url.

Verify it worked​

Use a sandbox test card that always succeeds (your dashboard lists the current set). The session reaches succeeded and you receive:

{ "object": "event", "type": "payment.succeeded",
  "data": { "object": { "object": "payment", "status": "succeeded", "amount": "1250", "currency": "USD" } } }

Confirm the amount and currency match what you created the session with.

Make it fail on purpose​

Before you go live, take one decline. Use a sandbox test card that returns insufficient_funds (again from your dashboard). The payment comes back at HTTP 200 with status: declined and a decline block -- not an HTTP error. Handle it now, in the code you just wrote, so production is not where you find out a decline is a 200.

Go live​

Swap the sk_test_/pk_test_ keys for sk_live_/pk_live_; nothing else changes, because the environment lives in the prefix. Read the go-live checklist first.

Next steps​

Test-card numbers come from the sandbox itself rather than from this page. They are the gateway's values, and a number written here would go stale the day the gateway changed it.