ACH charge
Initiate an ACH bank transfer charge. A payment can be made using raw ACH account data or for an existing customer vault.
Customer vault (customerId): request addresses and achData are ignored — the vault billing address and default payment method are used. The default must be an ACH-type method, or pass overrideDefaultPaymentMethod with the ACH account customerVaultId.
Currency: currency is an uppercase ISO code (USD | CAD).
billingAddress.state must be the full state/province name (e.g. California, not CA) for the Paya gateway.
Guarantee merchants require achData.driverLicenseNumber and achData.phoneNumber.
Dual-pricing accounts: amount represents the cash price; a discount is applied based on the configured discount rate.
achData.accountType values: businessChecking, businessSavings, personalChecking, personalSavings.
achData.last4 must be the last 4 digits of the account number (regex: \d{4}).
order is metadata only (orderId, orderDescription, poNumber, customValues); order.amount/order.discount are recomputed server-side. taxes holds merchant tax ids (see GET /public/tax); each tax is computed on amount and added to the total. bypassSurcharge and discount have no effect on ACH charges.
Headers
key-hashSecurity key hash issued to your integration (merchant dashboard: Administration → Security Keys).
user-agentRecorded on the transaction for auditing; not validated.
ACH charge › Request Body
amountA positive integer representing how much to charge in the smallest currency unit
clientIdIgnored. Derived from your API key (key-hash).
overrideDefaultPaymentMethodThe id of the payment method to use in the charge
currencyThree-letter ISO currency code, uppercase. Must be a supported currency
captureWhether to immediately capture the charge
sendReceiptsend Receipt info
bypassSurchargeIgnored for ACH (ACH charges never carry a surcharge).
discountIgnored for ACH; the discount is computed server-side (dual pricing).
customerIdCustomer ID
taxesArray of merchant tax ids (from GET /public/tax). Each tax is computed on amount and added to the total; unknown ids are rejected (404).
ACH charge › Responses
ACH charge created.
ACH refund
Post a refund on a previously created ACH payment. Funds are returned to the original bank account.
Important: the payment must be settled before it can be refunded (ACH payments become refundable 6 minutes after the charge; to cancel an unsettled payment use POST /public/ach/void). Partial refunds are supported up to the remaining refundable balance (except for WEB SEC merchants, which must refund the exact original amount). A refund on a fully refunded payment will result in an error.
amount is an integer in cents (1000 = $10.00). reason is required free text. transactionComponent is optional (base | donation | tip, default base). receipt, email and phoneNumber are optional (receipt delivery).
Headers
key-hashSecurity key hash issued to your integration (merchant dashboard: Administration → Security Keys).
user-agentRecorded on the transaction for auditing; not validated.
ACH refund › Request Body
amountInteger amount in cents (1000 = $10.00). Must not exceed the remaining refundable balance; when transactionComponent is base it is the pre-tax base amount.
paymentIdID of the payment to be refunded.
reasonRequired. Free-text reason; recommended values: duplicate, fraudulent, requested_by_customer.
transactionComponentTransaction component to refund. Possible values are base, donation, tip. Defaults to base when not sent.
receiptSend a refund receipt (email/SMS). Default false.
emailEmail for the refund receipt. Defaults to the payment contact email.
phoneNumber^[+]?[(]?[0-9]{3}[)]…Phone number for the refund receipt (SMS). Defaults to the payment contact phone.
ACH refund › Responses
Refund processed. Returns { data: <refund transaction> }.
ACH void
Void an existing ACH payment that has not yet been settled. Once voided, no additional charges can be made.
reason values: fraud, user_cancel, icc_rejected, icc_card_removed, icc_no_confirmation, pos_timeout, rejected, insufficient_funds, incorrect_information, pop_timeout.
Set receipt=true to send a receipt notification to the customer via email or SMS; email/phoneNumber override the payment contact.
The user-agent header is recorded on the void transaction but not validated.
Headers
key-hashSecurity key hash issued to your integration (merchant dashboard: Administration → Security Keys).
user-agentRecorded on the transaction for auditing; not validated.
ACH void › Request Body
paymentIdID of the payment to void
reasonVoid reason
paymentPayment type hint (creditcard | electronicCheck). Currently not used by the void flow.
receiptSend a void receipt (email/SMS). Default false.
emailEmail for the void receipt. Defaults to the payment contact email.
phoneNumber^[+]?[(]?[0-9]{3}[)]…Phone number for the void receipt (SMS). Defaults to the payment contact phone.
ACH void › Responses
Payment voided. Returns { data: <void transaction> }.
List ACH payments
Returns a paginated list of ACH payments. Filter by date range, last 4 digits of the account number, or authorization number.
query Parameters
authorizationNumberAuthorization/reference number from the ACH processor
achLast4Last 4 digits of the bank account number
endDayFilter end date (YYYY-MM-DD)
startDayFilter start date (YYYY-MM-DD)
limitItems per page (default: 10)
pagePage number (default: 1)
Headers
key-hashSecurity key hash issued to your integration (merchant dashboard: Administration → Security Keys).
List ACH payments › Responses
Paginated ACH payments list, wrapped in data.