Skip to main content
Card and bank account details never pass through your servers, or Payra’s, in the clear: Payra Elements collects them in secure fields, they are tokenized before they reach Payra, and Payra keeps only the tokens plus what you may see (a card’s brand, last four digits and expiration date; a bank account’s last four digits, account type and holder type; the holder’s name and billing postal code), a card’s first digits (BIN), which Payra uses internally, and, for a bank account, the record of the holder’s authorization. A payment method session is what authorizes one such collection, of one instrument: payment_method_types is ["card"] (the default) or ["us_bank_account"]. Your server creates it with a secret key; your page opens it with your publishable key and the session’s client_secret.
1

Create the session on your server

Optionally bind it to one of your customers, so the collected method belongs to them.
Response
client_secret is returned only by this call, and by a replay of it under the same Idempotency-Key for the 24 hours a stored answer is kept.A bank account session names the debit the account holder will authorize. Without a customer it takes the amount (in cents, USD only) of the one payment the account may be debited for; with a customer it saves the account under a standing authorization (ach_authorization.scope: "standing", a text without an amount) and takes no amount. amount is not used on a card session or on a bank session with a customer, but if you send it, it must still be a positive integer and currency must be USD.
The answer carries ach_authorization: the text Payra Elements shows the account holder, worded for your business name and that amount. The page cannot change it.
2

Hand the client secret to your page

Send the page the client_secret and nothing more: the secret key stays on your server. The page passes it to Payra Elements together with your publishable key.Under the hood, Elements retrieves the session with the publishable key:
The answer is the same object, without client_secret and with a collect block telling Elements where to collect.
3

Collect

When the customer submits, Elements sends the secure fields through the secure route, which replaces the card number and security code, or the routing and account numbers, with tokens, and confirms the session. The session becomes succeeded and carries a card block:
or a us_bank_account block, together with the moment the account holder accepted the authorization:
A bank account is confirmed only with that acceptance: Elements sends the version the holder saw, Payra stamps the moment, the address and the text itself, and keeps the record for any dispute. Elements refuses to send a confirm without it (ach_authorization_required, raised in the browser), and a confirm that reaches the API without it is 400 parameter_invalid and stores nothing.Your server then turns the session into a payment method it can charge, with the secret key. Once it did, the session carries the method’s id as payment_method.

​
Lifecycle

A browser opening a session that is not requires_payment_method gets 400 payment_method_session_inactive. Create a new session; they are cheap.

​
What a session cannot do

  • Charge or refund. It authorizes collection only.
  • Carry a card number or a routing number in the clear. The confirm refuses a card number or a routing number that did not come through the secure route (400 card_not_tokenized, 400 bank_account_not_tokenized) and stores nothing.
  • Skip the authorization. A bank account confirmed without the holder’s acceptance is 400 parameter_invalid (Elements never sends one: it raises ach_authorization_required in the browser instead); an acceptance of a text version this server no longer defines is 400 ach_terms_version_unsupported (reload Elements, which fetches the current one).
  • Debit any other amount. A one-time bank account session needs amount (400 parameter_invalid without it), and the later charge must match it.
  • Act as a key. A client_secret sent as a bearer token answers 401 invalid_api_key, and a publishable key sent without client_secret answers 401 client_secret_missing.
  • Cross a workspace or an environment. It belongs to the workspace and environment of the key that created it. A client_secret presented with another workspace’s publishable key, with a key of the other environment, or under another session’s id answers 401 invalid_client_secret, without saying which.

​
Idempotency

Send an Idempotency-Key when you create a session, so a retried request returns the same session and the same client_secret instead of a second one.