This guide is for AP clerks and tax accountants at a tenant designated as an ITBMS withholding agent under DGI Resolución 201-8055.
Before any certificate can be issued, the administrator must complete the following (one-time):
See the Administrator Guide for details.
You receive a vendor bill with ITBMS → You post a payment for that bill
↓
CifraHQ calculates 50% retention
↓
Certificate issued + GL posted + PDF emailed
↓
End of month: generate Formulario 4331
↓
Upload CSV to DGI e-Tax 2.0
A retention is generated automatically only when all of these conditions are true at the time you post the payment:
| Gate | Where to set it | What it does |
|---|---|---|
| Agent designation is enabled | Accounting → ITBMS Withholdings (Settings) | Master switch for the entire module |
| Payment date is inside your effective window | Accounting → ITBMS Withholdings (Settings) | Honors biennial designation cycles |
| The vendor is marked Subject to ITBMS withholding | Vendor detail → Withholding section | Per-vendor opt-in/out |
| The vendor's Tax Domicile is Panama | Vendor detail → Withholding section | Automatically excludes foreign Vendors |
| The source bill has at least one ITBMS-bearing line | Bill detail | Nothing to withhold from a zero-ITBMS bill |
Miami / US / Mexican / Canadian Vendors are excluded by default. When you set Tax Domicile to anything other than Panama, Subject to ITBMS withholding automatically turns off.
RetentionCertificate row with a sequential number (e.g., RT-00000001)The payment itself is unaffected - it posts at the gross amount. The retention is a separate document so your AP aging stays clean.
There are three places you can find an issued certificate:
When you open a posted Bill Payment that triggered a retention, you'll see a Withholding Certificate panel on the right sidebar. The panel shows:
| Field | What it tells you |
|---|---|
| Certificate Number | The sequential number assigned at issue time (e.g., RT-00000007) |
| Issue Date | The retention's trigger date - usually the payment's posting date |
| Total Withheld | The dollar amount retained from the supplier (50% of ITBMS) |
| Supplier | The vendor's legal name and the email the certificate was sent to |
| Status | Issued / Voided |
| Delivery | Email - delivered {timestamp} once the auto-send job finishes, or Not yet delivered if the email is still queued or failed |
| Storage | Azure Blob (PDF uploaded to the tenant's container) or Local fallback (Azure was unavailable; click Resend to retry) |
The panel has three action buttons:
https://verify.CifraHQ.cloud/cert/{token} URL to your clipboard, ready to paste into a chat or follow-up email.If the payment did not trigger a retention (foreign vendor, no ITBMS on the bill, etc.), the panel simply does not appear. There is no error and no empty card - the right sidebar just shows the regular payment fields.
Accounting → Form 4331 rolls up every period's totals: supplier count, certificate count, taxable base, ITBMS invoiced, ITBMS withheld, status, and a per-period CSV export. Drill into a row to see all certificates issued in that month and their state.
For programmatic access, every certificate exposes:
GET /api/RetentionCertificate/Download?id={certificateId}
The response is a fresh PDF stream (application/pdf). This is the same renderer the Reprint PDF button uses - handy for scripts, archival jobs, or supplier portals.
Two scenarios drive almost all reprint/resend traffic:
This is the most common case. The auto-email is sent immediately after the retention posts, but mail can land in spam, bounce on a typo'd address, or be quietly dropped by an over-eager filter at the supplier's MX.
Resolution steps:
Email - delivered {new timestamp}.The certificate row in the database is immutable for compliance - the issue date, number, amount, and verification token never change. But the rendered PDF is always built from live data at request time:
PrintReports row, so a template update (uploaded via the Stimulsoft designer) is picked up instantly.Settings → Company values.So if you re-brand the company logo or correct a typo in a supplier's legal name, just click Reprint on each affected certificate. No re-issue, no new sequence number, no new GL entry.
When the PDF render succeeds but the Azure blob upload fails (network blip, storage account permissions, account key rotation), the system falls back to a local:// storage marker. The certificate row still shows Issued and the email may still send, but the archived PDF is only on the worker that handled the request.
Resend explicitly clears the local:// marker before re-running the job, forcing a fresh PDF render and a fresh Azure upload. After Resend, the Storage row should read Azure Blob - at that point the PDF is durably stored in the tenant's container and survives worker recycles.
The PDF (Spanish by default for Panama tenants) includes:
https://verify.CifraHQ.cloud/cert/{token}Suppliers can verify any certificate by visiting the URL (public, no login).
You can void a certificate before the period is closed. Voiding:
After the period is closed (state Submitted), voiding is blocked. Use the Amendment workflow on the Form 4331 instead.
X-Form4331-Hash SHA-256 header. The same hash is persisted on the return for audit.Filing deadline: the 15th of the month following the filing month. Late filings incur a minimum USD 10 penalty plus interest.
| Symptom | Likely cause | What to do |
|---|---|---|
| Payment posted but no Withholding Certificate panel | Vendor has Subject to ITBMS withholding = false, or Tax Domicile ≠ Panama, or the bill had no ITBMS lines | Verify the vendor record. If the vendor is correctly flagged, the bill probably had no ITBMS lines - nothing to withhold from. |
| Payment posted, vendor is correct, but the panel still shows nothing | The retention job is still running, or hit an error mid-issue | Refresh after 30 seconds. If the panel still doesn't appear, see "Orphan recovery" in the Administrator Guide. |
Panel shows the cert but Storage reads Local fallback |
Azure blob upload failed (transient network issue, storage account permission rotation, etc.) | Click Resend by email - it forces a fresh PDF render plus a fresh Azure upload. |
Panel shows the cert but Delivery reads Not yet delivered after a minute |
Email delivery job failed or is still queued | Click Resend by email; verify the supplier email is correct first. |
| Supplier Reports the email never arrived | Spam filter or bounced address | Verify and fix the vendor email if needed, then click Resend by email. If the supplier's MX rejects ours, click Reprint PDF and forward manually. |
| Reprint button Returns an error about template render | The Stimulsoft template wasn't seeded into this tenant DB | Ask the admin to run POST /api/WithholdingTemplateSeeder/Seed (see Administrator Guide). |
| "GL/subledger mismatch" during 4331 validation | A retention was issued but the GL accounts on the tenant config are not set | Open Accounting → ITBMS Withholdings (Settings) and pick the ITBMS Withheld Payable account. |
| Form 4331 generation refused | One of the close-validation rules failed | Click Validate first - the dialog lists every reason. |
| Period close blocked by "uncertified retention" warning | A retention row exists with no matching certificate (orphan) | See "Orphan recovery" in the Administrator Guide. |
Was this page helpful?