ACH Direct Debit

Steps to integrate S2S JSON API and accept payments using ACH Direct Debit.

Available in🇮🇳 India

ACH (Automated Clearing House) is an electronic network that processes bank-to-bank payments in batches. ACH Direct Debit enables you to withdraw funds directly from a customer’s US bank account using their account and routing numbers, with transactions settling within 3-5 business days.

Integration Steps

Follow the steps below to integrate Razorpay S2S JSON API and accept payments using ACH.

1.1 Create an Order

1.2 Create a Payment

1.3 Handle Payment Success and Error Events

1.4 Integrate Payments Rainy Day Kit

1.5 Fetch Payment Details and Verify Payment Status

1.1 Create an Order

To process a payment, create a Razorpay Order to correspond with the order in your system. Send the order request parameters to the following endpoint:

Order is an important step in the payment process.

• An order should be created for every payment.
• You can create an order using the Orders API. It is a server-side API call. Know how to authenticate Orders API.
• The order_id received in the response should be passed to the checkout. This ties the order with the payment and secures the request from being tampered.

Watch Out!

Payments made without an order_id cannot be captured and will be automatically refunded. You must create an order before initiating payments to ensure proper payment processing.

You can create an order:

• Using the sample code on the Razorpay Postman Public Workspace.
• By manually integrating the API sample codes on your server.

Razorpay Postman Public Workspace

You can use the Postman workspace below to create an order:

Handy Tips

Under the Authorization section in Postman, select Basic Auth and add the Key Id and secret as the Username and Password, respectively.

API Sample Code

Use this endpoint to create an order using the Orders API.

POST /orders

Curl

curl -X POST https://api.razorpay.com/v1/orders
-U [YOUR_KEY_ID]:[YOUR_KEY_SECRET]
-H 'content-type:application/json'
-d '{
 "amount": 500,
 "currency": "INR",
 "receipt": "qwsaq1",
 "partial_payment": true,
 "first_payment_min_amount": 230,
 "notes": {
   "key1": "value3",
   "key2": "value2"
 }
}'

Success Response

{
 "id": "order_IluGWxBm9U8zJ8",
 "entity": "order",
 "amount": 5000,
 "amount_paid": 0,
 "amount_due": 5000,
 "currency": "INR",
 "receipt": "rcptid_11",
 "offer_id": null,
 "status": "created",
 "attempts": 0,
 "notes": [],
 "created_at": 1642662092
}

Request Parameters

amount mandatory : integer Payment amount in the smallest currency subunit. For example, if the amount to be charged is ₹299, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to accept a payment of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, to accept a payment of 295, pass the value as 295.

Watch Out!

As per payment guidelines, you should pass the last decimal number as 0 for three decimal currency payments. For example, if you want to charge a customer 99.991 KD for a transaction, you should pass the value for the amount parameter as 99990 and not 99991.

currency mandatory : string The currency in which the transaction should be made. See the list of supported currencies. Length must be 3 characters.

Handy Tips

Razorpay has added support for zero decimal currencies, such as JPY and three decimal currencies, such as KWD, BHD and OMR, allowing businesses to accept international payments in these currencies. Know more about Currency Conversion (May 2024).

receipt optional : string Your receipt id for this order should be passed here. Maximum length is 40 characters.

notes optional : json object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.

partial_payment optional : boolean Indicates whether the customer can make a partial payment. Possible values:

• true: The customer can make partial payments.
• false (default): The customer cannot make partial payments.

first_payment_min_amount optional : integer Minimum amount that must be paid by the customer as the first partial payment. For example, if an amount of ₹7000 is to be received from the customer in two installments of #1 - ₹5000, #2 - ₹2000 then you can set this value as 500000. This parameter should be passed only if partial_payment is true.

Know more about Orders API.

Response Parameters

Descriptions for the response parameters are present in the Orders Entity parameters table.

Error Response Parameters

The error response parameters are available in the API Reference Guide.

1.2 Create a Payment

Once an order is created, your next step is to create a payment. The following API will create a payment with ach as the payment method:

POST /payments/create/json

Request

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/payments/create/json \
-H "content-type: application/json" \
-d '{
  "amount": 50000,
  "currency": "INR",
  "order_id": "order_GAWN9beXgaqRyO",
  "email": "<email>",
  "contact": "<phone>",
  "method": "ach",
  "bank_account": {
    "account_number": "000000001234",
    "name": "<name>",
    "bank_code": "122105278",
    "bank_code_category": "routing_number",
    "account_type": "personal_savings"
  },
  "billing_address": {
    "line1": "Block",
    "line2": "Street",
    "city": "San Jose",
    "state": "California",
    "postal_code": "33154"
  }
}'

Success Response

{
   "razorpay_payment_id": "pay_29QQoUBi66xm2f",
   "razorpay_order_id": "order_GAWN9beXgaqRyO",
   "razorpay_signature": "9ef4dffbfd84f1318f6ae648f114332d8401e0949a3d"
}

Request Parameters

amount mandatory : integer Payment amount in the smallest currency sub-unit. For example, if the amount to be charged is ₹299, then pass 29900 in this field.

currency mandatory : string Currency code for the currency in which you want to accept the payment. For example, USD.

order_id mandatory : string Unique identifier of the Order.
Know more about Orders API.

email mandatory : string Email address of the customer. Maximum length supported is 40 characters.

contact mandatory : string Phone number of the customer. Maximum length supported is 15 characters, inclusive of country code.

