BAMS Payment Gateway API Documentation

Introduction

The BAMS Payment Gateway API gives you full programmatic control over payment processing, merchant onboarding, customer management, and reporting. Two API generations are available:

API Version	Base URL	Auth Method	Format
Classic API (transact.php)	`https://www.bamsgateway.com/api/transact.php`	`security_key` in POST body	Form-encoded POST / query-string response
Query API (query.php)	`https://www.bamsgateway.com/api/query.php`	`security_key` in POST body	Form-encoded POST / XML response
v3 / v5 REST API	`https://www.bamsgateway.com/v3`	`security-key` header	JSON

Most payment processing (sales, refunds, subscriptions, customer vault) uses the Classic API. The REST API is used for merchant management, applications, invoicing, and administration.

New to BAMS Payment Gateway? Start by creating a free sandbox account — you'll have full API access within seconds, no credit card required.

Authentication

All API requests require a Security Key (API key) associated with your merchant account. There are two key types:

Key Type	Use Case	Exposure
Public Key	Client-side tokenization (Collect.js, hosted fields)	Safe to embed in browser/mobile code
Private Key	All server-side API calls	Must never be exposed client-side

Getting Your API Key

Log into the BAMS Gateway Merchant Portal
Navigate to Settings → Security Keys
Click Add a New Key
Enter a descriptive name, select the associated user, and choose the permission scope
Copy the generated key — it will only be shown once

Classic API — Key in Request Body

For transact.php and query.php, include your key as the security_key field in the POST body:

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE&type=sale&amount=10.00&ccnumber=4111111111111111&ccexp=1026&cvv=999"

REST API — Key in Header

For v3/v5 REST endpoints, pass your key in the security-key request header:

bash

curl https://www.bamsgateway.com/v3/transactions \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{"type":"sale","amount":"10.00","ccnumber":"4111111111111111","ccexp":"1026","cvv":"999"}'

JavaScript / Node.js Example

javascript

const axios = require('axios');

const response = await axios.post(
  'https://www.bamsgateway.com/v3/transactions',
  { type: 'sale', amount: '10.00', ccnumber: '4111111111111111', ccexp: '1026', cvv: '999' },
  { headers: { 'security-key': process.env.BAMS_API_KEY, 'Content-Type': 'application/json' } }
);

Keep your private key secret. Never expose it in client-side JavaScript, public repositories, or log files. Rotate keys immediately if they are compromised. Generate separate keys for development, staging, and production.

Sends a lightweight query request to confirm your API key is valid. A 200 response with response=1 means you are authenticated.

Response

Testing Methods

The sandbox environment is identical to production — it just never moves real funds. Use your sandbox API key (obtained from the sandbox sign-up page) for all test requests. The sandbox endpoint is the same URL as production; the key determines the environment.

Never use real API keys when testing. Always use a dedicated sandbox/test merchant key. BAMS allows partners to create unlimited Test Merchant Accounts.

Test Credit Card Numbers

Card Number	Network	Result
`4111111111111111`	Visa	Approved
`4111111111111129`	Visa	Declined
`5431111111111111`	Mastercard	Approved
`6011000991300009`	Discover	Approved
`341111111111111`	American Express	Approved
`30205252489926`	Diner's Club	Approved
`3541963594572595`	JCB	Approved
`6799990100000000019`	Maestro	Approved

Use any future expiration date in MMYY format (e.g. 1226) and CVV 999 for all test cards.

Test ACH / eCheck Accounts

Account Number	Routing Number	Result
`123456789`	`021000021`	Approved
`123456789`	`011000015`	Declined

For ACH transactions set payment=check, account_type=checking, account_holder_type=personal, and sec_code=WEB.

AVS & CVV Test Values

Scenario	ZIP	Address	CVV
Full AVS match + CVV match	`10101`	`101 Main St`	`999`
ZIP match only	`10101`	(any other)	`999`
CVV mismatch	(any)	(any)	`901`

Rate Limiting

Rate limits are enforced per API key to ensure platform stability. Exceeding a limit returns HTTP 429 Too Many Requests.

Limit Type	Value
Requests per second	50
Requests per minute	1,000
Requests per hour	30,000

Every response includes these rate-limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Pagination

List endpoints return paginated results. Use offset and limit to navigate pages.

bash

