Skip to content
Documentation
Get started

Payments

Update the Invoice choice

PUT
/v1/payments/{paymentId}/invoice-choice
curl --request PUT \
  --url https://api.timbro.do/v1/payments/example/invoice-choice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "type": "E31", "buyer": { "kind": "anonymous" }, "governmentEligibility": { "entityKind": "central_government", "authorityReference": "example" } }'

Choose the Invoice type and buyer before payment submission. A change retires prepared payment-method submission tokens, so prepare payment methods again before submitting.

Authentication

Section titled “Authentication”

Parameters

Section titled “Parameters”

Path parameters

Section titled “Path parameters”
paymentId
required
string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/

Payment to update.

Header parameters

Section titled “Header parameters”
idempotency-key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

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

Request bodyrequired

Section titled “Request bodyrequired”
Media typeapplication/json

Choose the Invoice type and buyer before payment submission. Use an anonymous buyer to clear a previous recipient.

object
type
string
Allowed values: E31 E32 E45
buyer
Any of:
object
kind
required
string
Allowed value: anonymous
governmentEligibility
Any of:
object
entityKind
required
string
Allowed value: central_government
authorityReference
required
string
>= 1 characters <= 128 characters

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
Response fields and codes

One durable merchant payment request.

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

Only succeeded, canceled, and expired are terminal. A declined attempt returns the Payment to requires_customer_action with lastDecline, so the payer can try again until the Payment expires. 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 canceled expired
source
required

Immutable commercial source coordinate supplied by the merchant adapter.

object
id
required
string
>= 1 characters <= 256 characters
version
required
string
>= 1 characters <= 128 characters
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
checkoutDisplay
required

Read-only checkout presentation assembled from merchant configuration.

object
mode
required
string
Allowed values: itemized grouped amount_only
locale
required

Interface language. Amount notation and currency are independent of language.

string
Allowed values: es en
merchant
required
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
object
line1
required
string
>= 1 characters <= 160 characters
city
required
string
>= 1 characters <= 80 characters
countryCode
required
string
/^[A-Z]{2}$/
line2
string
>= 1 characters <= 160 characters
province
string
>= 1 characters <= 80 characters
postalCode
string
>= 1 characters <= 20 characters
deliveryPolicy
Any of:
object
kind
required
string
Allowed value: not_offered
statementDescriptor
required
string
>= 1 characters <= 22 characters
fiscal
required
object
availableKinds
required
Array<object>
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
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
checkoutReference
required

Unpredictable bearer handle for the full receipt projection after terminal payment. Possession reveals buyer identity and itemization; keep it private.

string
/^checkout_[0-9a-hjkmnp-tv-z]{24,}$/
lastDecline
required
Any of:

The most recent declined attempt. A decline ends the attempt, not the Payment; the payer can try again until the Payment expires. Submitting the next attempt, canceling the Payment, or creating, replacing, or renewing its split clears it; expiry keeps it.

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 authentication_unavailable suspected_fraud do_not_honor issuer_unavailable generic_decline confirmation_timeout
message
required

Customer-safe explanation. Wording may change.

string
attemptedAt
required

When the gateway recorded the provider’s decline of this attempt.

string format: date-time
problem
required
Any of:

An approved payment whose settlement evidence needs operator resolution. It does not withdraw the approval.

object
code
required

Normalized classification of a settlement problem found after approval.

string
Allowed values: settlement_amount_mismatch settlement_record_not_found settlement_amount_unverified
message
required
string
>= 1 characters <= 500 characters
invoiceId
required
Any of:

Canonical Timbro Invoice UUID when admitted.

string format: uuid
invoicing
required
Any of:

Retained Invoice instructions and recipient choice. Invoice lifecycle and access credentials are reported separately.

object
mode
required
Any of:
string
Allowed value: automatic
type
required
string
Allowed values: E31 E32 E45
recipientEmail
required
Any of:
string format: email
<= 320 characters
issuanceProblem

One RFC 9457 problem body returned on the /v1 surface.

object
code
required
string
>= 1 characters
requestId
required
string
status
required
integer format: int32
>= 400 <= 599
title
required
string
type
required
string
Allowed values: about:blank
detail
string
invoiceId

Present only when the rejected request produced a Fiscal operation.

string
issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>
Allowed values: invalid_request unsupported_protocol unsupported_rules_version invalid_resolved_facts numbering_verifier_missing numbering_mode_not_enabled document_type_not_recognized sequence_missing sequence_not_observed_on_effective_date sequence_suspended sequence_cancelled sequence_superseded sequence_exhausted sequence_conflicting sequence_document_type_mismatch sequence_rejected_by_dgii sequence_expired sequence_range_overlap fiscal_number_capacity_exhausted invalid_fiscal_number fiscal_number_outside_authorized_range fiscal_number_before_verified_floor sequence_expiration_mismatch
problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object
code
required
string
message
required
string
path
required
string
buyer
discriminator: kind
object
kind
required
string
Allowed values: anonymous
governmentEligibility
Any of:
object
entityKind
required
string
Allowed value: central_government
authorityReference
required
string
>= 1 characters <= 128 characters
allowedTypes
Array<string>
Allowed values: E31 E32 E45
isTypeLocked
boolean
isBuyerLocked
boolean
revision

Increases each time the Invoice type, buyer, or government eligibility changes.

integer
>= 1
invoiceReference
string
>= 1 characters <= 128 characters
verification
required
Any of:

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:
discriminator: kind
object
kind
required
string
Allowed value: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
isLiveMode
required
boolean
expiresAt
required
Any of:
string format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
sale
required
discriminator: kind
object
kind
required
string
Allowed value: itemized
reference
required
string
>= 1 characters <= 128 characters
currency
required
string
/^[A-Z]{3}$/
items
required
Array<object>
>= 1 items
object
id
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})?$/
unitPrice
required
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,4})?$/
tax
required
object
kind
required
Any of:
string
Allowed value: itbis_18
included
required
boolean
product

Presentation metadata. It is excluded from the fiscal canonical content.

object
id
required
string
>= 1 characters <= 128 characters
sku
string
>= 1 characters <= 128 characters
name
string
>= 1 characters <= 256 characters
description
string
>= 1 characters <= 500 characters
imageUrl
string format: uri
<= 2048 characters
unit
string
Allowed values: barrel bag jar bundle bottle box cigarette_pack centimetre cylinder set container day dozen bale gallon degree gram bulk hour crate kilogram kilowatt_hour pound litre lot metre square_metre cubic_metre million_btu minute package pair foot piece roll envelope second tank ton tube yard square_yard unit element thousand sack tin display drum ration quintal gross_register_tonnage square_foot passenger inch boat_berth_stay tray hectare millilitre milligram ounce troy_ounce
kind
Any of:
string
Allowed value: good
legalTip
object
applied
required
boolean
group
string
>= 1 characters <= 64 characters
totals
required
object
net
required
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
tax
required
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
legalTip
required
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
total
required
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
paymentReference
required

Immutable payment request identity within merchant and TEST/LIVE scope.

string
>= 1 characters <= 128 characters
amount
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
voluntaryTip
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
totalAmount
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
checkout
required
object
url
required
string format: uri
<= 2048 characters /^https?:///
expiresAt
required
Any of:
string format: date-time
split
required
Any of:
object
status
required

Aggregate split state. captured is settled money; authorized is reserved money; releasing and released describe authorization release.

string
Allowed values: open partially_authorized authorized capturing partially_paid releasing released succeeded expired
captured
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
authorized
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
remainingToAuthorize
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
remainingToCapture
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
capturedCount
required
integer
<= 10
authorizedCount
required
integer
<= 10
partCount
required
integer
>= 2 <= 10
parts
required
Array<object>
>= 2 items <= 10 items
object
ordinal
required
integer
>= 1 <= 10
amount
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
allocatedItbis
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
status
required

Authorization and capture state for one share. authorized means funds are reserved; succeeded means the reservation was captured.

string
Allowed values: unpaid processing authorized capturing releasing verifying succeeded released expired
lastDecline
required
Any of:

The most recent declined attempt. A decline ends the attempt, not the Payment; the payer can try again until the Payment expires. Submitting the next attempt, canceling the Payment, or creating, replacing, or renewing its split clears it; expiry keeps it.

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 authentication_unavailable suspected_fraud do_not_honor issuer_unavailable generic_decline confirmation_timeout
message
required

Customer-safe explanation. Wording may change.

string
attemptedAt
required

When the gateway recorded the provider’s decline of this attempt.

string format: date-time
paymentMethodSummary
required
Any of:
discriminator: kind
object
kind
required
string
Allowed value: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
refundable
required
Any of:
object
amount
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
automaticAmount
required
Any of:

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
automaticPartial
required
Any of:
object
maximumAmount
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
maximumTaxAmount
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
Optional fields
subscriptionId

Subscription owning this billing period

string
/^sub_[0-9a-hjkmnp-tv-z]{24,}$/
initiator
Any of:
string
Allowed value: customer
billingPeriod
object
start
required
string format: date-time
end
required
string format: date-time
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

Server-computed money composition. The invariant is payableTotalMinorUnits = fiscalDeclaredTotalMinorUnits + nonBillableMinorUnits; legal and voluntary tips are never double-counted.

object
taxableBases
required
Array<object>
object
taxTreatment
required
string
Allowed values: itbis_18 itbis_16 zero_rated
baseMinorUnits
required
integer
taxMinorUnits
required
integer
exemptMinorUnits
required
integer
nonBillableMinorUnits
required
integer
serviceCharges
required
Array<object>
object
kind
required
string
Allowed values: propina_legal
minorUnits
required
integer
taxesMinorUnits
required
integer
fiscalDeclaredTotalMinorUnits
required

Fiscal declared total: taxable bases, taxes, exempt lines, and legal tip. Non-billable lines are excluded.

integer
payableTotalMinorUnits
required

Commercial payable total: fiscalDeclaredTotalMinorUnits plus nonBillableMinorUnits. This is the amount collected before a voluntary tip.

integer
groups
Array<object>
object
group
required
string
>= 1 characters <= 64 characters
subtotalMinorUnits
required
integer
nextAction
discriminator: kind

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
paymentChannel
object
kind
required
string
Allowed value: bank_checkout
bank
required
Any of:
string
Allowed value: popular
processingReason
string
Allowed value: awaiting_company_approval
metadata

Merchant-owned keys carried with this Payment: at most 20 keys of 1 to 40 characters, each holding a string of at most 500 characters. Checkout stores it opaquely, never branches on it, never sends it to a payment provider, and never repeats it in a webhook body or a payer projection. It lives as long as its Payment and is deleted with it. Never put personal data or card data in it.

object
<= 20 properties
key
additional properties
string
<= 500 characters
tax
object
includedAmount
required

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
provenance
required
Any of:
string
Allowed value: explicit
policyRevision
integer
capturedPayment
object
allocations
required
Array<object>
>= 1 items
object
id
required

Stable identifier for one captured payment allocation.

string
/^payment_allocation_[0-9a-hjkmnp-tv-z]{24,}$/
amount
required

An exact decimal monetary amount.

object
currency
required

Example

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

Exact nonnegative decimal amount, with at most two fractional digits.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
paymentMethodSummary
required
Any of:
discriminator: kind
object
kind
required
string
Allowed value: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/

Headers

Section titled “Headers”
request-id
required
string

Identifies this request. Quote it when you contact support.

Idempotent-Replayed
string
Allowed value: true

true when this response replays the stored result of an earlier request with the same Idempotency-Key.