Accept ACH direct debit payments
Last updated: Oct 30th, 9:59am
Use ACH direct debit payments to accept payments from a payer by debiting directly from their bank account. For example, government agencies may use this feature for one-time payments for taxes, citations, or permit fees.
ACH direct debit can be used for one-time and Recurring payments. You can only transact in USD.
Know before you code
- Complete Merchant Onboarding.
- The instructions in Get Started will help you get your access token.
- This server-side integration uses the Orders REST API.
- Your chargeback and bank unauthorized rates must be less than 0.25%.
- Set
intent: capture
in the create order call for this feature to work. - Review the Nacha rules and other risks associated with ACH direct debit payments.
Review the liabilities
If an ACH payment is returned by your payer's bank, you are liable for the transaction amount PayPal might have already moved to your account and the return fees. These charges are reflected in the PayPal account set up during onboarding.
Understand the differences between unauthorized returns and the remaining type of returns to evaluate and control your exposure to any losses and manage your refund process. At a high level, the differences are as follows:
-
Unauthorized returns: Your payer can raise an unauthorized dispute anytime after the funds move out of their bank account to yours, within a timeframe of 60 days for consumer accounts and two days for business accounts. In unauthorized dispute cases, PayPal will charge your account in the amount of the original transaction amount plus a $5 dispute fee.
-
Other types of returns: Any non-unauthorized type of return, such as insufficient funds, invalid or closed account, or other reasons will not result in funds clearance. With these types of returns, you have less exposure to losses, unless you had requested PayPal to process the transaction as instant ACH. In the case you receive a non-unauthorized return and submitted the payment as standard ACH, then you will be liable for only the return fee. However, if you submitted the transaction as an instant ACH payment, then you will be liable for both the original transaction amount PayPal couldn't debit from your payer's bank account and the return fee.
You might be unnecessarily crediting your payer if you are issuing a refund to your payer, but the transaction gets returned from your payer's bank as a result of insufficient funds. To prevent any fraud or double-crediting your payers we recommend you:
- Don't issue a refund until after the funds settle in your account.
- Communicate to your payer immediately that you have started the refund process, and it will take at least 5 calendar days for them to receive the funds back in their bank account.
- Don't ship your product or service if you haven't received the funds from your payer, which should happen after 5 calendar days for funds clearance.
Review SEC options
This integration requires a standard entry class (SEC) code. The following codes are available:
- Telephone Initiated Entry (TEL)
- Internet Initiated Entry (WEB)
- Corporate Credit or Debit (CCD)
- Prearranged Payment and Deposit Entry (PPD)
TEL
TEL
entries are one-time consumer debit entries authorized by your payer over telephone. You must collect an oral authorization from your payer or provide a written notice, prior to the settlement date of the TEL entry, confirming the terms of the oral authorization. As per Nacha rules, the authorization should include the following:
- The date on or after the consumer’s account will be debited
- The amount of the debit entry to the consumer’s account
- The consumer’s name
- A telephone number that is available to the consumer and answered during normal business hours for payer inquiries
- The date of the consumer’s oral authorization
- A statement by you that the consumer’s authorization will be used to originate an ACH debit to the consumer’s account
WEB
WEB
entries are direct debit payments initiated online. You must collect the authorization from your customer online. Please refer to section on Authorization for a sample authorization you can use for WEB
transactions. To remain in compliance with NACHA regulations, we recommend you store the full text of the authorization and following information as proof of consent:
- Amount of transaction and bank details
- Timestamp that indicates what date and time the consumer authorized the debit
CCD
CCD
entries are used if you are debiting from a business bank account. The unauthorized return window is two business days if your payer has used a business bank account. The return window for consumer bank accounts is 60 days.
PPD
PPD
entries are used when payment is initiated to a consumer account based on a standing or single entry authorization you obtained from your payer. Like WEB
authorizations, PPD
transactions must have an authorization with clear and readily understandable terms.
Please refer to section on Authorization for a sample authorization you can use for PPD
transactions.
Authorization
For all ACH transactions, you are required to collect an authorization from the customer indicating that you have their explicit permission to debit their bank account. To remain in compliance with NACHA regulations, we recommend you store the full text of the authorization with amount of transaction, bank details and timestamp of authorization. You may be required to provide proof of the authorization when requested by PayPal, customer’s bank or by NACHA.
A reference authorization text is provided below. Include this text or a variation in your checkout flow, at or near the final "buy" (checkout, complete, submit etc.) button.
To support recurring payments with varying amounts:
By clicking ["Checkout/Submit"], I authorize PayPal, on behalf of [your business name here] to verify my bank account information using bank information and consumer reports and I authorize [your business name here] to initiate an ACH/electronic debit to my checking/savings account, Depository Name: [customer name], Routing Number: [customer’s bank routing number] and Account Number: [customer’s bank account number], that will be stored on file, and debited on or after the due date. I agree the ACH transactions I authorize comply with all applicable laws. I understand that this authorization will remain in full force and effect until I notify [your business name here] that I wish to revoke this authorization.
To support a One-time payment:
By clicking ["Checkout/Submit"], I authorize PayPal, on behalf of [your business name here] to verify my bank account information using bank information and consumer reports and I authorize [your business name here] to initiate an ACH/electronic debit to my checking/savings account, Depository Name: [customer name], Routing Number: [customer’s bank routing number] and Account Number: [customer’s bank account number], in the amount of [$XXX] on [date]. I agree the ACH transactions I authorize comply with all applicable laws.
Tokenize Bank Account Information
We can save your customer's bank account information, so they don’t have to re-enter details for future transactions. Customers can check out faster or pay without being present after they agree to save their bank account information.
The bank account information will be securely stored in our vault and exchanged for a unique token through a process called tokenization. You can store the token and use that instead of the original bank account information.
The benefits of using tokens include:
- Increased security by reducing opportunities for data theft.
- Simplified payment processing and faster checkout.
- Maintain compliance in storing of sensitive data.
Tokenizing bank account information :
Tokenize by providing bank account information - account_number
, routing_number
, account_type
, ownership_type
, account_holder_name
and verification_method
.
- Basic bank details are also returned with tokens. Basic bank details include last-4 digits and routing number. Use these in flows/experiences to help customer identify their bank.
- Tokenize with or without a transaction.
- With a transaction - Provide bank account details along with the order information in the Orders API. The bank details will be saved if the transaction is setup successfully. Token and basic bank details will be available in the response.
- Without a transaction - Provide bank account details on the Vault API and receive token and basic bank details in the response.
Using tokens :
To use a token in a transaction, simply provide the token instead of the bank account information in the ACH Debit object.
Detokenizing :
Retrieve full bank account information by providing the token in the detokenize Vault APIs.
Step 1: Create an order
To create an order for standard ACH direct debit payments, copy the following code and modify it:
1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders2 -H 'Content-Type: application/json'3 -H 'Authorization: Bearer ACCESS-TOKEN'4 -d '{5 "intent": "CAPTURE",6 "purchase_units": [7 {8 "amount": {9 "currency_code": "USD",10 "value": "100.00"11 },12 "payee": {13 "email_address": "merchant@example.com"14 }15 }16 ]17 }'
Modify the code
After you copy the code in the sample request, modify the following:
- Change
ACCESS-TOKEN
to your access token. - Set
intent
tocapture
. - Change the
standard_entry_class_code
. Options areTEL
,WEB
,CCD
, andPPD
. - Optional: Change the
purchase_unit/payment_instruction/platform_fees
array to specify fees for the order.
Step result
A successful request results in the following:
- A return status code of HTTP
201 Created
. - A JSON response body that contains the order ID. You'll use the order ID to capture the order.
Step 2: Capture an order
Before you can capture an order using ACH direct debit:
- The bank account must be verified before you can collect any money from that account.
- The payer must authorize the direct debit. See Authorization section for more information.
- Standard Entry Classification (SEC) codes are used to define how your payer has authorized the payment. PayPal accepts WEB, TEL, CCD, and PPD SEC codes. The default is WEB.
- The status of the order must be APPROVED. The order status is set to APPROVED when the payer successfully completes the checkout flow.
- Bank account information collected from the customer can be tokenized. It is recommended that you always tokenize the bank account information and use the token for subsequent transactions from this bank account.
After the bank account is verified and the payer authorizes the direct debit, you call capture order to capture the payer's funds. Provide the customer’ full bank account information or equivalent token during the capture call.
With full bank account information :
Copy the following code and modify it:
1curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture2 -H 'Authorization: Bearer ACCESS-TOKEN;'3 -H 'Content-Type: application/json'4 -d '{5 "payment_source": {6 "bank": {7 "ach_debit": {8 "account_number": "ACCOUNT-NUMBER",9 "routing_number": "ROUTING-NUMBER",10 "account_holder_name": "ACCOUNT-HOLDER-NAME",11 "account_type": "ACCOUNT-TYPE",12 "ownership_type": "OWNERSHIP-TYPE",13 "attributes": {14 "vault": {15 "store_in_vault": "ON_SUCCESS"16 }17 },18 "stored_credential": {19 "payment_initiator": "CUSTOMER",20 "payment_type": "RECURRING",21 "usage": "FIRST"22 },23 "payment_context": {24 "standard_entry_class_code": "WEB"25 }26 }27 }28 }29 }'
Modify the code
- Change
Access-Token
to your access token. - Change following placeholders with the customer bank account information.
ACCOUNT-NUMBER
ROUTING-NUMBER
ACCOUNT-HOLDER-NAME
ACCOUNT-TYPE
- (CHECKING or SAVINGS)- and
OWNERSHIP-TYPE
- (PERSONAL or BUSINESS)
- For
CCD
transactions, always set"standard_entry_class_code": "CCD"
and"ownership_type": "BUSINESS"
in the body ofach_debit
. - Optional: Change the transaction to an instant ACH transfer instead of standard. To change to an instant transfer, add
"payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
in the body ofpayment_context
.
Step result
A successful result for a standard ACH direct debit returns the following:
-
If the transaction is not declined, the response is
PAYMENT.CAPTURE.PENDING
. This status changes in 5 calendar days to eitherPAYMENT.CAPTURE.COMPLETED
orPAYMENT.CAPTURE.DENIED
. -
If the payment is completed, the response is
PAYMENT.CAPTURE.COMPLETED
. This payment can be returned in certain situations, such as with an unauthorized return. Use the daily Financial Summary Report to identify any bank returns for direct debit payments and reason codes for the return. -
If the payment is declined, the response is
PAYMENT.CAPTURE.DENIED
. A payment may be declined for incorrect routing or account numbers or for other reasons. -
The tokenized bank account information is uniquely identified by the value in
vault.id
. Store this token against your customer’s account and use it for subsequent transactions using this bank. PayPal also provides a unique reference to your customer invault.customer.id
. -
Tokenization will also provide
ach_debit.last_digits
andach_debit.routing_number
in the response. Use these in any flow/experiences to allow customers to identify their bank account.
With token instead of full bank account information
- If you have previously tokenized the bank account information, you may use that instead. Copy the following code and modify it:
1curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/capture2 -H 'Authorization: Bearer ACCESS-TOKEN;'3 -H 'Content-Type: application/json'4 -d '{5 "payment_source": {6 "bank": {7 "ach_debit": {8 "vault_id": "VAULT-ID",9 "stored_credential": {10 "payment_initiator": "MERCHANT",11 "payment_type": "RECURRING",12 "usage": "SUBSEQUENT"13 },14 "payment_context": {15 "standard_entry_class_code": "WEB"16 }17 }18 }19 }20 }'
Modify the code
- Change
Access-Token
to your access token. - Pass the
VAULT-ID
returned from bank account Tokenization.
Step result
A successful result for a standard ACH direct debit returns the following:
-
If the transaction is not declined, the response is PAYMENT.CAPTURE.PENDING. This status changes in 5 calendar days to either PAYMENT.CAPTURE.COMPLETED or PAYMENT.CAPTURE.DENIED.
-
If the payment is completed, the response is PAYMENT.CAPTURE.COMPLETED. This payment can be returned in certain situations, such as with an unauthorized return. Use the daily Financial Summary Report to identify any bank returns for direct debit payments and reason codes for the return.
-
If the payment is declined, the response is PAYMENT.CAPTURE.DENIED. A payment may be declined for incorrect routing or account numbers or for other reasons.
Review daily reports
Refer to the daily reports to reconcile all returns you received on that day. Then, you can work with any payer on the steps they should take to resubmit the payment. Use the following reports:
Decline Analysis Report
The Decline Analysis Report contains all returned/declined standard ACH debit transactions including the reason codes received from the ACH network.
Financial Summary Report
The Financial Summary Report contains the liability charges posted on your account as a result of returned ACH debit transactions. Instant ACH transactions that resulted in bank returns are also included in this daily report. The report includes the original transaction that was returned and what fees you incurred from returned transactions.
Review reason codes
If an ACH transaction is returned by your payer's bank, a reason code for the returned transaction is included. Depending on the reason code, the transaction can be corrected and re-submitted for processing.
The table below provides return reason codes and explains what steps you can take if an ACH transaction was not processed and returned to you:
Reason Code | Description | What it means | What you should do |
---|---|---|---|
R01 | Insufficient Funds | The bank account you submitted to PayPal for payment does not have sufficient balance to cover the amount on the transaction. | Contact your payer immediately to avoid any disruption in the service or the delivery of your product, and let them know you were not able to charge their bank account as a result of insufficient funds. You can ask them to add funds to their bank account and have them go through the payment experience again, or present them an option to pay with a different bank account or a different payment method and submit a new transaction. |
R02 | Account Closed | The bank account you submitted for payment has been closed. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R03 | No Account/Unable to Locate Account | The bank account you submitted for payment is invalid. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R04 | Invalid Account Number Structure | The bank account you submitted for payment is invalid. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R05 | Unauthorized Debit to Consumer Account Using Corporate SEC Code | Payment has been submitted on a corporate account using a consumer SEC code. | Correct the payment SEC code and resubmit. |
R06 | Returned per ODFI’s Request | Payment stopped as required by PayPal. | Resubmit the transaction. If PayPal has stopped payment on your behalf, contact PayPal. |
R07 | Authorization Revoked by Customer | Payment has been marked as unauthorized by payer. Payment has been reversed by payer by revoking authorization. | Contact payer to resolve the issue. |
R08 | Payment Stopped | Stop payment issued by payer on account for PayPal Payment has been stopped by payer. | Contact payer to resolve the issue. |
R09 | Uncollected Funds | Collected funds are not sufficient for payment of the debit entry | Contact the payer to inform them of insufficient funds. As per your procedures you may resubmit the transaction or request the payer to update payment method or payment account. |
R10 | Customer Advises Unauthorized, Improper, Ineligible, or part of an Incomplete Transaction | Payment has been marked as unauthorized by payer. Payment has been reversed by payer by revoking authorization. | Contact payer to resolve the issue. |
R12 | Account Sold to another DFI | RDFI is unable to post entry destined for a bank account maintained at a branch sold to another financial institution. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R13 | Invalid ACH Routing Number | Financial institution does not receive commercial ACH entries. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R14 | Representative Payee Deceased or Unable to Continue in that capacity | The representative payee authorized to accept entries on behalf of a beneficiary is either deceased or unable to continue in that capacity. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R15 | Beneficiary of Account Holder Deceased | The beneficiary entitled to payments is deceased and/or the bank account holder other than a representative payee is deceased. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R16 | Account Frozen/Entry Returned per OFAC Instruction | Funds in bank account are unavailable due to action by RDFI or legal order. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R17 | File Record Edit Criteria | Certain payment fields rejected by RDFI processing (identified in return addenda) | Correct the payment fields and resubmit. |
R20 | Non Transaction Account | The ACH entry is sent to a non-transaction account. | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |
R24 | Duplicate Entry | RDFI has received a duplicate entry. | Check if this transaction was a duplicate or has already completed, before resending the payment. |
R29 | Corporate Customer Advises not authorized | Payment has been marked as unauthorized by payer. | Payment has been reversed by payer by revoking authorization. Contact payer to resolve the issue. |
R34 | Limited Participation DFI | RDFI participation has been limited by a federal or state supervisor | Contact the payer to update payment method or payment account. Stop any recurring payments from this account. If the transaction you received this code on is a prenote, don't process any further transactions on this account. |