curl "https://www.bamsgateway.com/v3/transactions?limit=25&offset=50" \
  -H "security-key: YOUR_API_KEY_HERE"

Parameter	Default	Max	Description
`limit`	25	200	Number of records to return
`offset`	0	—	Number of records to skip

All paginated responses include a meta object:

json

{
  "data": [ ... ],
  "meta": {
    "total": 1420,
    "limit": 25,
    "offset": 50,
    "has_more": true
  }
}

Response Codes

The Classic API returns a response field and a numeric response_code. The response value is:

response	Meaning
`1`	Approved / Success
`2`	Declined
`3`	Error

Numeric Response Codes

Code	Meaning
`100`	Transaction approved
DECLINED BY PROCESSOR (200–264)
`200`	Declined by processor
`201`	Do not honor
`202`	Insufficient funds
`203`	Over limit
`204`	Transaction not allowed
`220`	Incorrect payment information
`221`	No such card issuer
`222`	No card number on file with issuer
`223`	Expired card
`224`	Invalid expiration date
`225`	Invalid security code (CVV)
`226`	Invalid PIN
`240`	Call issuer for further information
`250`	Pick up card
`251`	Lost card
`252`	Stolen card
`253`	Fraudulent card
`260`	Declined with further instructions available — see responsetext
`261`	Declined — stop all recurring billing
`262`	Declined — stop this recurring program
`263`	Declined — update cardholder data available
`264`	Declined — retry in a few days
GATEWAY / PROCESSOR ERRORS (300–461)
`300`	Rejected by gateway
`400`	Processor error
`410`	Invalid merchant configuration
`411`	Merchant account inactive
`420`	Communication error — unable to reach processor
`421`	Communication error — invalid response from processor
`430`	Duplicate transaction
`440`	Processor format error
`441`	Invalid transaction information
`460`	Processor feature not available
`461`	Unsupported card type
REST API HTTP CODES
`200`	OK — request succeeded
`201`	Created — resource successfully created
`400`	Bad Request — missing or invalid parameters
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource does not exist
`409`	Conflict — duplicate request or state conflict
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — contact support

Classic API error responses also include a responsetext field with a human-readable description of the decline reason.

Applications

The Applications API lets partners submit merchant account applications for automated risk review and underwriting. Applications move through a defined status lifecycle:

Submitted→ Under Review→ Approved→ Active

Upon approval, BAMS provisions a Gateway ID and Merchant ID automatically. You can monitor progress by polling the application status endpoint or subscribing to application webhooks.

bash

# Submit a new merchant application
curl -X POST https://www.bamsgateway.com/v3/applications \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "business_name": "Acme Retail LLC",
    "business_type": "retail",
    "email": "owner@acmecorp.com",
    "phone": "5551234567",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "country": "US"
    },
    "owner": {
      "first_name": "Jane",
      "last_name": "Smith",
      "ssn_last4": "1234",
      "dob": "1980-06-15"
    }
  }'

bash

# Get application status
curl https://www.bamsgateway.com/v3/applications/{application_id} \
  -H "security-key: YOUR_API_KEY_HERE"

Packages

Packages define the pricing tier and feature set for a merchant account — including interchange rates, monthly fees, enabled payment methods, and processing limits. Assign a package when submitting an application.

bash

# List available packages
curl https://www.bamsgateway.com/v3/packages \
  -H "security-key: YOUR_API_KEY_HERE"

json

{
  "data": [
    {
      "id": "pkg_retail_standard",
      "name": "Retail Standard",
      "monthly_fee": "25.00",
      "per_transaction_fee": "0.10",
      "enabled_payment_methods": ["card", "ach"]
    }
  ]
}

Webhook Subscriptions

Subscribe to application lifecycle events so your platform receives real-time notifications as merchant applications move through the review workflow.

bash

curl -X POST https://www.bamsgateway.com/v3/webhook-subscriptions \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "url": "https://yoursite.com/webhooks/bams",
    "events": [
      "application.approved",
      "application.declined",
      "application.pending_review",
      "merchant.activated"
    ]
  }'

Legal Consent

Before an application can be activated, the merchant must provide explicit consent to BAMS Payment Gateway Terms of Service and Card Brand Rules. Record consent through the API — the IP address, user-agent, and timestamp are stored for compliance purposes.

bash

