Ir al contenido
Documentación
Empieza gratis

Pagos

Listar pagos

GET
/v1/payments
curl --request GET \
  --url 'https://api.timbro.do/v1/payments?limit=20' \
  --header 'Authorization: Bearer <token>'

Devuelve los pagos más recientes primero con un cursor opaco determinista.

Autenticación

Sección titulada «Autenticación»

Parámetros

Sección titulada «Parámetros»

Parámetros de consulta

Sección titulada «Parámetros de consulta»
limit
integer
default: 20 >= 1 <= 100

Filas de una página.

cursor
string
>= 1 characters <= 512 characters

El nextCursor de la página anterior. Un cursor pertenece a la lista, el negocio, el modo y el conjunto de filtros que lo emitieron.

status
Array<string>
Valores permitidos: requires_customer_action processing partially_authorized authorized capturing partially_paid releasing verifying succeeded canceled expired

Repite el parámetro para incluir más de un estado.

paymentReference
string
>= 1 characters <= 128 characters

Devuelve solo el pago con exactamente este paymentReference.

saleReference
string
>= 1 characters <= 128 characters
invoiceId
string format: uuid

Devuelve solo los pagos que cobran esta factura, completa o en abonos.

createdAfter
string format: date-time
createdBefore
string format: date-time

Respuestas

Sección titulada «Respuestas»

200

Sección titulada «200»

Una página de pagos del comercio con montos decimales.

Media typeapplication/json
Campos y códigos de la respuesta

Una página de pagos del comercio con montos decimales.

object
object
obligatorio
string
Valor permitido: list
data
obligatorio
Array<object>
object
id
obligatorio

Identificador del pago. Opaco; no lo analices más allá del prefijo.

string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/
object
obligatorio
string
Valor permitido: payment
status
obligatorio

Solo succeeded, canceled y expired son terminales. Un intento rechazado devuelve el pago a requires_customer_action con lastDecline, así que el cliente puede intentarlo de nuevo hasta que el pago venza. partially_authorized significa que algunas partes tienen fondos retenidos, authorized que los fondos de todas las partes están retenidos y esperan que el organizador los capture, capturing que la captura está en curso y releasing que se están liberando los fondos retenidos. verifying es un estado real no terminal; no es un error ni un rechazo.

string
Valores permitidos: requires_customer_action processing partially_authorized authorized capturing partially_paid releasing verifying succeeded canceled expired
source
obligatorio

Referencia inmutable de la venta en el sistema de origen, que envía la integración del comercio.

object
id
obligatorio
string
>= 1 characters <= 256 characters
version
obligatorio
string
>= 1 characters <= 128 characters
saleReference
obligatorio

Referencia del comercio para buscar la venta. No cambia después de crear el pago, no tiene que ser única y no identifica los reintentos de la solicitud.

string
>= 1 characters <= 128 characters
checkoutDisplay
obligatorio

Presentación de Checkout, de solo lectura, armada a partir de la configuración del comercio.

object
mode
obligatorio
string
Valores permitidos: itemized grouped amount_only
locale
obligatorio

Idioma de la interfaz. La notación del importe y la moneda son independientes del idioma.

string
Valores permitidos: es en
merchant
obligatorio
object
legalName
obligatorio
string
>= 1 characters <= 256 characters
rnc
obligatorio
string
/^\d{9}$/
displayName
obligatorio
string
>= 1 characters <= 128 characters
supportPhone
obligatorio
string
>= 1 characters <= 32 characters
supportEmail
string format: email
<= 254 characters
permanentAddress
object
line1
obligatorio
string
>= 1 characters <= 160 characters
city
obligatorio
string
>= 1 characters <= 80 characters
countryCode
obligatorio
string
/^[A-Z]{2}$/
line2
string
>= 1 characters <= 160 characters
province
string
>= 1 characters <= 80 characters
postalCode
string
>= 1 characters <= 20 characters
deliveryPolicy
Cualquiera de:
object
kind
obligatorio
string
Valor permitido: not_offered
statementDescriptor
obligatorio
string
>= 1 characters <= 22 characters
fiscal
obligatorio
object
availableKinds
obligatorio
Array<object>
object
kind
obligatorio
string
Valores permitidos: consumer fiscal_credit government
isAvailable
obligatorio
boolean
buyerRequirement
obligatorio
string
Valores permitidos: none optional required
isLocked
obligatorio
boolean
serviceCharges
obligatorio
object
isPropinaApplicable
obligatorio
boolean
wallets
obligatorio
Array<string>
Valores permitidos: apple_pay google_pay
acceptedCardBrands

Marcas de tarjeta certificadas para la instantánea de la afiliación de este pago.

Array<string>
<= 3 items unique items
Valores permitidos: visa mastercard amex
threeDsPrograms

Programas 3-D Secure seleccionados para este pago, que no cambian después de crearlo. Una lista vacía significa que el pago con tarjeta no usa 3DS.

Array<string>
<= 3 items unique items
Valores permitidos: visa_secure mastercard_identity_check amex_safekey
checkoutReference
obligatorio

