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.
- Purpose: Field requirements and validation rules for collecting NACHA-compliant ACH consent.
- Applies To:
BANK_ACCOUNTpayment method only β card payments do not require a consent object. - Collection Types:
WEB,TEL,PPD - Related: Payments, Create Session (for widget/session-flow consent)
Consent Collection Typesβ
CCG supports three NACHA-defined collection types to accommodate different channels:
| Consent Type | Collection Method | Typical Use Case |
|---|---|---|
| WEB | Online / digital | Self-service web or mobile payment |
| TEL | Verbal / telephonic | IVR or agent-assisted phone payment |
| PPD | Physical / paper | Signed paper authorization form |
Consent is required for all ACH (bank account) payments.
| Payment Method | Consent Required |
|---|---|
| Bank Account (ACH) | Yes β full consent object required |
| Credit / Debit Card | No |
| Saved Bank Account | Yes β consent must accompany the payment request |
| IVR Bank Account | Yes β TEL consent type required |
Field Requirementsβ
- A consent object must be present on every ACH payment request.
collectionDetails.typemust be one ofWEB,TEL, orPPD.- 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 theconsentobject 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):
merchantConsentIdis required instead β a reference to a consent record stored by the merchant.
- CCG Widget / checkout session flow: supply
| Field | Rule |
|---|---|
collectionTimestamp | Required when consent object is present. Must be ISO-8601 format (e.g., 2025-07-21T14:30:00Z). |
| WEB type | collectionDetails.web.ipAddress and collectionDetails.web.userAgent are required. |
| TEL type | collectionDetails.tel must be present (non-null). inboundPhoneNumber and its sub-fields are optional. |
| PPD type | agent 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β
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.
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.