Skip to content
ACHQ

Developers

Applications API for ACHQ partners.

Send merchant applications to ACHQ straight from your own software. One HTTPS call, the same review as our online application, and every merchant is credited to you automatically.

POST /api/v1/applications
curl -X POST https://www.achq.com/api/v1/applications \
  -H "Authorization: Bearer achq_test_..." \
  -H "Content-Type: application/json" \
  -d @application.json

HTTP/1.1 201 Created
{
  "id": "a0UPj00000EXAMPLE",
  "status": "received",
  "test": true
}

What it is

The Applications API is for ACHQ referral and ISO partners who want to submit merchant applications from their own software instead of sending merchants to the online form at achq.com/apply.

It takes the same fields as the online application and runs the same checks and the same underwriting. Each API key belongs to one partner, so every application you send is credited to you in our system. You never need to send a partner code.

After you submit, ACHQ emails the merchant to confirm, and our team picks up the application from there. Bank account verification and any follow-up go to the merchant directly.

Authentication

Send your API key in the Authorization header as a Bearer token on every request.

Authorization: Bearer achq_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Live keys start with achq_live_ and create real applications.
  • Test keys start with achq_test_ and create practice records only. See Test keys.
  • Call the API from your server only. Never put a key in a web page, mobile app or anything a merchant can see. If a key leaks, email us and we will turn it off and issue a new one.

Endpoint

POST https://www.achq.com/api/v1/applications
  • Body: one JSON object with the fields below. Header Content-Type: application/json.
  • One application per request. Submit one merchant at a time.
  • Any partner field in the body is ignored. Credit always comes from the key.

Fields

This table is built from the same rules the API checks, so it always matches what the API accepts. Unknown fields are ignored. Booleans must be JSON true or false, and numbers must be JSON numbers, not strings.

Business

legalbusinessname

string · Required: Yes

Legal business name as registered with the IRS. Up to 100 characters.

dba

string · Required: No

Doing business as name, if different from the legal name. Up to 100 characters.

tax_id

string · Required: Yes

EIN, 9 digits. Dashes are fine and are stripped.

business_type

string · Required: Yes

Legal structure of the business.

CorporationLLCSole ProprietorPartnershipNon-Profit

sector

string · Required: Yes

Industry category.

Digital Goods and SoftwareeCommerce and RetailEducationEntertainment And RecreationFinancial ServicesGeneral Building ServicesMedical ServicesMembership OrganizationsPersonal ServicesProfessional ServicesTravel / LodgingUtilitiesTransportation and Facilities

specific_industry

string · Required: No

Free text, for example "Bookkeeping" or "HVAC repair". Up to 100 characters.

business_description

string · Required: Yes

What the business sells and to whom. Up to 255 characters.

service_use

string · Required: No

How the merchant plans to use ACH. Defaults to business_description. Up to 255 characters.

website

string · Required: Yes

Business website. "https://" is added if missing. Up to 255 characters.

primary_phone

string · Required: Yes

Business phone, 10 to 15 digits. Any formatting is fine. Up to 40 characters.

year_started

integer · Required: No

Year the business started, for example 2019. Not in the future.

Business address

business_street

string · Required: Yes

Street address. Up to 120 characters.

business_street2

string · Required: No

Suite, unit or floor. Up to 120 characters.

business_city

string · Required: Yes

City. Up to 80 characters.

business_state

string · Required: Yes

Two-letter state code.

51 allowed values

AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY

business_zip

string · Required: Yes

ZIP or ZIP+4, for example 80003 or 80003-1234. Up to 10 characters.

state_of_registration

string · Required: Yes

State where the business is registered, two-letter code.

51 allowed values

AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY

Beneficial owner

ownerFirstName

string · Required: Yes

Owner first name. Up to 50 characters.

ownerLastName

string · Required: Yes

Owner last name. Up to 50 characters.

owner_title

string · Required: No