Identificador secreto e impredecible que da acceso al recibo completo cuando el pago termina. Tenerlo revela la identidad del comprador y el detalle; mantenlo privado.

string
/^checkout_[0-9a-hjkmnp-tv-z]{24,}$/
lastDecline
obligatorio
Cualquiera de:

El intento rechazado más reciente. Un rechazo termina el intento, no el pago; el cliente puede intentarlo de nuevo hasta que el pago venza. Se borra al enviar el siguiente intento, cancelar el pago o crear, reemplazar o renovar su división; se conserva al vencer.

object
code
obligatorio

Código de rechazo normalizado. Los códigos originales del adquirente no son públicos.

string
Valores permitidos: 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
obligatorio

Explicación segura para el cliente. La redacción puede cambiar.

string
attemptedAt
obligatorio

Momento en que Timbro registró el rechazo del adquirente para este intento.

string format: date-time
problem
obligatorio
Cualquiera de:

Pago aprobado cuya evidencia de liquidación necesita que el equipo de Timbro la resuelva. No retira la aprobación.

object
code
obligatorio

Clasificación normalizada de un problema de liquidación encontrado después de la aprobación.

string
Valores permitidos: settlement_amount_mismatch settlement_record_not_found settlement_amount_unverified
message
obligatorio
string
>= 1 characters <= 500 characters
invoiceId
obligatorio
Cualquiera de:

UUID canónico de la factura de Timbro cuando se admita.

string format: uuid
invoicing
obligatorio
Cualquiera de:

Instrucciones de factura guardadas y selección del destinatario. El ciclo de vida de la factura y las credenciales de acceso se informan por separado.

object
mode
obligatorio
Cualquiera de:
string
Valor permitido: automatic
type
obligatorio
string
Valores permitidos: E31 E32 E45
recipientEmail
obligatorio
Cualquiera de:
string format: email
<= 320 characters
issuanceProblem

Cuerpo de un problema RFC 9457 devuelto por la API /v1.

object
code
obligatorio
string
>= 1 characters
requestId
obligatorio
string
status
obligatorio
integer format: int32
>= 400 <= 599
title
obligatorio
string
type
obligatorio
string
Valores permitidos: about:blank
detail
string
invoiceId

Solo aparece si la solicitud rechazada produjo una operación fiscal.

string
issuanceBlockers

Solo aparece cuando las reglas oficiales de emisión rechazan la emisión.

Array<string>
Valores permitidos: 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

Solo aparece cuando el rechazo señala un valor incluido en la solicitud.

Array<object>

Un problema público estable del documento, guardado para una admisión rechazada.

object
code
obligatorio
string
message
obligatorio
string
path
obligatorio
string
buyer
discriminator: kind
object
kind
obligatorio
string
Valores permitidos: anonymous
governmentEligibility
Cualquiera de:
object
entityKind
obligatorio
string
Valor permitido: central_government
authorityReference
obligatorio
string
>= 1 characters <= 128 characters
allowedTypes
Array<string>
Valores permitidos: E31 E32 E45
isTypeLocked
boolean
isBuyerLocked
boolean
revision

Aumenta cada vez que cambian el tipo de comprobante, el comprador o la elegibilidad gubernamental.

integer
>= 1
invoiceReference
string
>= 1 characters <= 128 characters
verification
obligatorio
Cualquiera de:

Progreso de conciliación mientras el estado es verifying.

object
startedAt
obligatorio
string format: date-time
nextCheckAt
obligatorio
string format: date-time
isEscalated
obligatorio
boolean
paymentMethodSummary
obligatorio
Cualquiera de:
discriminator: kind
object
kind
obligatorio
string
Valor permitido: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
isLiveMode
obligatorio
boolean
expiresAt
obligatorio
Cualquiera de:
string format: date-time
createdAt
obligatorio
string format: date-time
updatedAt
obligatorio
string format: date-time
sale
obligatorio
discriminator: kind
object
kind
obligatorio
string
Valor permitido: itemized
reference
obligatorio
string
>= 1 characters <= 128 characters
currency
obligatorio
string
/^[A-Z]{3}$/
items
obligatorio
Array<object>
>= 1 items
object
id
obligatorio
string
>= 1 characters <= 128 characters
description
obligatorio
string
>= 1 characters <= 80 characters
quantity
obligatorio
string
/^(?=[0-9.]*[1-9])[0-9]{1,16}(\.[0-9]{1,2})?$/
unitPrice
obligatorio
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,4})?$/
tax
obligatorio
object
kind
obligatorio
Cualquiera de:
string
Valor permitido: itbis_18
included
obligatorio
boolean
product

Metadatos de presentación. Se excluyen del contenido fiscal canónico.

object
id
obligatorio
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
Valores permitidos: 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
Cualquiera de:
string
Valor permitido: good
legalTip
object
applied
obligatorio
boolean
group
string
>= 1 characters <= 64 characters
totals
obligatorio
object
net
obligatorio
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
tax
obligatorio
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
legalTip
obligatorio
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
total
obligatorio
string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
paymentReference
obligatorio

Identidad inmutable de la solicitud de pago dentro del comercio y del modo, Prueba o En vivo.

