Accept an ACH Direct Debit payment
Build a custom payment form or use Stripe Checkout to accept payments with ACH Direct Debit.
Cuidado
A Stripe pode apresentar automaticamente as formas de pagamento relevantes aos seus clientes avaliando moedas, restrições de formas de pagamento e outros parâmetros.
- Siga o guia Aceitar um pagamento para elaborar uma integração de checkout que usa formas de pagamento dinâmicas.
- Se você não quiser usar o formas de pagamento dinâmico, siga as etapas abaixo para configurar manualmente as formas de pagamento em sua integração de checkout.
Stripe users in the US can use Checkout in payment mode to accept ACH Direct Debit payments.
A Checkout Session represents the details of your customer’s intent to purchase. You create a Session when your customer wants to pay for something. After redirecting your customer to a Checkout Session, Stripe presents a payment form where your customer can complete their purchase. After your customer completes a purchase, they redirect back to your site.
With Checkout, you can create a Checkout Session with us_ as a payment method type to track and handle the states of the payment until the payment completes.
Nota
ACH Direct Debit is a delayed notification payment method, which means that funds aren’t immediately available after payment. A payment typically takes 4 business days to arrive in your account.
Determine compatibility
To support ACH Direct Debit payments, make sure you express Prices for all line items in US dollars (currency code usd).
Create or retrieve a customerRecommendedServer-side
Create a Customer object when your user creates an account with your business, or retrieve an existing Customer associated with this user. Associating the ID of the Customer object with your own internal representation of a customer enables you to retrieve and use the stored payment method details later. Include an email address on the Customer to enable Financial Connections’ return user optimization.
Accept a payment
Nota
Build an integration to accept a payment with Checkout before using this guide.
This guides you through enabling ACH Direct Debit and shows the differences between accepting payments using dynamic payment methods and manually configuring payment methods.
Enable ACH Direct Debit as a payment method
When creating a new Checkout Session, you need to:
- Add
us_to the list ofbank_ account payment_.method_ types - Make sure all your
line_use theitems usdcurrency.
By default, collecting bank account payment information uses Financial Connections to instantly verify your customer’s account, with a fallback option of manual account number entry and microdeposit verification. See the Financial Connections docs to learn how to configure Financial Connections and access additional account data to optimize your ACH integration. For example, you can use Financial Connections to check an account’s balance before initiating the ACH payment.
Nota
To expand access to additional data after a customer authenticates their account, they must re-link their account with expanded permissions.
If the customer opts for microdeposit verification instead of Financial Connections, Stripe automatically sends two small deposits to the provided bank account. These deposits can take 1-2 business days to appear on the customer’s online bank statement. When the deposits are expected to arrive, the customer receives an email with a link to confirm these amounts and verify the bank account with Stripe. After verification is complete, the payment begins processing.
We recommend including the payment_intent_data.setup_future_usage parameter with a value of off_ when creating a payment mode Session for ACH Direct Debit so you can save payment method details.
Fulfill your orders
After accepting a payment, learn how to fulfill orders.
Test your integration
Saiba como testar cenários com verificações instantâneas usando Financial Connections.
Enviar e-mails transacionais em uma área restrita
Depois de coletar os dados da conta bancária e aceitar uma instrução, envie os e-mails de confirmação de mandato e verificação de microdepósito em uma área restrita.
Se seu domínio for {domain} e seu nome de usuário é {username}, use o seguinte formato de e-mail para enviar e-mails de teste de transação: {username}+test_email@{domain}.
Por exemplo, se seu domínio é example.com e seu nome de usuário é info, use o formato info+test_email@example.com para testar pagamentos por ACH Direct Debit. Esse formato garante que os e-mails sejam encaminhados corretamente. Se não incluir o sufixo +test_email, não enviaremos o e-mail.
Erro comum
Você precisa ativar sua conta Stripe antes de enviar esses e-mails durante os testes.
Números de conta de teste
A Stripe fornece vários números de conta de teste e tokens correspondentes que você pode usar para verificar se sua integração para contas bancárias inseridas manualmente está pronta para produção.
| Número da conta | Token | Routing number | Comportamento |
|---|---|---|---|
000123456789 | pm_ | 110000000 | O pagamento é aprovado. |
000111111113 | pm_ | 110000000 | O pagamento falha porque a conta está fechada. |
000000004954 | pm_ | 110000000 | O pagamento foi bloqueado pelo Radar devido a um alto risco de fraude. |
000111111116 | pm_ | 110000000 | O pagamento falha porque nenhuma conta foi encontrada. |
000222222227 | pm_ | 110000000 | O pagamento falha devido a fundos insuficientes. |
000333333335 | pm_ | 110000000 | O pagamento falha porque o uso de débitos não está autorizado. |
000444444440 | pm_ | 110000000 | O pagamento falha porque a moeda é inválida. |
000666666661 | pm_ | 110000000 | O pagamento não consegue enviar microdepósitos. |
000555555559 | pm_ | 110000000 | O pagamento aciona uma contestação. |
000000000009 | pm_ | 110000000 | O pagamento permanece em processamento indefinidamente. Útil para testar cancelamento do PaymentIntent. |
000777777771 | pm_ | 110000000 | O pagamento falha devido ao valor do pagamento fazer com que a conta exceda seu limite de volume de pagamentos semanal. |
000888888885 | 110000000 | O pagamento falha devido a um número de conta tokenizado desativado. |
Antes que as transações de teste possam ser concluídas, você precisa verificar todas as contas de teste que aprovam ou falham automaticamente o pagamento. Para fazer isso, use as quantias de microdepósito de teste ou códigos de descrição abaixo.
Testar valores de microdepósito e códigos de descrição
Para simular diferentes cenários, use estas quantias de microdepósito ou valores de código de descrição 0,01.
| Valores de microdepósito | Valores de código da descrição 0,01 | Cenário |
|---|---|---|
32 e 45 | SM11AA | Simula a verificação da conta. |
10 e 11 | SM33CC | Simula o excesso de tentativas permitidas de verificação. |
40 e 41 | SM44DD | Simula um tempo limite de microdepósito. |
Testar o comportamento da liquidação
As transações de teste são liquidadas instantaneamente e adicionadas ao seu saldo de teste disponível. Esse comportamento é diferente do modo de produção, em que as transações podem demorar vários dias para serem liquidadas no saldo disponível.
Additional considerations
Microdeposit verification failure
When a bank account is pending verification with microdeposits, the customer can fail to verify for three reasons:
- The microdeposits failed to send to the customer’s bank account (this usually indicates a closed or unavailable bank account or incorrect bank account number).
- The customer made 10 failed verification attempts for the account. Exceeding this limit means the bank account can no longer be verified or reused.
- The customer failed to verify the bank account within 10 days.
If the bank account fails verification for one of these reasons, you can handle the checkout. event to contact the customer about placing a new order.
OpcionalInstant only verification
By default, ACH Direct Debit payments allow your customers to use instant bank account verification or microdeposits. You can optionally require instant bank account verification only using the payment_ parameter when you create the Checkout session.
OpcionalAccess data on a Financial Connections bank account
You can only access Financial Connections data if you request additional data permissions when you create your PaymentIntent .
After your customer successfully completes the Checkout flow, the us_ PaymentMethod returned includes a financial_connections_account ID that points to a Financial Connections Account. Use this ID to access account data.
Erro comum
Bank accounts that your customers link through manual entry and microdeposits don’t have a financial_ ID on the Payment Method.
To determine the Financial Connections account ID, retrieve the Checkout Session and expand the payment_ attribute:
{ "id": "{{CHECKOUT_SESSION_ID}}", "object": "checkout.session", // ... "payment_intent": { "id": "{{PAYMENT_INTENT_ID}}", "object": "payment_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", // ... "type": "us_bank_account", "us_bank_account": { "account_holder_type": "individual", "account_type": "checking", "bank_name": "TEST BANK", "financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", "fingerprint": "q9qchffggRjlX2tb", "last4": "6789", "routing_number": "110000000" } } // ... } }
Learn more about using additional account data to optimize your ACH integration with Financial Connections.
OpcionalResolve disputesServer-side
Customers can generally dispute an ACH Direct Debit payment through their bank for up to 60 calendar days after a debit on a personal account, or up to 2 business days for a business account. In rare instances, a customer might be able to successfully dispute a debit payment outside these standard dispute timelines.
When a customer disputes a payment, Stripe sends a charge.dispute.closed webhook event, and the PaymentMethod authorization is revoked.
In rare situations, Stripe might receive an ACH failure from the bank after a PaymentIntent has transitioned to succeeded. If this happens, Stripe creates a dispute with a reason of:
insufficient_funds incorrect_account_ details bank_can't_ process
Stripe charges a failure fee in this situation.
Future payments reusing this PaymentMethod return the following error:
{ "error": { "message": "This PaymentIntent requires a mandate, but no existing mandate was found. Collect mandate acceptance from the customer and try again, providing acceptance data in the mandate_data parameter.", "payment_intent": { ... } "type": "invalid_request_error" } }
This error contains a PaymentIntent in the requires_ state. To continue with the payment, you must:
- Resolve the dispute with the customer to ensure future payments will not be disputed.
- Confirm authorization from your customer again.
To confirm authorization for the payment, you can collect mandate acknowledgement from your customer online with Stripe.js or confirm authorization with your customer offline using the Stripe API.
Cuidado
If a customer disputes more than one payment from the same bank account, Stripe blocks their bank account. Contact Stripe Support for further resolution.
OpcionalReferência do pagamento
The payment reference number is a bank-generated value that allows the bank account owner to use their bank to locate funds. When the payment succeeds, Stripe provides the payment reference number in the Dashboard and inside the Charge object.
| Charge State | Payment Reference Value |
|---|---|
| Pendentes | Não disponível |
| Malsucedidos | Não disponível |
| Concluída | Available (for example, 091000015001234) |
In addition, when you receive the charge. webhook, view the content of payment_ to locate the payment_reference.
The following example event shows the rendering of a successful ACH payment with a payment reference number.
{ "id": "{{EVENT_ID}}", "object": "event", // omitted some fields in the example "type": "charge.succeeded", "data": { "object": { "id": "{{PAYMENT_ID}}", "object": "charge", //... "paid": true, "payment_intent": "{{PAYMENT_INTENT_ID}}", "payment_method": "{{PAYMENT_METHOD_ID}}", "payment_method_details": { "type": "us_bank_account", "us_bank_account": { "account_holder_type": "individual", "account_type": "checking", "bank_name": "TEST BANK", "fingerprint": "Ih3foEnRvLXShyfB", "last4": "1000", "payment_reference": "091000015001234", "routing_number": "110000000" } } // ... } } }
View the contents of the destination_ to locate the refund reference associated with the refunded ACH payments.
The following example event shows the rendering of a successful ACH refund with a refund reference number. Learn more about refunds.
{ "id": "{{EVENT_ID}}", "object": "event", "type": "charge.refund.updated", "data": { "object": { "id": "{{REFUND_ID}}", "object": "refund", //... "payment_intent": "{{PAYMENT_INTENT_ID}}", "destination_details": { "type": "us_bank_transfer", "us_bank_transfer": { "reference": "091000015001111", "reference_status": "available" } } // ... } } }
OpcionalConfigure customer debit dateServer-side
You can control the date that Stripe debits a customer’s bank account using the target date. The target date must be at least three days in the future and no more than 15 days from the current date.
The target date schedules money to leave the customer’s account on the target date.
Target dates that meet one of the following criteria delay the debit until the next available business day:
- Target date falls on a weekend, a bank holiday, or other non-business day.
- Target date is fewer than three business days in the future.
This parameter operates on a best-effort basis. Each customer’s bank might process debits on different dates, depending on local bank holidays or other reasons.
Cuidado
You can’t set the verification method to microdeposits when using a target date, as the verification process could take longer than the target date, causing payments to arrive later than expected.