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, a US bank account or a Canadian one 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, and acss_debit (a Canadian bank account, debited under the
pre-authorized debit agreement the page shows) needs CAD and a workspace set up for Canadian debits.
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 kept on
file with them once the payment succeeds: the page tells the customer so and asks for the billing ZIP. A bank
account paid on the page is kept too, and the customer accepts a standing ACH authorization or pre-authorized
debit agreement, which also covers later debits, in place of a one-time one. metadata (up to 20 keys) is stored
and returned, never interpreted. expires_at can be at most 7 days out. line_items and amount_details
list the order on the page: see Order lines.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, the order lines when you sent them,
and one tab per payment method type you allowed (a Canadian account’s is “Bank account (EFT)”). 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.
When the card’s bank wants to verify the customer (3-D Secure, on workspaces where Payra has turned it
on), the page takes them through it, on the page itself or at the bank’s, and finishes the payment; if the
bank refuses, the customer can try another method on the same page. 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.Order lines
Send the order with the session and the page lists it next to the amount, as a receipt: each line with its quantity, unit price and SKU, then the total; with shipping, tax or a discount, the subtotal and a row for each of them that is not zero come before it. The fields and the rule are the ones on a payment:line_items must come to amount together with
amount_details, or the create answers 400 parameter_invalid and no page is made. A quantity can have decimals: a line of 9.5 at $145.00 shows as 9.5 × $145.00 and $1,377.50.
checkout_session.completed and the
payment.* events have them too. A session sent without them shows the amount, the description and the
reference only.
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.