Skip to content
Documentation
Get started

REST reference

Timbro API 2026-10-01

Section titled “Timbro API 2026-10-01”

Reference for payments, invoices, business setup, refunds, and webhooks.

View OpenAPI

Operations

Section titled “Operations”

Payments

Section titled “Payments”
PUT
Associate an accepted Invoice with a Payment/v1/payments/{paymentId}/invoice
POST
Create the canonical invoice for a captured payment/v1/payments/{paymentId}/invoice
GET
List payments/v1/payments
POST
Create a payment/v1/payments
GET
Retrieve a payment/v1/payments/{paymentId}
POST
Cancel a payment/v1/payments/{paymentId}/cancel
PUT
Update the Invoice recipient/v1/payments/{paymentId}/invoice-recipient
PUT
Update the Invoice choice/v1/payments/{paymentId}/invoice-choice

Subscriptions

Section titled “Subscriptions”
GET
List monthly subscriptions/v1/subscriptions
POST
Create a fixed monthly subscription with automatic fiscal invoicing/v1/subscriptions
GET
Retrieve a subscription and its period Payments/v1/subscriptions/{subscriptionId}
GET
List payments for a subscription/v1/subscriptions/{subscriptionId}/payments
POST
Cancel future charges for a subscription/v1/subscriptions/{subscriptionId}/cancel
POST
Create a scoped management link for a subscription/v1/subscriptions/{subscriptionId}/management
POST
Retrieve the setup link for a subscription/v1/subscriptions/{subscriptionId}/setup
POST
Resend a recovery notice for a subscription/v1/subscriptions/{subscriptionId}/recovery_notice

Invoices

Section titled “Invoices”
GET
List Invoices/v1/invoices
POST
Issue an Invoice/v1/invoices
POST
Replace a rejected Invoice/v1/invoices/{invoiceId}/replacements
POST
Preview an Invoice without issuing it/v1/invoices/preview
GET
Retrieve an Invoice/v1/invoices/{invoiceId}
POST
Email an Invoice to its buyer/v1/invoices/{invoiceId}/deliveries
GET
Retrieve an Invoice delivery/v1/invoices/{invoiceId}/deliveries/{deliveryId}
POST
Share an accepted Invoice's receipt/v1/invoices/{invoiceId}/receipt-access
GET
Retrieve a shared Invoice receipt/v1/invoice-receipts/{receiptId}
GET
Download a shared Invoice receipt's PDF/v1/invoice-receipts/{receiptId}/pdf
GET
Download an Invoice's signed XML/v1/invoices/{invoiceId}/files/xml
GET
Download an Invoice's PDF/v1/invoices/{invoiceId}/files/pdf

Refunds

Section titled “Refunds”
GET
List refunds/v1/refunds
POST
Create a full or partial refund/v1/refunds
PUT
Attach an accepted credit-note Invoice to a refund/v1/refunds/{refundId}/invoice
GET
Retrieve a refund/v1/refunds/{refundId}

Business

Section titled “Business”
GET
Read Invoice issuance readiness for certification/v1/business/certification/invoices/issuance-readiness
POST
Record a DGII certification sequence/v1/business/certification/sequences
POST
Issue an Invoice in certification/v1/business/certification/invoices
GET
Retrieve a certification Invoice/v1/business/certification/invoices/{invoiceId}
GET
Download a certification Invoice XML/v1/business/certification/invoices/{invoiceId}/xml
GET
Download a certification Invoice PDF/v1/business/certification/invoices/{invoiceId}/pdf
GET
Retrieve the business/v1/business
PATCH
Update the business/v1/business
GET
Read peer authentication/v1/business/certification/peer-authentication
POST
Require or stop requiring peer authentication/v1/business/certification/peer-authentication
GET
Retrieve the business certification process/v1/business/certification
POST
Prepare a business certification process/v1/business/certification
POST
Report an outcome for a DGII certification step/v1/business/certification/evidence
POST
Declare the DGII step a business certification is on/v1/business/certification/progress
GET
Retrieve the current certification workbook/v1/business/certification/test-sets/current
POST
Upload a certification workbook/v1/business/certification/test-sets
POST
Run a certification workbook/v1/business/certification/test-runs
GET
Retrieve the latest certification test run/v1/business/certification/test-runs/current
GET
Download a consumer invoice a test run kept/v1/business/certification/test-runs/{runId}/consumer-invoices/{eNcf}
POST
Sign a DGII certification portal document/v1/business/certification/portal-documents/sign
POST
Configure a Timbro invoice environment/v1/business/configure-invoicing
POST
Import a signing certificate/v1/business/import-signing-certificate
POST
Record an e-NCF sequence/v1/business/record-sequence
POST
Issue the test invoice/v1/business/issue-test-invoice
GET
Retrieve the merchant Checkout policy/v1/business/checkout-policy
PUT
Replace the merchant Checkout policy/v1/business/checkout-policy
POST
Verify an RNC/v1/business/rnc-verification

