Withholding receipts

POST /v1/withholdings issues a withholding receipt (comprobante de retención, XML 2.0.0): the document a withholding agent gives a supplier for the income tax, VAT or ISD withheld from a payment. One receipt covers one supplier and one or more of their documents.

Request

curl https://api.flashpi.com.ec/v1/withholdings \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: wh-001-002-000004567" \
  -H "Content-Type: application/json" \
  -d @withholding.json

withholding.json

{
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "issueDate": "2026-10-15",
  "subject": {
    "idType": "ruc",
    "id": "0990000000001",
    "name": "Distribuidora del Pacífico S.A.",
    "relatedParty": false,
    "email": "facturacion@example.com"
  },
  "fiscalPeriod": "2026-10",
  "supportingDocuments": [
    {
      "taxSupportCode": "01",
      "documentTypeCode": "01",
      "number": "001-002-000004567",
      "issueDate": "2026-10-10",
      "authorizationNumber": "1010202601099000000000120010020000045677301928413",
      "subtotal": "1000.00",
      "total": "1150.00",
      "taxes": [{ "type": "vat", "rate": "15", "taxableBase": "1000.00" }],
      "withholdings": [
        { "tax": "income_tax", "code": "312", "taxableBase": "1000.00", "rate": "1.75" },
        { "tax": "vat", "code": "1", "taxableBase": "150.00" }
      ],
      "payments": [{ "method": "other_financial_system", "amount": "1150.00" }]
    }
  ],
  "expectedTotal": "62.50"
}

The withheld subject

Field	Required	Notes
subject.idType, subject.id, subject.name	Yes	The supplier. It cannot be a final consumer.
subject.relatedParty	Yes	Whether the supplier is a related party (parte relacionada).
subject.subjectType	With foreign_id	individual or company.
subject.email	No	Where Flashpi emails the authorized receipt.
fiscalPeriod	No	YYYY-MM. Defaults to the month of the issue date.

Supporting documents

Each entry of supportingDocuments (1 to 50) is a document of the supplier, usually their invoice, with what you withhold from it:

Field	Required	Notes
taxSupportCode	Yes	The tax support code (código de sustento) of the Catálogo ATS, table 5, such as 01.
documentTypeCode	Yes	The document type code of the Catálogo ATS, table 4, such as 01 for an invoice.
number, issueDate	Yes	Its number and its issue date, on or before the receipt’s.
authorizationNumber	No	Its authorization number: 10, 37 or 49 digits (the access key of an electronic document).
accountingDate	No	When you recorded it in your books.
subtotal, total	Yes	Its subtotal before taxes and its total, as on the document. Flashpi copies them; it does not recompute them.
taxes	Yes	Its VAT: type vat, the rate in force on its issue date and the taxableBase. amount defaults to base × rate, rounded.
withholdings	Yes	1 to 20 withholdings, see below.
payments	Yes	How it is paid; the payments must add up to its total.
paymentResidence	No	local (default) or foreign. A foreign payment needs foreignPayment with the regime (general, tax_haven or preferential), the SRI country code and the treaty flags.

Withholdings

Field	Required	Notes
tax	Yes	income_tax (renta), vat (IVA) or isd.
code	Yes	The withholding code: the Catálogo ATS for income_tax (for example 312), the SRI’s TABLA 20 for vat (1 = 30 %, 2 = 70 %, 3 = 100 %) and isd.
taxableBase	Yes	The base the percentage applies to. For VAT, that is the VAT amount of the document.
rate	For income_tax	The percentage, up to 2 decimals. For vat and isd Flashpi takes it from the code, and a different rate is refused (rate_mismatch).
dividends	With tax support code 10	paymentDate, corporateIncomeTax and profitFiscalYear.
bananaBoxes	With the banana income tax codes	count and pricePerBox, for codes 338, 340, 341, 342, 342A and 342B.

What Flashpi computes

Each withheld amount is the taxable base × the percentage, rounded half up to 2 decimals, and the receipt’s total is their sum:

Withholding	Base × percentage	Withheld
Income tax, code 312	1000.00 × 1.75 %	17.50
VAT, code 1 (30 %)	150.00 × 30 %	45.00
Total withheld		62.50

expectedTotal is compared with the total withheld.

Response

202 Accepted. The totals of a withholding receipt only have withheld:

{
  "id": "01a14167-168f-7c0b-b002-c22b0b25ee9c",
  "type": "withholding",
  "environment": "test",
  "status": "processing",
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "sequential": 57,
  "number": "001-001-000000057",
  "accessKey": "1510202607179000000000110010010000000575296841018",
  "issueDate": "2026-10-15",
  "xmlVersion": "2.0.0",
  "counterparty": { "id": "0990000000001", "name": "Distribuidora del Pacífico S.A." },
  "totals": { "withheld": "62.50" },
  "authorization": { "number": null, "authorizedAt": null },
  "ride": { "status": "pending", "template": null, "generatedAt": null },
  "email": { "requested": true, "status": "queued", "deliveries": [], "warnings": [] },
  "sriMessages": [],
  "failure": null,
  "voidedAt": null,
  "createdAt": "2026-10-15T21:10:37.455Z",
  "updatedAt": "2026-10-15T21:10:37.455Z"
}

With options.waitForAuthorization the answer can be 200 OK with the final status (Sync and async modes). The withholding.authorized and withholding.rejected webhooks report the SRI’s decision.

Errors

Answer	When
422 validation_failed	For example rate_mismatch on a VAT withholding with another percentage, a missing dividends or bananaBoxes where the codes need them, subject.subjectType missing for a foreign ID, or payments that do not add up to the document’s total.
422 validation_failed with incompatible_issuer_profile	The issuer’s special taxpayer number is longer than the 5 characters a withholding receipt accepts.
422 total_mismatch	expectedTotal differs from the total withheld.
409 sequential_already_used, sequentials_exhausted	See Sequentials.

Flashpi takes the percentage of VAT and ISD withholdings from their code, but it does not check income tax codes and percentages against the Catálogo ATS yet: it uses the rate you send. The withholding catalogs change with the SRI’s resolutions, so check the codes and percentages in force with your accountant.