Owner title, for example "Owner" or "CEO". Up to 80 characters.

owner_email

string · Required: Yes

Owner email. ACHQ sends the application confirmation here. Up to 254 characters.

owner_cell

string · Required: Yes

Owner mobile phone, 10 to 15 digits. Up to 40 characters.

owner_dob

string · Required: Yes

Date of birth as YYYY-MM-DD. The owner must be 18 or older.

owner_street

string · Required: Yes

Owner home street address. Up to 120 characters.

owner_city

string · Required: Yes

Owner home city. Up to 80 characters.

owner_state

string · Required: Yes

Owner home state, two-letter code.

51 allowed values

AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY

owner_zip

string · Required: Yes

Owner home ZIP. Up to 10 characters.

owner_ssn_last4

string · Required: Yes

Last 4 digits of the owner SSN. Never send the full SSN.

Volume

charge_dollars

number · Required: When add_charges is true

Expected monthly dollar volume of charges. Must be greater than zero.

charge_count

integer · Required: When add_charges is true

Expected number of charges per month. Whole number, greater than zero.

charge_max

number · Required: When add_charges is true

Largest single charge in dollars. Must be greater than zero.

payout_dollars

number · Required: When add_payouts is true

Expected monthly dollar volume of payouts. Must be greater than zero.

payout_count

integer · Required: When add_payouts is true

Expected number of payouts per month. Whole number, greater than zero.

payout_max

number · Required: When add_payouts is true

Largest single payout in dollars. Must be greater than zero.

add_charges

boolean · Required: Yes

true if the merchant will pull money from customers. At least one of add_charges or add_payouts must be true.

add_payouts

boolean · Required: Yes

true if the merchant will send money to customers or vendors.

Customers and authorization

person_customer

boolean · Required: Yes

true if the merchant charges consumers (PPD). At least one customer type must be true.

business_customer

boolean · Required: Yes

true if the merchant charges businesses (CCD).

web_auth

boolean · Required: Yes

true if customers authorize payments online. At least one authorization method must be true.

signed_auth

boolean · Required: Yes

true if customers sign a written authorization.

phone_auth

boolean · Required: Yes

true if customers authorize payments by phone.

Customer service

statement_descriptor

string · Required: Yes

Name shown on the customer bank statement. Up to 10 characters: uppercase letters, numbers, spaces and . & - only. Up to 10 characters.

service_phone

string · Required: Yes

Phone number customers call with questions. Up to 40 characters.

service_email

string · Required: Yes

Email address customers write to with questions. Up to 254 characters.

refund_policy

string · Required: No

Refund policy text or a link to it. Up to 2000 characters.

Banking

transfer_name

string · Required: Yes

Name of the bank where ACHQ settles funds. Up to 80 characters.

transfer_routing

string · Required: Yes

9-digit ABA routing number. Must pass the ABA checksum.

transfer_account

string · Required: Yes

Settlement account number, 4 to 20 digits. Up to 20 characters.

billing_choice

boolean · Required: Yes

true to pay ACHQ fees from the settlement account. false to use a separate billing account below.

billing_name

string · Required: When billing_choice is false

Billing bank name. Up to 80 characters.

billing_routing

string · Required: When billing_choice is false

Billing 9-digit ABA routing number.

billing_account

string · Required: When billing_choice is false

Billing account number, 4 to 20 digits.

Consent

consent

boolean · Required: Yes

Must be true. Send it only after the merchant has agreed to the ACHQ Terms of Service and Privacy Policy at achq.com/legal.

Other

source

string · Required: No

Optional free text that shows up for the ACHQ team, for example your own reference for the merchant. Up to 120 characters.

Example

Every value below is a placeholder. Use real merchant details with a live key, or any values that pass the field rules with a test key.

Request
curl -X POST https://www.achq.com/api/v1/applications \
  -H "Authorization: Bearer $ACHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1d2e-8b7a-4c5d-9e0f-1a2b3c4d5e6f" \
  -d @application.json