method mandatory : string Name of the payment method. Here it is ach.

bank_account mandatory : object Bank account details.

account_number mandatory : string Customer’s bank account number.

name mandatory : string Account holder’s name as per bank records.

bank_code mandatory : string The ACH routing number of the bank account.

bank_code_category mandatory : string The category of bank code. Must be routing_number for ACH payments.

account_type mandatory : string Type of bank account. Possible values:

• personal_savings: Individual savings account.
• personal_checking: Individual current account.
• business_savings: Business savings account.
• business_checking: Business current account.

billing_address optional : json object This will have details about the billing address of the customer/user.

line1 optional : string Address Line 1 of the address.

line2 optional : string Address Line 2 of the address.

city optional : string City of the address. For example, San Jose.

state optional : string Name of the state. For example, California.

postal_code optional : string Postal code of the state. For example, 33514.

The payment request for each of the supported payment methods will slightly vary. Know more about the relevant payment request fields.

Response Parameters

If the payment request is valid, the response contains the following fields:

razorpay_order_id : string Order ID returned by Razorpay Orders API.

razorpay_payment_id : string Returned by Razorpay API only for successful payments.

razorpay_signature : string A hexadecimal string used for verifying the payment.

Error Response Parameters

Error	Cause	Solution
The API <key/secret> provided is invalid.	The API credentials passed in the API call differ from the ones generated on the Dashboard. Possible reasons: Different keys for test mode and live modes. Expired API key.	The API keys must be active and entered correctly with no whitespace before or after the keys.
The amount must be at least USD 1.00.	The amount specified is less than the minimum amount. Currency subunits, such as cents (in the case of USD), should always be greater than or equal to 100.	Enter an amount equal to or greater than the minimum amount, that is 100 (representing $1.00).
You entered an account number which is invalid or not found please try again.	The bank account number provided is invalid, does not exist or does not match the format expected by the bank.	Verify that the account number is entered correctly without any spaces or special characters. Confirm the account number with the customer or check their bank statement. Ensure the account is active and not closed.
You entered a bank code which is invalid or not found please try again.	The routing number (bank code) provided is invalid or does not exist in the ACH network.	Verify that the routing number is exactly 9 digits. Ensure the routing number passes checksum validation using the formula: ((3 × d1 + 7 × d2 + 1 × d3) + (3 × d4 + 7 × d5 + 1 × d6) + (3 × d7 + 7 × d8 + 1 × d9)) % 10 == 0 Confirm the routing number with the customer or check their cheque or bank statement.
You entered an account type which is invalid please try again.	The account type provided does not match the accepted values for ACH transactions.	Ensure the account type is one of the following valid values: personal_savings, personal_checking, business_savings or business_checking. Verify that the account type matches the customer’s actual bank account type.

ACH Payment States

ACH payments progress through the following states:

• Created: Payment request has been initiated.
• Authorised: Payment has been accepted by Razorpay and submitted to the ACH network.
• Captured: Funds have been confirmed and will be settled to your account.
• Failed: Payment was rejected due to invalid account details, insufficient funds or other errors.

Payment Processing Timeline

Unlike card payments, ACH transactions are not processed in real-time. After successful payment creation:

• The payment status moves to authorised within seconds.
• However, actual bank authorisation takes 1-4 business days.
• Settlement occurs on T+5 (5 business days after transaction).
• Most returns occur within the first 5 days if there are account issues.

1.4 Handle Payment Success and Error Events

Once the payment is completed by the customer, a POST request is made to the callback_url provided in the payment request. The data contained in this request will depend on whether the payment was a success or a failure.

Success Callback

If the payment made by the customer is successful, the following fields are sent:

• razorpay_payment_id
• razorpay_order_id
• razorpay_signature

Callback Example

{
  "razorpay_payment_id": "pay_LUtJxInEqa0oAA&",
  "razorpay_order_id": "order_LUtJ52zWwapfqs&",
  "razorpay_signature": "e617a6c035cb39feb6cd16358d83a4e3d30b11d9e8e2181e6ef442da1d41df20"
}

Failure Callback

If the payment has failed, the callback will contain details of the error. Refer to Errors for details.

1.5 Integrate Payments Rainy Day Kit

Use Payments Rainy Day kit to overcome payments exceptions such as:

• Late Authorisation
• Payment Downtime
• Payment Errors

1.6 Fetch Payment Details and Verify Payment Status

After receiving the razorpay_payment_id through the callback_url, use this endpoint to fetch the payment details:

Request

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/payments/pay_LUuOjDOkeb63gS \

Handy Tips

On the Razorpay Dashboard, ensure that the payment status is captured. Refer to the payment capture settings page to know how to capture payments automatically.

You can track the payment status in three ways:

Verify Status from Dashboard

To verify the payment status from the Razorpay Dashboard:

1. Log in to the Razorpay Dashboard and navigate to Transactions → Payments.
2. Check if a Payment Id has been generated and note the status. In case of a successful payment, the status is marked as Captured.

Subscribe to Webhook Events

You can use Razorpay webhooks to configure and receive notifications when a specific event occurs. When one of these events is triggered, we send an HTTP POST payload in JSON to the webhook’s configured URL. Know how to set up webhooks.

Example

If you have subscribed to the order.paid webhook event, you will receive a notification every time a customer pays you for an order.

Poll APIs

Poll Payment APIs to check the payment status.

Next Steps

Step 2: Test Integration