Processor: Bbva
BBVA is a V1 payment processor configured at the center level. It supports card and ACH (Automated Clearing House) direct-debit payments with card-on-file storage and a dedicated stored-account vault (BBVAStoredAccount). BBVA does not support terminals or card readers.
Before you begin
Permission: Center-level payment configuration access is required.
BBVA merchant-side prerequisites
- BBVA merchant agreement activated for card and ACH processing in your region.
- ACH rail enrolment β if you plan to accept direct-debit payments, BBVA must enable the ACH / local direct-debit rail on your MID (Merchant Identifier).
- Batch processing β BBVA uses batched settlement; your BBVA representative confirms the cut-off time.
Credentials
| Field | Source / owner | What to enter |
|---|---|---|
| API credentials (MID + secret) | BBVA account representative / BBVA merchant portal | Issued on MID activation. Zenoti does not supply defaults. |
[SOURCE GAP β PM VERIFY: exact credential field names for BBVA. FS references API credentials without naming each field.]
Network requirements
| Direction | Port | Protocol | Why |
|---|---|---|---|
| Outbound from Zenoti to BBVA API | 443 | HTTPS | Charge, refund, tokenization, and batch-status calls |
| Outbound from BBVA to Zenoti | 443 | HTTPS | Batch-settlement and ACH-return callbacks |
BBVA capabilities in Zenoti
| Capability | Supported |
|---|---|
| ACH direct debit | Yes |
| Card (online) | Yes |
| Stored accounts | Yes (dedicated BBVAStoredAccount class) |
| Global tokenization within BBVA-family processors | Yes |
| Recurring payments | Yes |
| Sale | Yes |
| Refund | [SOURCE GAP β PM VERIFY: BBVAProcessor.cs has no RefundTransaction override; refunds may route via batch processing or a separate microservice.] |
| Void | [SOURCE GAP β PM VERIFY: same as refund.] |
| Terminal (POS (Point of Sale)) | No (no card-reader class) |
Configure BBVA
- At the center level, navigate to Configuration > Payments > Settings (the center-scope caption of the Payments row).
- Select BBVA as the payment processor.
- Enter your BBVA API credentials.
- Enable card and/or ACH channels as activated on the BBVA side.
- Select Save.
- Select Test to verify.
Toggle interactions
| Card | ACH direct debit | Stored card-on-file | Behaviour |
|---|---|---|---|
| Off | Off | Off | BBVA not available at checkout. |
| On | Off | Off | One-off card payments only. |
| Off | On | Off | ACH debits only. |
| On | On | Off | Guest picks card or ACH. |
| On | On | On | Recommended for recurring / membership businesses. |
Process a payment
- On the invoice, select BBVA as the payment method.
- Choose card or ACH (if both are enabled).
- Enter payment details or select a stored account.
- Zenoti submits the charge to BBVA; the result is returned inline (card) or queued into the next batch (ACH).
Manage stored accounts
Cards saved against BBVA live in the BBVA vault via the BBVAStoredAccount class. The vault supports tokenization across BBVA-family processor instances in the same organization.
Edit or reverse a posted payment
| Invoice state | What you can do |
|---|---|
| Open | Remove the BBVA payment line; re-take if needed. For ACH charges already queued, contact BBVA support to stop the batch if it has not yet been submitted. |
| Closed | Reopen if permissions allow, or post a compensating refund line. Because refund support in the processor class is uncertain ([SOURCE GAP]), coordinate with BBVA support and record the refund reference in Zenoti as an "Other"-category entry if needed. |
Failure modes
| Failure mode | User-visible symptom | Resolution |
|---|---|---|
| BBVA API unreachable | Transaction fails with communication error. | Check outbound HTTPS and BBVA status. Retry. |
| Authentication expired | Every transaction fails with auth error. | Re-verify credentials with BBVA. |
| Card declined | Issuer decline returned inline. | Guest retries. |
| ACH bank reject (insufficient funds, account closed) | Charge appears settled then reverses days later when the batch return comes back. | Invoice reopens; guest must provide another method. Normal ACH behaviour. |
| Amount out of range | Rejected at gateway. | BBVA enforces per-channel minimums and maximums; confirm with BBVA. |
| Currency mismatch | Rejected. | Confirm center currency matches BBVA's activated currency. |
| Settlement / batch failure | ACH batch not ingested. | Raise with BBVA support using the batch ID. |
Settlement and reconciliation
BBVA uses batch settlement; the daily cut-off is BBVA-side. ACH debits typically settle T+1 to T+3 in the markets BBVA serves, with up to 5 business days for return notifications. [SOURCE GAP β PM VERIFY: exact settlement window.]
| Source | Report / view | Match key |
|---|---|---|
| Zenoti | Collections report (filter: Payment Method = BBVA) | BBVA transaction / batch reference + Zenoti invoice number |
| BBVA | BBVA merchant portal settlement / batch report | Same fields |
Recommended cadence: daily β ACH returns arrive asynchronously and must be caught quickly.
Tips
- BBVA is primarily used for ACH-based payment flows. Verify that your BBVA merchant account is configured for ACH debit before enabling this processor.
- If ACH payments fail, verify the guest's bank account details are correctly entered.
- BBVA uses its own stored-account vault β cards stored here cannot be migrated to a different processor without re-enrolment.