Checking access…

Skip to main content
Version: v1

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.

Quick Reference
  • Purpose: Field requirements and validation rules for collecting NACHA-compliant ACH consent.
  • Applies To: BANK_ACCOUNT payment method only β€” card payments do not require a consent object.
  • Collection Types: WEB, TEL, PPD
  • Related: Payments, Create Session (for widget/session-flow consent)

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.

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

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 payment request): 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"
}
}
}
}

Sample Requests​

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"
}
}
}

Sample 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.

Edge Cases​

Low Probability β€” Stale Consent Timestamp

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.

Low Probability β€” Missing Consent on Retry

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.

Error Handling​

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

  • ACH β€” business overview of ACH payments, including the consent summary
  • Payments β€” general Payments API integration guide