Ir al contenido
TimbroTimbroTimbro

Choose a fiscal document

PUT
/payments/{paymentId}/fiscal-document-choice
curl --request PUT \
  --url https://api.timbro.dev/v1/payments/example/fiscal-document-choice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "kind": "consumer", "buyer": { "identityKind": "domestic", "taxId": "example" }, "governmentEligibility": { "entityKind": "central_government", "authorityReference": "example" } }'

Choose the fiscal document kind and buyer before payment submission.

Authorizations

Sección titulada «Authorizations»

Parameters

Sección titulada «Parameters»

Path Parameters

Sección titulada «Path Parameters»
paymentId
required
string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/

Payment to update.

Header Parameters

Sección titulada «Header Parameters»
idempotency-key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Caller-derived unique key, stable under retry. Printable ASCII. Required.

Request Bodyrequired

Sección titulada «Request Bodyrequired»

The fiscal choice collected before payment submission.

Media typeapplication/json
FiscalDocumentChoiceRequest

The fiscal choice collected before payment submission.

object
kind
string
Allowed values: consumer fiscal_credit government
buyer
Any of:
object
identityKind
required
string
Allowed value: domestic
taxId
required
string
>= 1 characters <= 64 characters
governmentEligibility
Any of:
object
entityKind
required
string
Allowed value: central_government
authorityReference
required
string
>= 1 characters <= 128 characters

Responses

Sección titulada «Responses»

200

Sección titulada «200»

The bill projection safe for a scoped hosted-checkout or receipt holder.

Media typeapplication/json
CheckoutPayment

The bill projection safe for a scoped hosted-checkout or receipt holder.

object
id
required

Payment identifier. Opaque; do not parse beyond the prefix.

string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/
object
required
string
Allowed value: payment
status
required

partially_authorized means some shares have reserved funds, authorized means every share is reserved and awaits the organizer's capture command, capturing means capture is running, and releasing means reserved funds are being released. verifying is a real, non-terminal status; it is not an error or decline.

string
Allowed values: requires_customer_action processing partially_authorized authorized capturing partially_paid releasing verifying succeeded declined canceled expired
amount
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

string
/^[A-Z]{3}$/
minorUnits
required

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
voluntaryTip
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

string
/^[A-Z]{3}$/
minorUnits
required

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
totalAmount
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

string
/^[A-Z]{3}$/
minorUnits
required

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
saleReference
required

Merchant-owned searchable business reference. It is immutable after create, need not be unique, and does not identify command retries.

string
>= 1 characters <= 128 characters
returnUrl

Merchant web destination offered after Checkout. Payment status must be retrieved from the API.

string format: uri
<= 2048 characters /^https?:///
serviceLabel

Merchant-authored context label such as Mesa 12.

string
<= 24 characters
description

Concise description of the product or service being purchased.

string
>= 1 characters <= 80 characters
breakdown
Breakdown

Server-computed money composition. The only totals a checkout page renders.

object
taxableBases
required
Array<object>
BreakdownTaxableBase
object
taxTreatment
required
string
Allowed values: itbis_18 itbis_16 zero_rated
baseMinorUnits
required
integer
taxMinorUnits
required
integer
exemptMinorUnits
required
integer
serviceCharges
required
Array<object>
BreakdownServiceCharge
object
kind
required
string
Allowed values: propina_legal
minorUnits
required
integer
taxesMinorUnits
required
integer
totalMinorUnits
required
integer
groups
Array<object>
BreakdownGroup
object
group
required
string
>= 1 characters <= 64 characters
subtotalMinorUnits
required
integer
checkoutDisplay
required
CheckoutDisplay

Read-only checkout presentation assembled from merchant configuration.

object
mode
required
string
Allowed values: itemized grouped amount_only
locale
required
string
>= 2 characters <= 16 characters
merchant
required
CheckoutDisplayMerchant
object
legalName
required
string
>= 1 characters <= 256 characters
rnc
required
string
/^\d{9}$/
displayName
required
string
>= 1 characters <= 128 characters
supportPhone
required
string
>= 1 characters <= 32 characters
supportEmail
string format: email
<= 254 characters
permanentAddress
CheckoutDisplayPermanentAddress
object
line1
required
string
>= 1 characters <= 160 characters
line2
string
>= 1 characters <= 160 characters
city
required
string
>= 1 characters <= 80 characters
province
string
>= 1 characters <= 80 characters
postalCode
string
>= 1 characters <= 20 characters
countryCode
required
string
/^[A-Z]{2}$/
deliveryPolicy
Any of:
object
kind
required
string
Allowed value: not_offered
statementDescriptor
required
string
>= 1 characters <= 22 characters
fiscal
required
CheckoutDisplayFiscal
object
availableKinds
required
Array<object>
FiscalAvailableKind
object
kind
required
string
Allowed values: consumer fiscal_credit government
isAvailable
required
boolean
buyerRequirement
required
string
Allowed values: none optional required
isLocked
required
boolean
serviceCharges
required
CheckoutDisplayServiceCharges
object
isPropinaApplicable
required
boolean
wallets
required
Array<string>
Allowed values: apple_pay google_pay
acceptedCardBrands

Card brands certified for this Payment's Merchant Account snapshot.

Array<string>
<= 3 items unique items
Allowed values: visa mastercard amex
threeDsPrograms

3-D Secure programs selected for this immutable Payment journey. An empty list means card submission does not use 3DS.

Array<string>
<= 3 items unique items
Allowed values: visa_secure mastercard_identity_check amex_safekey
nextAction
One of: discriminator: kind
RedirectToUrlAction

Send the customer to the hosted checkout page.

object
kind
required
string
Allowed value: redirect_to_url
url
required

Open in a top-level browsing context.

string format: uri
expiresAt
required
string format: date-time
decline
required
Any of:
Decline

Present only while status is declined.

object
code
required

Normalized decline code. Raw provider codes are not public.

string
Allowed values: insufficient_funds card_expired invalid_card_number incorrect_security_code incorrect_pin card_restricted card_reported_lost_or_stolen exceeds_limit transaction_not_permitted authentication_failed suspected_fraud do_not_honor issuer_unavailable generic_decline
canTryAgain
required
boolean
message
required

Customer-safe explanation. Wording may change.

string
verification
required
Any of:
Verification

Reconciliation progress while status is verifying.

object
startedAt
required
string format: date-time
nextCheckAt
required
string format: date-time
isEscalated
required
boolean
paymentMethodSummary
required
Any of:
One of: discriminator: kind
CardPaymentMethodSummary
object
kind
required
string
Allowed value: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
isLiveMode
required
boolean
expiresAt
required
string format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
fiscalDocument
required
Any of:
One of: discriminator: status
object
id
required

Fiscal document identifier.

string
/^fiscal_document_[0-9a-hjkmnp-tv-z]{24,}$/
object
required
string
Allowed value: fiscal_document
paymentId
required

Payment that requested the fiscal document.

string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/
kind
required
string
Allowed values: consumer fiscal_credit government
issuanceMode
required

Whether fiscal issuance is required before Checkout presents the purchase as complete or may finish after the paid receipt is shown.

string
Allowed values: required deferred
revision
required
integer
>= 1
buyer
FiscalBuyer
object
identityKind
required
string
Allowed values: domestic foreign
taxId
required
Any of:
string
/^\d{9}$|^\d{11}$/
foreignId
required
Any of:
string
>= 1 characters <= 20 characters /^[A-Za-z0-9][A-Za-z0-9._/-]{0,19}$/
legalName
required
string
>= 1 characters <= 256 characters
address
string
>= 1 characters <= 100 characters
contactName
string
>= 1 characters <= 80 characters
email
string format: email
<= 80 characters
governmentEligibility
Any of:
object
entityKind
required
string
Allowed value: central_government
authorityReference
required
string
>= 1 characters <= 128 characters
lines
required
Array<object>
>= 1 items
FiscalLine
object
sourceLineId
required
string
>= 1 characters <= 128 characters
description
required
string
>= 1 characters <= 80 characters
quantity
required
string
/^(?=[0-9.]*[1-9])[0-9]{1,16}(\.[0-9]{1,2})?$/
measurementUnit
required
string
Allowed values: unit kilogram litre metre piece
unitPriceMinorUnits
required
integer
itemKind
required
string
Allowed values: good service
taxTreatment
required
string
Allowed values: itbis_18 itbis_16 zero_rated exempt non_billable
isLegalTipApplicable
required

Whether this line belongs to the merchant's mandatory legal-tip base. Non-billable lines cannot be eligible.

boolean
group
string
>= 1 characters <= 64 characters
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
status
required
string
Allowed value: requested
delivery
required
Any of:
One of: discriminator: status
object
email
required
string format: email
<= 320 characters
status
required
string
Allowed value: waiting_for_document
Example
{
  "object": "payment",
  "status": "requires_customer_action",
  "amount": {
    "currency": "DOP",
    "minorUnits": 125000
  },
  "voluntaryTip": {
    "currency": "DOP",
    "minorUnits": 125000
  },
  "totalAmount": {
    "currency": "DOP",
    "minorUnits": 125000
  },
  "breakdown": {
    "taxableBases": [
      {
        "taxTreatment": "itbis_18"
      }
    ],
    "serviceCharges": [
      {
        "kind": "propina_legal"
      }
    ]
  },
  "checkoutDisplay": {
    "mode": "itemized",
    "merchant": {
      "deliveryPolicy": {
        "kind": "not_offered"
      }
    },
    "fiscal": {
      "availableKinds": [
        {
          "kind": "consumer",
          "buyerRequirement": "none"
        }
      ]
    },
    "wallets": [
      "apple_pay"
    ],
    "acceptedCardBrands": [
      "visa"
    ],
    "threeDsPrograms": [
      "visa_secure"
    ]
  },
  "nextAction": {
    "kind": "redirect_to_url"
  },
  "decline": {
    "code": "insufficient_funds"
  },
  "paymentMethodSummary": {
    "kind": "card"
  },
  "fiscalDocument": {
    "object": "fiscal_document",
    "kind": "consumer",
    "issuanceMode": "required",
    "buyer": {
      "identityKind": "domestic"
    },
    "governmentEligibility": {
      "entityKind": "central_government"
    },
    "lines": [
      {
        "measurementUnit": "unit",
        "itemKind": "good",
        "taxTreatment": "itbis_18"
      }
    ],
    "status": "requested",
    "delivery": {
      "status": "waiting_for_document"
    }
  }
}

400

Sección titulada «400»

The request could not be understood or is not valid for this merchant account.

Media typeapplication/json
InvalidRequestError

The request could not be understood or is not valid for this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: parameter_missing parameter_invalid provider_not_available currency_not_supported amount_below_minimum amount_above_maximum checkout_reference_invalid checkout_reference_expired fiscal_buyer_tax_id_invalid fiscal_line_total_invalid fiscal_lines_required payment_split_invalid
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing"
  }
}

401

Sección titulada «401»

The credential is missing, malformed, or no longer valid.

Media typeapplication/json
AuthenticationError

The credential is missing, malformed, or no longer valid.

object
error
required
object
type
required
string
Allowed value: authentication_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_missing"
  }
}

403

Sección titulada «403»

The credential is valid but not permitted to perform this operation on this resource.

Media typeapplication/json
PermissionError

The credential is valid but not permitted to perform this operation on this resource.

object
error
required
object
type
required
string
Allowed value: permission_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: merchant_account_not_owned merchant_account_admin_required operation_not_permitted_for_checkout_token live_mode_not_enabled
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "permission_error",
    "code": "merchant_account_not_owned"
  }
}

404

Sección titulada «404»

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

Media typeapplication/json
NotFoundError

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: endpoint_not_found payment_not_found fiscal_document_not_found merchant_account_not_found merchant_profile_not_found payment_split_not_found payment_part_not_found
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "endpoint_not_found"
  }
}

409

Sección titulada «409»

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

Media typeapplication/json
ConflictError

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: conflict_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: idempotency_key_reused idempotency_request_in_progress idempotency_key_expired payment_method_already_in_progress payment_awaiting_verification decline_not_retryable checkout_window_closed fiscal_preset_locked payment_not_editable fiscal_buyer_required fiscal_correction_not_allowed payment_split_not_allowed payment_split_exists payment_split_locked payment_split_not_capturable payment_split_not_expired payment_split_not_renewable payment_split_complete payment_split_part_required payment_part_not_payable fiscal_artifact_not_ready
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_key_reused"
  }
}

422

Sección titulada «422»

Default Response

Media typeapplication/json
Any of:
UnprocessableRequestError

The request is well-formed but cannot be carried out for this payment or this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: merchant_account_not_ready merchant_profile_incomplete payment_description_required merchant_account_provider_mismatch credential_storage_unavailable provider_not_eligible no_eligible_provider currency_not_supported_by_provider currency_not_supported_for_fiscal_document fiscal_total_mismatch fiscal_line_total_invalid fiscal_line_legal_tip_invalid fiscal_document_kind_not_allowed fiscal_document_kind_unsupported fiscal_government_eligibility_required fiscal_government_eligibility_not_allowed
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "merchant_account_not_ready"
  }
}

429

Sección titulada «429»

Too many requests. Retry after the interval in the Retry-After header.

Media typeapplication/json
RateLimitError

Too many requests. Retry after the interval in the Retry-After header.

object
error
required
object
type
required
string
Allowed value: rate_limit_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: rate_limit_exceeded
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500

Sección titulada «500»

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

Media typeapplication/json
ApiError

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: api_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: internal_error
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "api_error",
    "code": "internal_error"
  }
}

502

Sección titulada «502»

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

Media typeapplication/json
ProviderError

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: provider_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: provider_unavailable provider_rejected_request
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "provider_error",
    "code": "provider_unavailable"
  }
}

503

Sección titulada «503»

A required Gateway dependency is temporarily unavailable. The request is safe to retry.

Media typeapplication/json
TaxpayerDirectoryUnavailableError

A required Gateway dependency is temporarily unavailable. The request is safe to retry.

object
error
required
object
type
required
string
Allowed value: api_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: taxpayer_directory_unavailable
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "api_error",
    "code": "taxpayer_directory_unavailable"
  }
}