Skip to main content
A US bank account is debited over the ACH network, the batch system the US banks share, under rules set by Nacha. The pages on payment method sessions, payment methods, payments and refunds describe the calls; this page is the picture around them: what happens to a debit after you send it, what Payra holds as evidence, what is screened, and what the network allows.

​
How a debit moves

A debit is not a card authorization. Nothing is approved or declined at the moment you charge; the processor accepts the instruction, puts it in its next batch to the bank, and the bank answers later, by moving the money or by sending it back.
  1. Collection. The account holder enters the account in Payra Elements and accepts the debit authorization, or your server sends an account it holds with your attestation. Payra stores the account as a token and keeps its last four digits.
  2. Charge. POST /payments sends the debit to the processor. The payment is processing.
  3. Settlement. The processor’s batch goes to the bank once a banking day; the payment turns succeeded, with succeeded_at, and payment.succeeded is sent. Timing is on the payments page under when a debit settles.
  4. Return, if any. The bank can send the debit back, before settlement (it refuses the entry) or after it. The payment turns returned and payment.returned is sent.
There is no instant rail and no same-day confirmation: the right model is “accepted, then settled, then final after the return window”, and the webhooks mark each step.

​
Standard Entry Class (SEC) codes

Every ACH entry carries a Standard Entry Class code, which tells the bank what kind of authorization stands behind it. It is set from the account you collected, by Payra or by its processor from the holder type Payra passes on; you do not send it. The network also defines PPD and TEL for an individual’s account authorized on paper or by phone; a debit Payra sends for you carries WEB or CCD by holder type, whichever way the authorization was obtained, and your attestation records how it was. The code matters because the rules differ: a consumer (WEB) can dispute a debit as unauthorized for 60 calendar days after it posts; a company (CCD) has two banking days. Collect a business account as company when it is one: it is the holder’s own designation, and it changes both the rule and the risk.

​
Authorization and its proof

Every debit Payra makes is backed by an authorization it recorded at collection and never changes afterwards:
  • In Payra Elements, the account holder is shown the authorization text with your name and, for a one-time debit, the amount filled in, and accepts it with a checkbox. Payra records the version and the full text they saw, the payee, the amount, the server’s time of acceptance, the holder’s IP address and browser, and that it was the holder who accepted. The session’s ach_authorization is that record, with scope: "single" for one amount and scope: "standing" for an account saved to a customer, which covers whatever that customer owes.
  • From your server, the record is your attestation instead: how the holder authorized the debit (verbal, written, online_checkbox), when, and, when you have them, from where. You confirm in it that you keep the original authorization for two years after it ends, and that a one-time debit authorized by phone was recorded or confirmed in writing before it settles.
The charge and the saved payment method both cite the record, so when a bank asks for proof of authorization on a disputed debit, the answer comes from Payra’s records: read the session with GET /payment-method-sessions/{id}. Keep the pms_… id with your order.

​
Preventative screening

Nacha requires the originator of a WEB debit to run a “commercially reasonable” fraud detection system, and since 2021 that includes validating the account the first time it is used. Payra’s checks happen before a debit is sent, and most of them before anything is stored:
  • The numbers. routing_number must be a real US routing number (a prefix the Federal Reserve issues, a valid check digit) and account_number 7 to 17 digits. A request that fails this is refused with 400 parameter_invalid and nothing is kept.
  • The account. When a US account is saved to a customer, it is verified with the workspace’s processor before it is tokenized; where the processor validates accounts, the account number and the holder’s name are checked together. A processor that refuses the account refuses the save: 402 bank_account_verification_failed on the confirm, and nothing is kept on the customer’s file.
  • The authorization, recorded as above, with the holder’s IP address and browser when the holder accepted it in Elements.
  • The debit itself. A one-time account can be debited once, for exactly the amount the holder authorized, within 30 minutes of collection, and is spent by that charge whether it was accepted or refused. A saved account is only debited by the keys of the workspace it was saved on.
  • External account validation and pre-authorization screening. Before the first debit on an account, the processor checks it against an external account validation service: that the routing and account numbers belong to a real, open account that can receive ACH entries, which is what the network’s account validation rule asks for. The debit itself is then screened before it is sent, on the same risk engine as a card payment, so an entry that would fail or that looks high-risk is stopped before processing rather than returned days later.
  • Proactive account blocking. When a debit comes back with a terminal return that cannot be recovered (account closed, no such account, invalid account number), the processor blocks that bank account across its whole network, not only on your workspace. Any later attempt on a blocked account fails at once, as a failed payment on the create, instead of settling and returning again. That spares you repeated failures and the return-rate exposure they create; a block is lifted on evidence that the account is open again.