curl -X POST https://www.bamsgateway.com/v3/applications/{application_id}/consent \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)…",
    "consented_at": "2026-01-15T14:32:00Z",
    "terms_version": "2026-01"
  }'

Transactions

The Transaction API is a POST endpoint that processes payments in real time. Transaction details are sent form-encoded; the gateway responds immediately with a query-string result.

Transaction Types

type	Description
`sale`	Authorize and capture a payment in a single step
`auth`	Authorize only — places a hold; capture separately
`capture`	Settle a prior `auth`; requires `transactionid`
`void`	Cancel an unsettled transaction; requires `transactionid`
`refund`	Return funds on a settled transaction; requires `transactionid`
`credit`	Push funds to a card without a prior charge
`validate`	Verify a card number is valid without charging (`$0 auth`)

Sale — Charge a Card

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "type=sale" \
  -d "amount=49.99" \
  -d "ccnumber=4111111111111111" \
  -d "ccexp=1226" \
  -d "cvv=999" \
  -d "firstname=Jane" \
  -d "lastname=Smith" \
  -d "email=jane@example.com" \
  -d "address1=123 Main St" \
  -d "city=New York" \
  -d "state=NY" \
  -d "zip=10001" \
  -d "country=US" \
  -d "ipaddress=203.0.113.42" \
  -d "orderid=ORD-20260115-0042"

Authorize Only

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "type=auth" \
  -d "amount=49.99" \
  -d "ccnumber=4111111111111111" \
  -d "ccexp=1226" \
  -d "cvv=999"

Capture / Void / Refund

bash

# Capture an auth
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE&type=capture&transactionid=BAMS-TXN-001&amount=49.99"

# Void an unsettled transaction
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE&type=void&transactionid=BAMS-TXN-001"

# Refund a settled transaction (full or partial)
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE&type=refund&transactionid=BAMS-TXN-001&amount=25.00"

ACH / eCheck Transaction

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "type=sale" \
  -d "payment=check" \
  -d "amount=49.99" \
  -d "checkname=Jane Smith" \
  -d "checkaba=021000021" \
  -d "checkaccount=123456789" \
  -d "account_type=checking" \
  -d "account_holder_type=personal" \
  -d "sec_code=WEB" \
  -d "email=jane@example.com"

Core Request Parameters

Parameter	Required	Description
`security_key`	Required	Your API Security Key
`type`	Required	Transaction type: `sale`, `auth`, `capture`, `void`, `refund`, `credit`, `validate`
`amount`	Required	Charge amount in `x.xx` format (e.g. `49.99`)
`ccnumber`	Required*	Credit card number (*not required when using `customer_vault_id`)
`ccexp`	Required*	Expiration date in `MMYY` format
`cvv`	Recommended	Card security code (strongly recommended for e-commerce)
`transactionid`	Conditional	Original transaction ID — required for `capture`, `void`, `refund`
`currency`	Optional	ISO 4217 currency code (default: `USD`)
`orderid`	Optional	Your order reference number
`order_description`	Optional	Description of the order
`ipaddress`	Optional	Cardholder IP address (recommended for fraud scoring)
`industry`	Optional	`ecommerce`, `moto`, `retail`, `restaurant`, or `lodging`
`customer_receipt`	Optional	`true` to send email receipt to cardholder
`dup_seconds`	Optional	Duplicate detection window in seconds (0 disables; max 7862400)
`processor_id`	Optional	Route to a specific processor (Multiple MID setups)
`partial_payments`	Optional	`settle_partial` or `payment_in_full`

Billing & Shipping Parameters

Parameter	Description
`firstname`	Cardholder first name
`lastname`	Cardholder last name
`company`	Company name
`address1`	Billing address line 1
`address2`	Billing address line 2
`city`	Billing city
`state`	Billing state (2-letter code)
`zip`	Billing ZIP / postal code
`country`	Billing country (ISO 3166-1 alpha-2)
`phone`	Customer phone number
`fax`	Customer fax number
`email`	Customer email (required for `customer_receipt=true`)
`shipping_firstname`	Shipping recipient first name
`shipping_lastname`	Shipping recipient last name
`shipping_address1`	Shipping address line 1
`shipping_city`	Shipping city
`shipping_state`	Shipping state
`shipping_zip`	Shipping ZIP
`shipping_country`	Shipping country (ISO 3166-1 alpha-2)
`shipping_email`	Shipping contact email

