Accept ACH direct debit payments

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.

  Important: You might be double-crediting your payer if you issue a refund at the same time your payer reports an unauthorized transaction to their bank.

• 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/orders
2 -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 to capture.
• Change the standard_entry_class_code. Options are TEL, WEB, CCD, and PPD.
• Optional: Change the purchase_unit/payment_instruction/platform_fees array to specify fees for the order.

  Tip: To help prevent chargebacks and unauthorized disputes, use the soft descriptor in the Orders API so that your payers can recognize the transaction when it posts to their account.

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/capture
2 -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 of ach_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 of payment_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 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.

• 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 in vault.customer.id.

• Tokenization will also provide ach_debit.last_digits and ach_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/capture
  2 -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: