Checking access…

Skip to main content
Version: v2

ACH Consent Integration

ACH (Automated Clearing House) consent is a legal authorization provided by a customer that permits electronic debits from their bank account. This consent is required by NACHA (National Automated Clearing House Association) regulations before initiating any ACH transaction β€” a consent object must be present on every ACH payment request, or the payment is rejected with a validation error.

Integration Details
  • Prerequisite: A BANK_ACCOUNT payment method on the customer's wallet or in the request.
  • Endpoint: POST /v2/payments (and POST /v2/token/payments for PCI-scope flows) β€” the consent object is part of the payment request body. For widget/session-flow payments, merchantConsentText is instead supplied in the consent object of the session request (POST /v2/sessions) β€” see Sessions.
  • Scope: merchant or merchant-pci
  • Use: Collecting and submitting NACHA-compliant consent for ACH payments

CCG supports three NACHA-defined collection types to accommodate different channels:

Consent TypeCollection MethodTypical Use Case
WEBOnline / digitalSelf-service web or mobile payment
TELVerbal / telephonicIVR or agent-assisted phone payment
PPDPhysical / paperSigned paper authorization form

Consent is required for all ACH (bank account) payments. Card payments do not require a consent object.

Payment MethodConsent Required
Bank Account (ACH)Yes β€” full consent object required
Credit / Debit CardNo
Saved Bank AccountYes β€” consent must accompany the payment request
IVR Bank AccountYes β€” TEL consent type required

API Request​

Field Requirements​

  • A consent object must be present on every ACH payment request.
  • collectionDetails.type must be one of WEB, TEL, or PPD.
  • A consent identifier is required and depends on who initiates the payment:
    • CCG Widget / checkout session flow: supply merchantConsentText β€” the full consent text displayed to the customer β€” in the consent object of the session request (POST /v2/sessions). The Widget carries it through when it submits the payment; you do not send it again on a separate payment request.
    • Merchant-initiated or guest flow (direct POST /v2/payments call): merchantConsentId is required instead β€” a reference to a consent record stored by the merchant.
FieldRule
collectionTimestampRequired when consent object is present. Must be ISO-8601 format (e.g., 2025-07-21T14:30:00Z).
WEB typecollectionDetails.web.ipAddress and collectionDetails.web.userAgent are required.
TEL typecollectionDetails.tel must be present (non-null). inboundPhoneNumber and its sub-fields are optional.
PPD typeagent at the payment request level must be present. No collectionDetails sub-object required beyond type.
Consent Object Schema
"consent": {
"merchantConsentId": "string",
"merchantConsentText": "string",
"collectionTimestamp": "string",
"collectionDetails": {
"type": "WEB",
"web": {
"ipAddress": "string",
"userAgent": "string"
},
"tel": {
"inboundPhoneNumber": {
"countryCode": "string",
"number": "string"
}
}
}
}

Examples by Collection Type​

WEB Consent β€” Online Payment

Customer agrees to ACH terms by checking a box on the payment page. The platform captures IP address and user agent as proof of digital consent.

{
"consent": {
"merchantConsentText": "I authorize ACME Healthcare to debit my account for the amount specified and understand this authorization will remain in effect until I cancel it in writing.",
"collectionTimestamp": "2025-07-21T10:15:30Z",
"collectionDetails": {
"type": "WEB",
"web": {
"ipAddress": "192.168.1.100",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}
}
}
}
TEL Consent β€” Phone / IVR Payment (minimal)

Customer provides verbal authorization over the phone. Only the tel object is required β€” inboundPhoneNumber is optional.

{
"consent": {
"merchantConsentId": "CONSENT-12345-ABCDE",
"collectionTimestamp": "2025-07-21T14:22:18Z",
"collectionDetails": {
"type": "TEL",
"tel": {}
}
}
}
TEL Consent β€” Phone / IVR Payment (with optional inboundPhoneNumber)
{
"consent": {
"merchantConsentId": "CONSENT-12345-ABCDE",
"collectionTimestamp": "2025-07-21T14:22:18Z",
"collectionDetails": {
"type": "TEL",
"tel": {
"inboundPhoneNumber": {
"countryCode": "1",
"number": "5551234567"
}
}
}
}
}
PPD Consent β€” Paper Authorization

Customer signs a physical authorization form. The agent field at the payment request level identifies who collected the consent.

{
"consent": {
"merchantConsentId": "CONSENT-67890-FGHIJ",
"collectionTimestamp": "2025-07-20T09:45:00Z",
"collectionDetails": {
"type": "PPD"
}
}
}

API Response​

  • Consent valid: The ACH payment proceeds to authorization and capture, following the standard Payments response flow.
  • Consent missing or invalid: The payment is rejected with a validation error. No debit is initiated.

Status Handling​

Consent validation happens synchronously at payment creation β€” there is no separate status to poll for consent itself. See Payments for the overall payment status lifecycle.

Error Handling​

Refer to the Payment Error Codes reference for the validation error shape returned when a consent object is missing or malformed.

FAQ​

No. When retrying a failed ACH payment, include a fresh consent object with the new request β€” reusing consent from a prior failed attempt may not satisfy NACHA authorization requirements.

How old can collectionTimestamp be?​

If collectionTimestamp is significantly older than the payment date, it may indicate stale consent. Collect consent at or immediately before the time of payment initiation to satisfy NACHA retention requirements.

Yes β€” consent must accompany every ACH payment request regardless of whether the bank account is newly entered or previously saved.

Integration Checklist​

  • Include a consent object on every ACH (BANK_ACCOUNT) payment request
  • Choose the correct collectionDetails.type (WEB, TEL, or PPD) for your channel
  • Supply merchantConsentId for your merchant-initiated or guest-flow payment requests, or merchantConsentText in the session request (POST /v2/sessions) for widget/session-flow payments
  • Always set collectionTimestamp in ISO-8601 format, captured at or near payment initiation
  • Generate a fresh consent object on every retry β€” do not reuse a prior attempt's consent
  • ACH β€” business overview of ACH payments, including the consent summary
  • Payments β€” general Payments API integration guide