Fees & Order Detail Parameters

Parameter	Description
`shipping`	Freight / shipping amount (`x.xx`)
`tax`	Sales tax amount (`x.xx`); use `-1` for tax-exempt
`surcharge`	Surcharge amount (`x.xx`)
`convenience_fee`	Convenience fee amount (`x.xx`)
`tip`	Tip amount (`x.xx`)
`ponumber`	Purchase order number

Stored Credentials (CIT / MIT)

Use stored credential indicators to distinguish between customer-initiated transactions (CIT) and merchant-initiated transactions (MIT) for compliance with card brand requirements.

Parameter	Values	Description
`initiated_by`	`customer` \| `merchant`	Who initiated the transaction
`stored_credential_indicator`	`stored` \| `used`	`stored` = first use, `used` = subsequent
`initial_transaction_id`	Transaction ID	The original CIT transaction ID for MIT references

bash

# Initial customer-initiated transaction (stores credential)
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE&type=sale&amount=29.99&ccnumber=4111111111111111&ccexp=1226" \
  -d "initiated_by=customer&stored_credential_indicator=stored"

# Subsequent merchant-initiated transaction (e.g. subscription renewal)
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE&type=sale&amount=29.99&ccnumber=4111111111111111&ccexp=1226" \
  -d "initiated_by=merchant&stored_credential_indicator=used&initial_transaction_id=BAMS-TXN-001"

3D Secure Parameters

Parameter	Description
`cardholder_auth`	3DS result: `verified` or `attempted`
`cavv`	Cardholder Authentication Verification Value
`xid`	Cardholder authentication transaction ID
`three_ds_version`	3DS version: `2.0.0` or `2.2.0`
`transaction_session_id`	32-character Kount DDC session ID

Merchant Defined Fields

Attach up to 20 custom key-value pairs to any transaction. These are stored and returned in reporting.

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE&type=sale&amount=10.00&ccnumber=4111111111111111&ccexp=1226" \
  -d "merchant_defined_field_1=store_42" \
  -d "merchant_defined_field_2=promo_SUMMER2026"

Response Fields

Field	Description
`response`	`1`=approved, `2`=declined, `3`=error
`responsetext`	Human-readable result (e.g. `SUCCESS`, `DECLINE`)
`authcode`	Authorization code from the issuing bank
`transactionid`	Unique BAMS transaction identifier
`avsresponse`	Address Verification result code
`cvvresponse`	CVV verification result code (`M`=match, `N`=no match, `P`=not processed)
`orderid`	Your order ID echoed back
`type`	Transaction type echoed back
`response_code`	Numeric response code (see Response Codes section)
`customer_vault_id`	Vault ID created (if `customer_vault=add_customer` was sent)

text

# Example response (query string format)
response=1&responsetext=SUCCESS&authcode=123456&transactionid=BAMS-20260115-00001234&avsresponse=Y&cvvresponse=M&orderid=ORD-0042&type=sale&response_code=100

Runs a live call against the sandbox. Use the test card numbers from the Testing section — no real funds are charged.

Type

Amount

Card Number

Expiry (MMYY)

CVV

First Name

Last Name

Response

Customer Vault

The Customer Vault securely stores payment information (card numbers, ACH account details, and billing data) in a Level 1 PCI-certified facility. Once stored, you reference customers by a customer_vault_id instead of raw card data — eliminating the need to handle or store sensitive payment information on your own servers.

PCI Scope Reduction. When you use the Customer Vault exclusively, sensitive payment data never touches your server. This significantly reduces your PCI DSS compliance scope and breach liability.

How Tokenization Works

Customer's card or ACH details are sent to the gateway over SSL
Gateway stores the data in a PCI-compliant vault and returns a customer_vault_id
You store only the customer_vault_id — no card data on your server
Future charges reference the vault ID; the gateway decrypts and processes the data automatically

Add a Customer to the Vault

Pass customer_vault=add_customer alongside a sale or validate transaction. The vault record is created and the ID returned in the response:

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "type=sale" \
  -d "amount=49.99" \
  -d "ccnumber=4111111111111111" \
  -d "ccexp=1226" \
  -d "cvv=999" \
  -d "firstname=Jane" \
  -d "lastname=Smith" \
  -d "email=jane@example.com" \
  -d "customer_vault=add_customer"

