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, plus the institution and transit numbers of a Canadian one; 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), ["us_bank_account"] for a US bank account or ["acss_debit"] for a Canadian one. 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 is saved on 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 one of USD and CAD.
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.
method says how the authorization was obtained: always online_checkbox in Elements, and what your server attested to (verbal, written, online_checkbox) on the session Payra makes for bank details you send.A Canadian bank account session (acss_debit) is the same, in CAD: without a customer it takes the amount (in cents, with currency: "CAD") of the one pre-authorized debit (PAD) the account holder will authorize; with a customer it saves the account under the combined agreement that covers later debits (pad_agreement.scope: "standing") and takes no amount. A Canadian account is only debited in CAD, so a currency of USD on a one-time session is 400 parameter_invalid on currency. Canadian debits are set up per workspace: where they are not, the create answers 400 payment_provider_not_configured on payment_method_types, before any page opens.
The answer carries pad_agreement in place of ach_authorization: the Pre-Authorized Debit Agreement Payra Elements shows the account holder, worded for your business name. It names no amount, only “the amount shown”, so show the amount on your page; the session’s is recorded with the acceptance.
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 bank account’s 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:
last4 is null when the account number has fewer than 7 digits (US account numbers go down to 4; the token for a shorter number keeps none of its digits). Such an account can be charged once, but cannot be saved as a payment method: POST /v1/payment-methods makes it usage: one_time even when the session named a customer, and refuses usage: saved with parameter_invalid.A Canadian account comes back as an acss_debit block, with its branch, and the accepted pad_agreement:
The institution and transit numbers identify the bank and the branch, not the account, so they travel in the clear; the account number is tokenized like any other.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, or pad_agreement_required on a Canadian account, 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 bank account number in the clear. The confirm refuses a card number, or a routing or account number, that did not come through the secure route (400 card_not_tokenized, 400 bank_account_not_tokenized) and stores nothing; where Payra enabled it, a US account your server holds goes to POST /payment-methods instead. A Canadian account is accepted only from the secure fields of Elements: a confirm of one sent from your server, or from fields of your own, is 400 bank_account_not_tokenized (param: accountNumber).
  • 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). The same holds for a Canadian account and its PAD agreement: pad_agreement_required in the browser, 400 pad_terms_version_unsupported for a version this server no longer defines.
  • 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.