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.
- Prerequisite: A
BANK_ACCOUNTpayment method on the customer's wallet or in the request. - Endpoint:
POST /v2/payments(andPOST /v2/token/paymentsfor PCI-scope flows) β theconsentobject is part of the payment request body. For widget/session-flow payments,merchantConsentTextis instead supplied in theconsentobject of the session request (POST /v2/sessions) β see Sessions. - Scope:
merchantormerchant-pci - Use: Collecting and submitting NACHA-compliant consent for ACH payments
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. Card payments do not require a consent object.
| 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 |
API Requestβ
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
POST /v2/paymentscall):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"
}
}
}
}
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β
Can I reuse consent from a previous payment attempt?β
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.
Do saved/wallet bank accounts need consent on every payment?β
Yes β consent must accompany every ACH payment request regardless of whether the bank account is newly entered or previously saved.
Integration Checklistβ
- Include a
consentobject on every ACH (BANK_ACCOUNT) payment request - Choose the correct
collectionDetails.type(WEB,TEL, orPPD) for your channel - Supply
merchantConsentIdfor your merchant-initiated or guest-flow payment requests, ormerchantConsentTextin the session request (POST /v2/sessions) for widget/session-flow payments - Always set
collectionTimestampin 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