Settings

Section titled “Settings”
GET
List received documents/v1/received-documents
GET
Retrieve a received document/v1/received-documents/{receivedDocumentId}
POST
Accept or reject a received document/v1/received-documents/{receivedDocumentId}/commercial-response
GET
Download a received document's original XML/v1/received-documents/{receivedDocumentId}/files/xml
GET
List merchant accounts/v1/merchant-accounts
GET
Retrieve a merchant account/v1/merchant-accounts/{merchantAccountId}
POST
Rotate the calling secret key/v1/api-keys/rotate
GET
Retrieve the reference exchange rate/v1/exchange-rates/{currency}

Webhooks

Section titled “Webhooks”
GET
List webhook endpoints/v1/webhook-endpoints
POST
Create a merchant webhook endpoint/v1/webhook-endpoints
GET
Retrieve a webhook endpoint/v1/webhook-endpoints/{webhookEndpointId}
DELETE
Delete a webhook endpoint/v1/webhook-endpoints/{webhookEndpointId}
GET
List deliveries to a webhook endpoint/v1/webhook-endpoints/{webhookEndpointId}/deliveries
POST
Replay events to a webhook endpoint/v1/webhook-endpoints/{webhookEndpointId}/replays
POST
Rotate the signing secret of a webhook endpoint/v1/webhook-endpoints/{webhookEndpointId}/rotate-secret
POST
Suspend a webhook endpoint/v1/webhook-endpoints/{webhookEndpointId}/suspend
POST
Reactivate a suspended webhook endpoint/v1/webhook-endpoints/{webhookEndpointId}/reactivate

Events

Section titled “Events”
POST
Webhook: subscription.canceled WEBHOOK
POST
Webhook: subscription.status_changed WEBHOOK
POST
Webhook: payment.succeeded WEBHOOK
POST
Webhook: payment.declined WEBHOOK
POST
Webhook: payment.canceled WEBHOOK
POST
Webhook: payment.expired WEBHOOK
POST
Webhook: payment.operator_required WEBHOOK
POST
Webhook: refund.succeeded WEBHOOK
POST
Webhook: refund.declined WEBHOOK
POST
Webhook: refund.operator_required WEBHOOK
POST
Webhook: refund.invoiceAttached WEBHOOK
POST
Webhook: invoice.accepted WEBHOOK
POST
Webhook: invoice.rejected WEBHOOK
POST
Webhook: invoice.operatorRequired WEBHOOK
POST
Webhook: invoice.ready WEBHOOK
POST
Webhook: invoice.deliverySent WEBHOOK
POST
Webhook: invoice.deliveryFailed WEBHOOK

Authentication

Section titled “Authentication”

secretKey

Section titled “secretKey”

Secret key. Server-side only.

Security scheme type: http

adminKey

Section titled “adminKey”

Administrator key. Server-side only.

Security scheme type: http

integrationToken

Section titled “integrationToken”

Access token of an integration’s machine client, such as an Odoo company, which authenticates with private_key_jwt. Request it with the /v1 resource and the scopes of one mode; a token acts in that mode only.

Security scheme type: oauth2

Flow type: clientCredentials

Token URL: https://api.timbro.do/v1/merchant_auth/oauth2/token

Scopes:

  • invoices:test - Issue and read invoices, and read received documents in test mode.
  • invoices:live - Issue and read invoices, and read received documents in live mode.
  • payments:test - Create, read, and cancel payments and checkout tokens in test mode.
  • payments:live - Create, read, and cancel payments and checkout tokens in live mode.
  • refunds:test - Create and read refunds in test mode.
  • refunds:live - Create and read refunds in live mode.
  • sequences:live - Record the e-NCF sequences DGII granted the business in live mode.

invoiceReceiptAccess

Section titled “invoiceReceiptAccess”

Server-side access token for one accepted Invoice receipt and its PDF. Grants no issuance, XML, or diagnostic authority.

Security scheme type: http