Response includes: customer_vault_id=cv_abc123def456

Charge a Vaulted Customer

Use the customer_vault_id in place of ccnumber / ccexp for subsequent transactions:

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "type=sale" \
  -d "amount=29.99" \
  -d "customer_vault_id=cv_abc123def456"

Update a Vault Record

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "customer_vault=update_customer" \
  -d "customer_vault_id=cv_abc123def456" \
  -d "ccnumber=5431111111111111" \
  -d "ccexp=0128"

Delete a Vault Record

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "customer_vault=delete_customer" \
  -d "customer_vault_id=cv_abc123def456"

Customer Vault Parameters

Parameter	Values	Description
`customer_vault`	`add_customer` \| `update_customer` \| `delete_customer`	Vault operation to perform
`customer_vault_id`	String	Vault record ID (auto-generated on `add_customer` if omitted)

Invoicing

Create and send payment invoices directly to customers via email. Customers pay via a hosted BAMS-branded payment page — no additional integration required on the payment side.

Create an Invoice

bash

curl -X POST https://www.bamsgateway.com/v3/invoices \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "customer_id": "cust_abc123",
    "amount": "250.00",
    "due_date": "2026-04-15",
    "memo": "Project retainer — March 2026",
    "line_items": [
      { "description": "Consulting Services", "quantity": 5, "unit_price": "50.00" }
    ]
  }'

Invoice Endpoints

Method	Endpoint	Description
POST	`/v3/invoices`	Create a new invoice and email it to the customer
GET	`/v3/invoices`	List invoices (supports filters: status, date range, customer)
GET	`/v3/invoices/{id}`	Retrieve a specific invoice
PUT	`/v3/invoices/{id}`	Update an open invoice
POST	`/v3/invoices/{id}/send`	Re-send invoice email to the customer
DELETE	`/v3/invoices/{id}`	Close/cancel an invoice

Subscriptions

Create recurring billing schedules that automatically charge customers on a defined interval. The gateway handles retry logic, failed payment notifications, and Automatic Card Updater (ACU) for expiring cards.

Add a Subscription

bash

# Subscribe using an existing plan
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "recurring=add_subscription" \
  -d "plan_id=plan_monthly_pro" \
  -d "ccnumber=4111111111111111" \
  -d "ccexp=1226" \
  -d "firstname=Jane" \
  -d "lastname=Smith" \
  -d "email=jane@example.com"

bash

# Create a custom monthly subscription (no plan required)
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "recurring=add_subscription" \
  -d "plan_amount=29.99" \
  -d "plan_payments=12" \
  -d "month_frequency=1" \
  -d "day_of_month=15" \
  -d "start_date=20260401" \
  -d "ccnumber=4111111111111111" \
  -d "ccexp=1226" \
  -d "firstname=Jane" \
  -d "lastname=Smith"

bash

# Custom daily billing (every 7 days)
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "recurring=add_subscription" \
  -d "plan_amount=9.99" \
  -d "plan_payments=0" \
  -d "day_frequency=7" \
  -d "start_date=20260401" \
  -d "ccnumber=4111111111111111" \
  -d "ccexp=1226" \
  -d "firstname=Jane" \
  -d "lastname=Smith"

ACH Subscription

bash

curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "recurring=add_subscription" \
  -d "payment=check" \
  -d "plan_id=plan_monthly_ach" \
  -d "checkname=Jane Smith" \
  -d "checkaba=021000021" \
  -d "checkaccount=123456789" \
  -d "account_type=checking" \
  -d "account_holder_type=personal" \
  -d "sec_code=PPD"

Update / Delete a Subscription

bash

# Update subscription (change amount or payment method)
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "recurring=update_subscription" \
  -d "subscription_id=sub_xyz789" \
  -d "plan_amount=39.99" \
  -d "ccnumber=5431111111111111" \
  -d "ccexp=0228"

# Cancel / delete a subscription
curl -X POST https://www.bamsgateway.com/api/transact.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "recurring=delete_subscription" \
  -d "subscription_id=sub_xyz789"

Subscription Parameters

Parameter	Required	Description
`recurring`	Required	`add_subscription`, `update_subscription`, or `delete_subscription`
`plan_id`	Conditional	Existing plan ID (required if not specifying custom billing fields)
`plan_amount`	Conditional	Charge per cycle in `x.xx` format (required for custom plans)
`plan_payments`	Optional	Number of charges (0 = bill indefinitely until canceled)
`month_frequency`	Conditional	Months between charges (1–24). Use either this or `day_frequency`, not both.
`day_of_month`	Conditional	Day of month to charge (1–31; if month lacks that date, last day is used)
`day_frequency`	Conditional	Days between charges. Use either this or `month_frequency`, not both.
`start_date`	Optional	Date of first charge in `YYYYMMDD` format
`subscription_id`	Conditional	Required for `update_subscription` and `delete_subscription`
`acu_enabled`	Optional	`true` (default) to enable Automatic Card Updater for expiring cards
`paused_subscription`	Optional	`true` to pause billing without canceling

Subscription Response Fields

Field	Description
`response`	`1`=success, `2`=failed, `3`=error
`subscription_id`	Created or modified subscription identifier
`responsetext`	Human-readable result
`customer_vault_id`	Vault ID if a vault record was created or used

Customers

The REST Customers API provides CRUD operations over Customer Vault records. Use it to manage customer profiles and payment methods from your admin or CRM, separate from the transaction flow.

bash

# Create a customer vault record (no charge)
curl -X POST https://www.bamsgateway.com/v3/customers \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "firstname": "Jane",
    "lastname": "Smith",
    "email": "jane@example.com",
    "ccnumber": "4111111111111111",
    "ccexp": "1226"
  }'

Method	Endpoint	Description
POST	`/v3/customers`	Create a new customer vault record
GET	`/v3/customers`	List customer vault records
GET	`/v3/customers/{id}`	Retrieve a specific customer
PUT	`/v3/customers/{id}`	Update customer billing information or card
DELETE	`/v3/customers/{id}`	Delete a customer vault record

Devices

Manage card-present terminals through the Devices API. BAMS Payment Gateway supports a wide range of certified EMV/NFC terminals. Each device is registered to a merchant account and can be targeted for Cloud API transactions.

bash

# List registered terminals for your account
curl https://www.bamsgateway.com/v3/devices \
  -H "security-key: YOUR_API_KEY_HERE"

bash

# Get a specific device
curl https://www.bamsgateway.com/v3/devices/{device_id} \
  -H "security-key: YOUR_API_KEY_HERE"

Cloud API

The Cloud API lets you initiate card-present transactions remotely from your server. Send a payment request to a specific terminal — the customer taps or dips their card on the device and the result is delivered via webhook or polling.

bash

# Initiate a sale on a specific terminal
curl -X POST https://www.bamsgateway.com/v3/devices/{device_id}/transactions \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "type": "sale",
    "amount": "24.99",
    "tip_mode": "on_device",
    "orderid": "ORD-20260115-0043"
  }'

bash

# Poll for transaction result
curl https://www.bamsgateway.com/v3/devices/{device_id}/transactions/{transaction_id} \
  -H "security-key: YOUR_API_KEY_HERE"

Merchants

Retrieve and update merchant account details including business information, processing limits, enabled payment methods, and processor configuration. Partners can use this API to manage all merchants under their umbrella.

bash

# Get merchant details
curl https://www.bamsgateway.com/v3/merchants/{merchant_id} \
  -H "security-key: YOUR_API_KEY_HERE"

bash

# Update merchant settings
curl -X PUT https://www.bamsgateway.com/v3/merchants/{merchant_id} \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{"business_name": "Acme Retail LLC (Updated)", "email": "newcontact@acme.com"}'

Settlement

Query settlement batches and funding status. BAMS Payment Gateway offers next-business-day funding for qualifying merchants. Batch summaries include gross sales, refunds, chargebacks, fees, and net deposit amounts.

bash

# List settlement batches for a date range
curl "https://www.bamsgateway.com/v3/settlements?start_date=2026-01-01&end_date=2026-01-31" \
  -H "security-key: YOUR_API_KEY_HERE"

bash

# Get a specific batch
curl https://www.bamsgateway.com/v3/settlements/{batch_id} \
  -H "security-key: YOUR_API_KEY_HERE"

Fee Schedules

Retrieve the fee schedule applied to a merchant account, including interchange-plus margins, monthly statement fees, chargeback fees, and per-transaction rates by card type.

bash