string
>= 1 characters <= 128 characters
amount
obligatorio

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Estado agregado de la división. captured es dinero liquidado; authorized, dinero retenido; releasing y released describen la liberación de la autorización.

string
Valores permitidos: open partially_authorized authorized capturing partially_paid releasing released succeeded expired
captured
obligatorio

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Estado de autorización y captura de una parte. authorized significa que los fondos están retenidos; succeeded, que esos fondos se capturaron.

string
Valores permitidos: unpaid processing authorized capturing releasing verifying succeeded released expired
lastDecline
obligatorio
Cualquiera de:

El intento rechazado más reciente. Un rechazo termina el intento, no el pago; el cliente puede intentarlo de nuevo hasta que el pago venza. Se borra al enviar el siguiente intento, cancelar el pago o crear, reemplazar o renovar su división; se conserva al vencer.

object
code
obligatorio

Código de rechazo normalizado. Los códigos originales del adquirente no son públicos.

string
Valores permitidos: 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
obligatorio

Explicación segura para el cliente. La redacción puede cambiar.

string
attemptedAt
obligatorio

Momento en que Timbro registró el rechazo del adquirente para este intento.

string format: date-time
paymentMethodSummary
obligatorio
Cualquiera de:
discriminator: kind
object
kind
obligatorio
string
Valor permitido: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
refundable
obligatorio
Cualquiera de:
object
amount
obligatorio

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
automaticAmount
obligatorio
Cualquiera de:

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

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

Suscripción a la que pertenece este período

string
/^sub_[0-9a-hjkmnp-tv-z]{24,}$/
initiator
Cualquiera de:
string
Valor permitido: customer
billingPeriod
object
start
obligatorio
string format: date-time
end
obligatorio
string format: date-time
returnUrl

Destino web del comercio que se ofrece al salir de Checkout. Consulta el estado del pago en la API.

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

Etiqueta de contexto escrita por el comercio, como Mesa 12.

string
<= 24 characters
description

Descripción breve del producto o servicio que se compra.

string
>= 1 characters <= 80 characters
breakdown

Composición monetaria calculada por el servidor. La invariante es payableTotalMinorUnits = fiscalDeclaredTotalMinorUnits + nonBillableMinorUnits; las propinas legales y voluntarias nunca se cuentan dos veces.

object
taxableBases
obligatorio
Array<object>
object
taxTreatment
obligatorio
string
Valores permitidos: itbis_18 itbis_16 zero_rated
baseMinorUnits
obligatorio
integer
taxMinorUnits
obligatorio
integer
exemptMinorUnits
obligatorio
integer
nonBillableMinorUnits
obligatorio
integer
serviceCharges
obligatorio
Array<object>
object
kind
obligatorio
string
Valores permitidos: propina_legal
minorUnits
obligatorio
integer
taxesMinorUnits
obligatorio
integer
fiscalDeclaredTotalMinorUnits
obligatorio

Total fiscal declarado: bases imponibles, impuestos, líneas exentas y propina legal. Las líneas no facturables se excluyen.

integer
payableTotalMinorUnits
obligatorio

Total comercial por cobrar: fiscalDeclaredTotalMinorUnits más nonBillableMinorUnits. Es el importe cobrado antes de una propina voluntaria.

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

Envía al cliente a Checkout.

object
kind
obligatorio
string
Valor permitido: redirect_to_url
url
obligatorio

Ábrelo en un contexto de navegación de nivel superior.

string format: uri
expiresAt
obligatorio
string format: date-time
paymentChannel
object
kind
obligatorio
string
Valor permitido: bank_checkout
bank
obligatorio
Cualquiera de:
string
Valor permitido: popular
processingReason
string
Valor permitido: awaiting_company_approval
metadata

Claves del comercio que acompañan este pago: como máximo 20 claves de 1 a 40 caracteres, cada una con un string de hasta 500 caracteres. Timbro las guarda de forma opaca, nunca toma decisiones con ellas, nunca las envía a un adquirente ni las repite en el cuerpo de un webhook o en una proyección para el cliente. Viven lo mismo que su pago y se eliminan con él. Nunca incluyas datos personales ni datos de tarjeta.

object
<= 20 properties
key
propiedades adicionales
string
<= 500 characters
tax
object
includedAmount
obligatorio

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
provenance
obligatorio
Cualquiera de:
string
Valor permitido: explicit
policyRevision
integer
capturedPayment
object
allocations
obligatorio
Array<object>
>= 1 items
object
id
obligatorio

Identificador estable de una asignación de pago capturada.

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

Monto monetario decimal exacto.

object
currency
obligatorio

Ejemplo

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

Monto decimal exacto y no negativo, con un máximo de dos cifras decimales.

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
paymentMethodSummary
obligatorio
Cualquiera de:
discriminator: kind
object
kind
obligatorio
string
Valor permitido: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
hasMore
obligatorio

Verdadero cuando existe otra página después de esta.

boolean
nextCursor
obligatorio
Cualquiera de:
string
>= 1 characters

Cabeceras

Sección titulada «Cabeceras»
request-id
obligatorio
string

Identifica esta solicitud. Indícalo cuando contactes a soporte.