application.json
{
  "legalbusinessname": "Example Plumbing LLC",
  "dba": "Example Plumbing",
  "tax_id": "00-0000001",
  "business_type": "LLC",
  "sector": "General Building Services",
  "specific_industry": "Plumbing",
  "business_description": "Residential plumbing repair. Customers pay invoices by bank transfer.",
  "website": "https://example.com",
  "primary_phone": "(555) 555-0100",
  "year_started": 2015,
  "business_street": "100 Example St",
  "business_city": "Denver",
  "business_state": "CO",
  "business_zip": "80202",
  "state_of_registration": "CO",
  "ownerFirstName": "Jane",
  "ownerLastName": "Example",
  "owner_title": "Owner",
  "owner_email": "jane@example.com",
  "owner_cell": "(555) 555-0101",
  "owner_dob": "1980-01-01",
  "owner_street": "200 Example Ave",
  "owner_city": "Denver",
  "owner_state": "CO",
  "owner_zip": "80202",
  "owner_ssn_last4": "0000",
  "add_charges": true,
  "add_payouts": false,
  "charge_dollars": 25000,
  "charge_count": 100,
  "charge_max": 1500,
  "person_customer": true,
  "business_customer": false,
  "web_auth": true,
  "signed_auth": false,
  "phone_auth": false,
  "statement_descriptor": "EXAMPLE",
  "service_phone": "(555) 555-0102",
  "service_email": "support@example.com",
  "refund_policy": "Refunds within 30 days on request.",
  "transfer_name": "Example Bank",
  "transfer_routing": "000000000",
  "transfer_account": "0000000000",
  "billing_choice": true,
  "consent": true
}
Response 201
{
  "id": "a0UPj00000EXAMPLE",
  "status": "received",
  "test": false
}

Responses and error codes

Every response is JSON. Error bodies never include merchant data.

StatusWhat it meansBody
201Application received. Keep the id for your records.{ "id": "a0UPj00000EXAMPLE", "status": "received", "test": false }
400A field is missing or invalid. fields lists every problem by field name. Fix them and send again.{ "error": "validation_error", "fields": { "tax_id": ["Tax ID (EIN) must be 9 digits"] } }
400The body is not valid JSON.{ "error": "invalid_json" }
401The API key is missing, mistyped or turned off.{ "error": "unauthorized" }
409The same application was already submitted in the last two minutes. id is the existing application. Nothing new was created.{ "error": "duplicate", "id": "a0UPj00000EXAMPLE", "status": "received", "test": false }
409A request with the same Idempotency-Key is still running. Wait a few seconds and retry.{ "error": "request_in_progress" }
429More than 30 requests in a minute from one key. Wait the number of seconds in the Retry-After header.{ "error": "rate_limited" }
500Something went wrong on our side. Retry with the same Idempotency-Key, or email sales@achq.com if it keeps happening.{ "error": "server_error" }

Test keys

Every partner gets a test key along with a live key. A test key runs the full request, including every field check, but the result is a practice record that is clearly marked as a test. No real merchant is created, no emails go out, and the response has "test": true.

Build and test with the test key, then switch to the live key when you are ready. Nothing else changes.

Idempotency

Send an Idempotency-Key header with a unique value for each application, such as a UUID. If a request times out or you are not sure it went through, send it again with the same key. For 10 minutes we return the first response instead of creating a second application, and the replay carries an Idempotent-Replayed: true header.

Keys are 8 to 128 characters: letters, numbers, dashes and underscores. Use a new key for every new application.

Rate limits

Each API key can send up to 30 requests per minute. Over that, the API returns 429 with a Retry-After header in seconds. If you need more, email us and tell us your expected volume.

Get an API key

API keys are for approved ACHQ referral and ISO partners. Email sales@achq.com with your company name and we will send you a live key and a test key. Not a partner yet? Start with the partner program. Looking for the payments API instead? See the developers page.