curl https://www.bamsgateway.com/v3/merchants/{merchant_id}/fee-schedule \
  -H "security-key: YOUR_API_KEY_HERE"

Transaction Data (Query API)

The Query API (query.php) retrieves transaction history, customer vault records, recurring subscriptions, and account data. Post your query parameters form-encoded; the response is XML.

bash

# Query recent transactions
curl -X POST https://www.bamsgateway.com/api/query.php \
  -d "security_key=YOUR_API_KEY_HERE" \
  -d "report_type=transaction" \
  -d "start_date=20260101" \
  -d "end_date=20260131" \
  -d "result_limit=50"

Report Types

report_type	Description
`transaction`	Transaction history — sales, auths, voids, refunds
`recurring`	Subscription / recurring billing records
`customer_vault`	Customer vault records
`invoices`	Invoice history and status

Query Parameters

Parameter	Description
`report_type`	Type of report (see above)
`start_date`	Start date in `YYYYMMDD` format (or `YYYYMMDDHHMMSS`)
`end_date`	End date in `YYYYMMDD` format
`result_limit`	Maximum records to return (default 1000)
`transaction_id`	Look up a specific transaction by ID
`order_id`	Filter by your order ID
`condition`	Filter by status: `complete`, `pending`, `failed`
`action_type`	Filter by type: `sale`, `refund`, `void`, etc.
`first_name` / `last_name`	Filter by customer name
`email`	Filter by customer email
`cc_number`	Filter by last 4 digits of card number
`amount`	Filter by exact amount

The REST endpoint also supports flexible querying:

bash

curl "https://www.bamsgateway.com/v3/transactions?start_date=2026-01-01&status=approved&limit=50" \
  -H "security-key: YOUR_API_KEY_HERE"

Billing

Access itemized billing statements for your merchant account, including processing fees, monthly charges, chargeback costs, and any adjustments. Statements are generated monthly.

bash

# List billing statements
curl https://www.bamsgateway.com/v3/billing/statements \
  -H "security-key: YOUR_API_KEY_HERE"

bash

# Get a specific statement
curl https://www.bamsgateway.com/v3/billing/statements/{statement_id} \
  -H "security-key: YOUR_API_KEY_HERE"

API Keys

Create, rotate, and revoke API keys programmatically. Keys inherit the permission scope of the user account they are associated with. Follow the principle of least privilege — scope each key to only the permissions it needs.

Key Permission Scopes

Scope	Access
`transactions:write`	Create and modify transactions
`transactions:read`	Query transaction history
`customers:write`	Create and modify vault records
`customers:read`	Read customer vault data
`reporting:read`	Access billing and settlement reports
`admin`	Full access including key management and user management

bash

# Create a scoped API key
curl -X POST https://www.bamsgateway.com/v3/api-keys \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_ADMIN_KEY_HERE" \
  -d '{
    "name": "Production Integration — transactions only",
    "scopes": ["transactions:write", "customers:read"]
  }'

bash

# Revoke a key
curl -X DELETE https://www.bamsgateway.com/v3/api-keys/{key_id} \
  -H "security-key: YOUR_ADMIN_KEY_HERE"

Users

Manage user accounts and role-based access control within your merchant organization. BAMS Payment Gateway supports granular permission scopes — invite team members with only the access they need.

bash

# Invite a team member
curl -X POST https://www.bamsgateway.com/v3/users \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "email": "finance@yourcompany.com",
    "role": "reporting_only",
    "first_name": "Alex",
    "last_name": "Johnson"
  }'

Role	Description
`admin`	Full access including user and key management
`developer`	API and integration access; cannot manage users
`reporting_only`	Read-only access to transactions and reports
`support`	Can view transactions and issue refunds; no admin access

Webhooks

Webhooks deliver real-time event notifications to your server via HTTPS POST. BAMS Payment Gateway signs all payloads with HMAC-SHA256 so you can verify their authenticity before processing.

Event Types

Category	Events
Transactions	Sales, auths, captures, voids, refunds, and credits — filterable by successful, failed, or unknown
Check Status	ACH/eCheck settled, returned, or late return
Recurring	New subscription created, subscription updated, subscription canceled, plan created/updated
Settlement	Batch closed and funded — filterable by successful or failed
Chargebacks	Chargeback received, chargeback won, chargeback lost (requires processor support)
Automatic Card Updater	Card updated, card closed, customer contact info updated

