cs_test_… / cs_live_… object your server
creates with a secret key and a url on Payra’s domain. Send the customer there; the page carries
your business name and logo, collects a card or a US bank account with Payra Elements,
charges it in your name (the payment shows in RevOS like any other), and sends the customer back to
your success_url. A session pays once and expires after 24 hours unless you say otherwise.
Use it when you would rather not host the payment step: no fields on your page, no publishable key in
your front end, one redirect out and one back. Use Elements directly when the fields have
to live inside your own checkout.
1
Create the session on your server
Response
amount is in the smallest unit, charged exactly. success_url and cancel_url must be https; a
sandbox key may also use http://localhost while you build.
reference (your order number) and description are stored on the payment the page makes, so the
payment.* webhooks carry them as they do for any charge. payment_method_types omitted
means a card only; us_bank_account needs USD. customer_email is kept on the session for your records.
customer, one of your customers, files the payment on them, and a card paid on the page is also saved
to them: the page tells the customer so and asks for the billing ZIP. metadata (up to 20 keys) is stored
and returned, never interpreted. expires_at can be at most 7 days out.An Idempotency-Key is required: a retry after a timeout answers the same session and
the same url, not a second page for the order.url is in this response only. It carries the key that opens the page; reading the session back
never returns it. Store it with the order, or send the customer at once.2
Send the customer to the page
Redirect in the same tab (
302, or window.location). The page shows your business name and logo
from RevOS settings, the amount, the description and the reference, and one tab per payment method
type you allowed. The customer enters the details; a refused card can be tried again on the same page.A card is charged at once; a bank debit is accepted and the page says the payment is scheduled. On
success the customer is sent to success_url with ?checkout_session=cs_… appended, so your page can
read the session before the webhook lands. Back to store goes to cancel_url, and so does an
expired page.3
Confirm on your server
Listen for
checkout_session.completed, whose data.object is the session with
payment set to the pay_… it made; or for payment.succeeded as with any charge (the payment carries
your reference). A page that ran out of time, or that you expired, emits checkout_session.expired.Reading the session back works too:status is open, complete (with payment) or expired. A bank debit leaves the session complete
while the payment is still processing: follow the payment, as Payments explains, to know
when it settled.The publishable key the page uses
The page mounts Elements with a publishable key of your workspace. If the workspace has none in that environment, the first session creates one named Hosted checkout; it appears in Settings → Integrations like any other key and can be revoked there. Revoking it while sessions are open makes those pages unavailable; the next session creates a new one.Closing a page early
When the order is canceled on your side, expire the page so the customer cannot pay it:400 checkout_session_not_open. While the customer is
paying on the page, the page stays open and the call answers 409 checkout_session_payment_in_flight:
retrieve the session once that payment has succeeded or failed. If it is complete, the order is
paid; if it is still open, expire it again.
Listing
GET /checkout-sessions answers your sessions newest first, paged with limit and starting_after
like every other list; see pagination.