What Payra does not do, and the network does not offer: confirm the balance before the debit, or guarantee the debit will not be returned. The checks above lower returns; they do not remove the return window.

​
Failures and returns

A bank debit can end in three ways other than succeeded, and failure on the payment says which. A return carries a reason code from the bank; when the processor reports it, the dashboard shows it on the payment. The common ones: Two rules the network sets around retries:
  • A debit returned for insufficient funds may be presented again, at most twice, within 180 days of the original. Collect a new authorization or, when the holder’s authorization covers it, charge the saved account again.
  • A debit returned as unauthorized must not be presented again on that authorization, and the account holder can file the claim through their bank for 60 days. Unauthorized returns are counted against the originator: Nacha caps them at 0.5% of debits, and an account with a high rate is reviewed. Keep the authorization clear and the holder informed of what will be debited and when.

​
Refunds

A debit can be refunded once it has settled: POST /refunds on a succeeded payment sends the money back over the same network, as a credit to the account, and the refund reads succeeded when the processor has sent it; the bank posts it in one to a few banking days. A debit still processing cannot be refunded (payment_not_refundable): wait for payment.succeeded, or, if the goods have not shipped, let it settle and refund then. There is no same-day cancel on a bank debit through the API, since the instruction is already in the processor’s batch. The refunds page has the calls and the partial-refund rules. A returned debit needs no refund: the money never stayed. Read amount_refunded on the payment for what you sent back on purpose, and status: "returned" for what the bank took back.

​
Reversals

A reversal is not a refund. A refund is a new credit you choose to send, for any reason, once the debit has settled. A reversal is the network’s way to undo a debit that was wrong when it was sent, and the rules allow it for exactly four errors: a duplicate of an entry already sent, the wrong amount, the wrong account, or a date earlier than authorized. It must be originated within five banking days of the original’s settlement, it reverses the full amount, and the account holder must be told. A reversal for any other reason (the customer changed their mind, the goods were returned) is a misuse of the rule; those are refunds. On the API a debit has no reversal call: a reversal is originated by Payra on your request, inside the five-day window, and Payra tells you how the payment was recorded once the reversing entry has gone out. If the error is caught before the debit settles (it still reads processing), tell Payra at once; the window is shortest then. For everything else, use POST /refunds once the payment is succeeded.

​
Saving an account for later debits

An account collected in a session that names a customer is saved on that customer’s file under a standing authorization: the holder accepted, once, that the account may be debited for what they owe you. Every later charge is POST /payments with the saved pm_… and the amount, no new collection and no new authorization, and the payment carries the same us_bank_account block. The account stays until you detach it or the holder revokes the authorization, in which case the next debit comes back as unauthorized: detach the account when they tell you, and do not debit it again. Payra never stores the account number itself: it holds a processor token and the last four digits, and the token only works for the workspace that created it. See Customers for creating the customer and payment methods for listing what is on file.

​
Nacha rules: what you agree to by debiting an account

Debiting a US bank account makes you the originator of the entry, and Nacha’s operating rules apply to you as they do to Payra and the processor. In practice they come to this:
  • Authorization first. Obtain the account holder’s authorization before the first debit, in a form the holder can keep: the Elements checkbox and text, a signed form, or a recorded call with written confirmation. The authorization states who will debit, how much or on what schedule, and how it can be revoked.
  • Keep the proof. Retain the authorization for two years after it ends, and produce it when a bank asks. Payra’s record is yours to read, but the attestation you send from your server is a statement about proof you hold.
  • Tell the holder. Give notice before a debit whose amount or date differs from what was authorized, and stop debiting when the holder revokes.
  • Validate the account before the first WEB debit on it, and run fraud detection on web-authorized debits. Payra’s screening above is what covers this on debits it collects.
  • Keep returns low. Unauthorized returns above 0.5% of debits, and overall returns above 15%, put the originator under review and can end the ability to debit.
This is a summary for integrators, not the rules themselves. The current operating rules and the return reason codes are published by Nacha.