Register a Webhook Endpoint

All webhook URLs must start with https:// and have valid TLS encryption.

bash

curl -X POST https://www.bamsgateway.com/v3/webhooks \
  -H "Content-Type: application/json" \
  -H "security-key: YOUR_API_KEY_HERE" \
  -d '{
    "url": "https://yoursite.com/webhooks/bams",
    "events": [
      "transaction.approved",
      "transaction.declined",
      "chargeback.created",
      "recurring.subscription_canceled"
    ]
  }'

Webhook Payload Structure

Every webhook POST contains three top-level fields:

json

{
  "event_id":   "evt_a1b2c3d4e5f6",
  "event_type": "transaction.approved",
  "event_body": {
    "transactionid": "BAMS-20260115-00001234",
    "type": "sale",
    "amount": "49.99",
    "response": "1",
    "authcode": "123456",
    ...
  }
}

Verifying Webhook Signatures

Each webhook request includes a X-BAMS-Signature header in the format t={nonce},s={signature}. Verify the signature before processing the event:

php

function webhookIsVerified(string $webhookBody, string $signingKey, string $header): bool {
    // Header format: t={nonce},s={signature}
    if ( ! preg_match( '/t=([^,]+),s=(.+)/', $header, $m ) ) return false;
    $nonce = $m[1];
    $sig   = $m[2];
    $expected = hash_hmac( 'sha256', $nonce . '.' . $webhookBody, $signingKey );
    return hash_equals( $expected, $sig );
}

// In your webhook handler:
$rawBody = file_get_contents( 'php://input' );
$header  = $_SERVER['HTTP_X_BAMS_SIGNATURE'] ?? '';
if ( ! webhookIsVerified( $rawBody, BAMS_WEBHOOK_SECRET, $header ) ) {
    http_response_code( 401 );
    exit( 'Invalid signature' );
}
$event = json_decode( $rawBody, true );

javascript

const crypto = require('crypto');

function verifyWebhook(rawBody, signingKey, header) {
  const match = header.match(/t=([^,]+),s=(.+)/);
  if (!match) return false;
  const [, nonce, sig] = match;
  const expected = crypto.createHmac('sha256', signingKey)
                         .update(`${nonce}.${rawBody}`)
                         .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

IP Allowlist

For additional security, restrict your webhook endpoint to only accept requests from BAMS Gateway IP ranges:

text

104.192.32.81  –  104.192.32.87
104.192.36.81  –  104.192.36.87

Retry Logic

If your endpoint does not return HTTP 200, BAMS will retry the webhook delivery with exponential back-off. Respond with 200 as quickly as possible — process the event asynchronously if needed.

Configure via Portal. Webhooks can also be configured in the BAMS Merchant Portal under Settings → Webhooks. Click Create, enter your HTTPS URL, and select the event types you want to receive.

BAMS Payment Gateway API Reference

Introduction

Authentication

Getting Your API Key

Classic API — Key in Request Body

REST API — Key in Header

JavaScript / Node.js Example

Testing Methods

Test Credit Card Numbers

Test ACH / eCheck Accounts

AVS & CVV Test Values

Rate Limiting

Pagination

Response Codes

Numeric Response Codes

Applications

Packages

Webhook Subscriptions

Legal Consent

Transactions

Transaction Types

Sale — Charge a Card

Authorize Only

Capture / Void / Refund

ACH / eCheck Transaction

Core Request Parameters

Billing & Shipping Parameters

Fees & Order Detail Parameters

Stored Credentials (CIT / MIT)

3D Secure Parameters

Merchant Defined Fields

Response Fields

Customer Vault

How Tokenization Works

Add a Customer to the Vault

Charge a Vaulted Customer

Update a Vault Record

Delete a Vault Record

Customer Vault Parameters

Invoicing

Create an Invoice

Invoice Endpoints

Subscriptions

Add a Subscription

ACH Subscription

Update / Delete a Subscription

Subscription Parameters

Subscription Response Fields

Customers

Devices

Cloud API

Merchants

Settlement

Fee Schedules

Transaction Data (Query API)

Report Types

Query Parameters

Billing

API Keys

Key Permission Scopes

Users

Webhooks

Event Types

Register a Webhook Endpoint

Webhook Payload Structure

Verifying Webhook Signatures

IP Allowlist

Retry Logic