Pagos

Crear un pago

POST

/v1/payments

const url = 'https://api.timbro.do/v1/payments';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"paymentReference":"order-123","amount":{"currency":"DOP","value":"1250.00"},"description":"Servicio de mantenimiento","returnUrl":"https://merchant.example/orders/123"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.timbro.do/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "paymentReference": "order-123", "amount": { "currency": "DOP", "value": "1250.00" }, "description": "Servicio de mantenimiento", "returnUrl": "https://merchant.example/orders/123" }'

Crea un pago y devuelve el Payment vigente y la siguiente acción del cliente. paymentReference identifica una solicitud inmutable dentro del comercio y del modo, Prueba o En vivo. Repetir la misma referencia y los mismos datos recupera ese pago, incluso después de un resultado terminal y antes de aplicar nuevos valores predeterminados. Cambiar los datos bajo esa referencia devuelve HTTP 409.

Un intento rechazado no termina el pago: el Payment vuelve a status: "requires_customer_action" con lastDecline y se entrega un evento payment.declined. El cliente puede intentarlo de nuevo hasta que el pago venza. Un resultado incierto del adquirente devuelve 201 con status: "verifying".

saleReference es una etiqueta comercial opcional que puedes repetir. Idempotency-Key es opcional: si lo omites, la referencia proporciona una clave estable. Si lo envías, conserva la misma clave y solicitud para reintentar; cambiar la intención bajo esa clave devuelve 409.

Autenticación

secretKey
integrationToken
payments:test
integrationToken
payments:live

Parámetros

Parámetros de cabecera

idempotency-key

string

>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Clave de idempotencia opcional para repetir esta solicitud. Si la omites, Timbro usa una clave basada en paymentReference. Usa solo caracteres ASCII imprimibles.

Cuerpo de la solicitud^obligatorio

Cobra por monto, con artículos o por factura. El monto incluye el impuesto: para cobrar por monto, configura el impuesto o envía tax.includedAmount. Con artículos, Timbro calcula los totales. Por factura, envía solo invoicing con el invoiceId de una factura aceptada; el monto y los artículos salen de ella (cobrar una factura).

application/json

Ejemplo

{
  "paymentReference": "order-123",
  "amount": {
    "currency": "DOP",
    "value": "1250.00"
  },
  "description": "Servicio de mantenimiento",
  "returnUrl": "https://merchant.example/orders/123"
}

object

paymentReference

obligatorio

Referencia única para este pago. Para repetir la solicitud, usa la misma referencia y los mismos datos.

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})?$/

description

obligatorio

string

>= 1 characters <= 80 characters

Campos opcionales

returnUrl

Página del comercio que el cliente puede abrir al salir de Checkout. Omítela para pagos por QR o en punto de venta.

string format: uri

<= 2048 characters /^https?:///

serviceLabel

Texto de contexto para el pago, como Mesa 12.

string

<= 24 characters

expiresAfterSeconds

Segundos que Checkout permanece abierto, de 300 (5 minutos) a 86400 (24 horas). Si omites este campo, Checkout queda abierto 1800 segundos con returnUrl y 3600 sin él. Renovar un pago dividido vencido lo reabre como máximo por este tiempo, nunca más de 1800. Forma parte de la identidad de la solicitud.

integer

>= 300 <= 86400

checkoutDisplay

object

mode

obligatorio

string

Valores permitidos: itemized grouped amount_only

metadata

Tus datos de referencia, guardados con el pago y eliminados con él. Hasta 20 claves, de 1 a 40 caracteres, con valores de texto de hasta 500 caracteres. Timbro no usa estos datos para procesar el pago ni los envía al adquirente, al cliente o en los webhooks. No incluyas datos personales ni de tarjeta.

object

<= 20 properties

key

propiedades adicionales

string

<= 500 characters

merchantAccountId

Afiliación (cuenta de comercio) que quieres usar. Si la omites, Timbro elige la afiliación.

string

/^merchant_account_[0-9a-hjkmnp-tv-z]{24,}$/

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bancos que este pago ofrece como alternativa, entre los que adoptó la política de Checkout. Una lista vacía no ofrece ninguno; omítela para seguir la política.

Array

<= 2 items unique items

paymentPage

Solo en modo de prueba. Con true, tu cliente paga en la página del adquirente de la afiliación que la habilitó (Azul Payment Page o Botón de Pago de CardNet), en lugar del formulario de tarjeta de Checkout. Esa página pasa a ser el único método de pago, por lo que no puedes combinarla con división de pagos, propinas, billeteras ni bancos. Omite el campo o envía false para usar los métodos de Checkout.

boolean

testOptions

object

threeDs

boolean

source

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

object

obligatorio

string

>= 1 characters <= 256 characters

version

obligatorio

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 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})?$/

Ejemplo

{
  "paymentReference": "order-124",
  "currency": "DOP",
  "items": [
    {
      "description": "Servicio de mantenimiento",
      "unitPrice": "1180.00",
      "tax": {
        "kind": "itbis_18",
        "included": true
      }
    }
  ]
}

object

paymentReference

obligatorio

Referencia única para este pago. Para repetir la solicitud, usa la misma referencia y los mismos datos.

string

>= 1 characters <= 128 characters

currency

obligatorio

Ejemplo

DOP

string

/^[A-Z]{3}$/

items

obligatorio

Array<object>

>= 1 items

object

description

obligatorio

string

>= 1 characters <= 80 characters

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

string

>= 1 characters <= 128 characters

product

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

object

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

quantity

string

/^(?=[0-9.]*[1-9])[0-9]{1,16}(\.[0-9]{1,2})?$/

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
string

string

Valor permitido: good

legalTip

object

applied

obligatorio

boolean

group

string

>= 1 characters <= 64 characters

Campos opcionales

returnUrl

Página del comercio que el cliente puede abrir al salir de Checkout. Omítela para pagos por QR o en punto de venta.

string format: uri

<= 2048 characters /^https?:///

serviceLabel

Texto de contexto para el pago, como Mesa 12.

string

<= 24 characters

expiresAfterSeconds

integer

>= 300 <= 86400

checkoutDisplay

object

mode

obligatorio

string

Valores permitidos: itemized grouped amount_only

metadata

object

<= 20 properties

key

propiedades adicionales

string

<= 500 characters

merchantAccountId

Afiliación (cuenta de comercio) que quieres usar. Si la omites, Timbro elige la afiliación.

string

/^merchant_account_[0-9a-hjkmnp-tv-z]{24,}$/

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bancos que este pago ofrece como alternativa, entre los que adoptó la política de Checkout. Una lista vacía no ofrece ninguno; omítela para seguir la política.

Array

<= 2 items unique items

paymentPage

boolean

testOptions

object

threeDs

boolean

source

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

object

obligatorio

string

>= 1 characters <= 256 characters

version

obligatorio

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 characters

invoicing

discriminator: mode

object

type

obligatorio

string

Valores permitidos: E31 E32 E45

mode

obligatorio

string

Valor permitido: automatic

buyer

Cualquiera de:

object

kind

obligatorio

string

Valor permitido: anonymous

recipientEmail

Correo del comprador al que se entrega la factura una vez emitida.

string format: email

<= 254 characters

allowedTypes

Array<string>

>= 1 items

Valores permitidos: E31 E32 E45

isTypeLocked

boolean

isBuyerLocked

boolean

governmentEligibility

Cualquiera de:

object

entityKind

obligatorio

string

Valor permitido: central_government

authorityReference

obligatorio

string

>= 1 characters <= 128 characters

invoiceReference

string

>= 1 characters <= 128 characters

object

mode

obligatorio

string

Valor permitido: existing

invoiceId

obligatorio

string format: uuid

receipt

Acceso a la factura compartida de una factura que emitió una integración independiente. Mantén el token en privado.

object

obligatorio

string format: uuid

accessToken

obligatorio

string

>= 43 characters <= 43 characters /^[A-Za-z0-9_-]{43}$/

recipientEmail

Correo del comprador al que se entrega la factura. No se acepta junto con receipt: las facturas que emitió una integración independiente las entrega esa integración.

string format: email

<= 254 characters

expectedTotals

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})?$/

Cobra el total a pagar de una factura aceptada a partir de su id. El pago toma de la factura la venta, la moneda y los totales. Para cobrar un abono, envía CreateInvoicePartPaymentRequest con un amount. Puedes cobrar una factura completa con un solo pago o en abonos con varios pagos, nunca de las dos formas a la vez.

Ejemplo

{
  "paymentReference": "order-125",
  "invoicing": {
    "mode": "existing",
    "invoiceId": "f35b7ae4-c484-4c63-981e-4f0f15e913b5"
  }
}

object

paymentReference

obligatorio

Referencia única para este pago. Para repetir la solicitud, usa la misma referencia y los mismos datos.

string

>= 1 characters <= 128 characters

invoicing

obligatorio

object

mode

obligatorio

string

Valor permitido: existing

invoiceId

obligatorio

string format: uuid

receipt

Acceso a la factura compartida de una factura que emitió una integración independiente. Mantén el token en privado.

object

obligatorio

string format: uuid

accessToken

obligatorio

string

>= 43 characters <= 43 characters /^[A-Za-z0-9_-]{43}$/

recipientEmail

Correo del comprador al que se entrega la factura. No se acepta junto con receipt: las facturas que emitió una integración independiente las entrega esa integración.

string format: email

<= 254 characters

Campos opcionales

returnUrl

Página del comercio que el cliente puede abrir al salir de Checkout. Omítela para pagos por QR o en punto de venta.

string format: uri

<= 2048 characters /^https?:///

serviceLabel

Texto de contexto para el pago, como Mesa 12.

string

<= 24 characters

expiresAfterSeconds

integer

>= 300 <= 86400

metadata

object

<= 20 properties

key

propiedades adicionales

string

<= 500 characters

merchantAccountId

Afiliación (cuenta de comercio) que quieres usar. Si la omites, Timbro elige la afiliación.

string

/^merchant_account_[0-9a-hjkmnp-tv-z]{24,}$/

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bancos que este pago ofrece como alternativa, entre los que adoptó la política de Checkout. Una lista vacía no ofrece ninguno; omítela para seguir la política.

Array

<= 2 items unique items

paymentPage

boolean

testOptions

object

threeDs

boolean

source

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

object

obligatorio

string

>= 1 characters <= 256 characters

version

obligatorio

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 characters

Cobra un abono a una factura aceptada a partir de su id. El pago cobra solo amount, sin líneas propias, y queda vinculado a la factura.

Ejemplo

{
  "paymentReference": "order-123",
  "amount": {
    "currency": "DOP",
    "value": "1250.00"
  },
  "description": "Servicio de mantenimiento",
  "returnUrl": "https://merchant.example/orders/123"
}

object

paymentReference

obligatorio

Referencia única para este pago. Para repetir la solicitud, usa la misma referencia y los mismos datos.

string

>= 1 characters <= 128 characters

invoicing

obligatorio

La factura aceptada a la que se aplica un abono. Un abono nunca envía la factura por correo y solo cobra facturas emitidas por el propio negocio, así que no acepta recipientEmail ni receipt.

object

mode

obligatorio

string

Valor permitido: existing

invoiceId

obligatorio

string format: uuid

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})?$/

Campos opcionales

returnUrl

Página del comercio que el cliente puede abrir al salir de Checkout. Omítela para pagos por QR o en punto de venta.

string format: uri

<= 2048 characters /^https?:///

serviceLabel

Texto de contexto para el pago, como Mesa 12.

string

<= 24 characters

expiresAfterSeconds

integer

>= 300 <= 86400

metadata

object

<= 20 properties

key

propiedades adicionales

string

<= 500 characters

merchantAccountId

Afiliación (cuenta de comercio) que quieres usar. Si la omites, Timbro elige la afiliación.

string

/^merchant_account_[0-9a-hjkmnp-tv-z]{24,}$/

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bancos que este pago ofrece como alternativa, entre los que adoptó la política de Checkout. Una lista vacía no ofrece ninguno; omítela para seguir la política.

Array

<= 2 items unique items

paymentPage

boolean

testOptions

object

threeDs

boolean

source

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

object

obligatorio

string

>= 1 characters <= 256 characters

version

obligatorio

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 characters

tax

ITBIS incluido en el amount de un abono. Si lo omites, Timbro le asigna al abono la porción del ITBIS de la factura que corresponde a su monto, redondeada al centavo (medio centavo se redondea hacia arriba). Si los demás abonos también usaron esa porción, el abono que completa el total lleva el ITBIS que queda. El ITBIS de un abono no puede ser mayor que su monto ni que el ITBIS de la factura que los otros abonos todavía no cubren.

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})?$/

description

Descripción de un abono. Si la omites, Timbro usa Factura <e-NCF>.

string

>= 1 characters <= 80 characters

Respuestas

200

Una solicitud de pago del comercio.

application/json

Campos y códigos de la respuesta

Una solicitud de pago del comercio.

object

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

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
object

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:

PaymentDecline
null

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:

PaymentProblem
null

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:

string
null

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

string format: uuid

invoicing

obligatorio

Cualquiera de:

PaymentInvoicing
null

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
null

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:

Verification
null

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:

PaymentMethodSummary
null

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
null

string format: date-time

createdAt

obligatorio

string format: date-time

updatedAt

obligatorio

string format: date-time

sale

obligatorio

discriminator: kind

ItemizedSale
AmountOnlySale

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

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

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

kind

Cualquiera de:

string
string

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
null

string format: date-time

split

obligatorio

Cualquiera de:

MerchantSplit
null

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:

PaymentDecline
null

object

code

obligatorio

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

string

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:

PaymentMethodSummary
null

discriminator: kind

object

kind

obligatorio

string

Valor permitido: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

refundable

obligatorio

Cualquiera de:

object
null

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:

Money
null

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
null

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})?$/

Campos opcionales

subscriptionId

Suscripción a la que pertenece este período

string

/^sub_[0-9a-hjkmnp-tv-z]{24,}$/

initiator

Cualquiera de:

string
string

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

RedirectToUrlAction

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
string

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

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:

PaymentMethodSummary
null

discriminator: kind

object

kind

obligatorio

string

Valor permitido: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

Cabeceras

request-id

obligatorio

string

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

Idempotent-Replayed

string

Valor permitido: true

true cuando esta respuesta repite el resultado guardado de una solicitud anterior con la misma clave de idempotencia (Idempotency-Key).

201

Una solicitud de pago del comercio.

application/json

Campos y códigos de la respuesta

Una solicitud de pago del comercio.

object

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

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

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
object

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:

PaymentDecline
null

object

code

obligatorio

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

string

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:

PaymentProblem
null

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:

string
null

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

string format: uuid

invoicing

obligatorio

Cualquiera de:

PaymentInvoicing
null

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
null

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>

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:

Verification
null

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:

PaymentMethodSummary
null

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
null

string format: date-time

createdAt

obligatorio

string format: date-time

updatedAt

obligatorio

string format: date-time

sale

obligatorio

discriminator: kind

ItemizedSale
AmountOnlySale

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

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

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

kind

Cualquiera de:

string
string

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
null

string format: date-time

split

obligatorio

Cualquiera de:

MerchantSplit
null

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:

PaymentDecline
null

object

code

obligatorio

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

string

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:

PaymentMethodSummary
null

discriminator: kind

object

kind

obligatorio

string

Valor permitido: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

refundable

obligatorio

Cualquiera de:

object
null

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:

Money
null

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
null

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})?$/

Campos opcionales

subscriptionId

Suscripción a la que pertenece este período

string

/^sub_[0-9a-hjkmnp-tv-z]{24,}$/

initiator

Cualquiera de:

string
string

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

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

RedirectToUrlAction

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
string

string

Valor permitido: popular

processingReason

string

Valor permitido: awaiting_company_approval

metadata

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

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:

PaymentMethodSummary
null

discriminator: kind

object

kind

obligatorio

string

Valor permitido: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

Cabeceras

request-id

obligatorio

string

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

Idempotent-Replayed

string

Valor permitido: true

true cuando esta respuesta repite el resultado guardado de una solicitud anterior con la misma clave de idempotencia (Idempotency-Key).

400

No se pudo entender la solicitud.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "No se pudo entender la solicitud.",
  "status": 400,
  "code": "parameter_missing",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: parameter_missing parameter_invalid currency_not_supported fiscal_buyer_tax_id_invalid request_body_malformed payment_reference_invalid payment_tax_required payment_tax_invalid payment_items_invalid payment_totals_mismatch payment_invoice_item_fields_required

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 400

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

401

La credencial falta, tiene un formato incorrecto o ya no es válida.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La credencial falta, tiene un formato incorrecto o ya no es válida.",
  "status": 401,
  "code": "api_key_missing",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: api_key_missing api_key_invalid integration_token_invalid checkout_token_invalid checkout_token_expired

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 401

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

403

La credencial es válida, pero no tiene permiso para realizar esta operación.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La credencial es válida, pero no tiene permiso para realizar esta operación.",
  "status": 403,
  "code": "operation_not_permitted",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: operation_not_permitted

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 403

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

404

Ningún endpoint sirve este método y ruta, o no existe un recurso con este identificador dentro del alcance del solicitante.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "Ningún endpoint sirve este método y ruta, o no existe un recurso con este identificador dentro del alcance del solicitante.",
  "status": 404,
  "code": "payment_not_found",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: payment_not_found

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 404

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

409

La solicitud entra en conflicto con el estado actual del recurso o con una solicitud anterior que usó la misma clave de idempotencia (Idempotency-Key).

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La solicitud entra en conflicto con el estado actual del recurso o con una solicitud anterior que usó la misma clave de idempotencia (`Idempotency-Key`).",
  "status": 409,
  "code": "business_fiscal_setup_incomplete",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: business_fiscal_setup_incomplete payment_reference_conflict idempotency_key_reused idempotency_request_in_progress idempotency_key_expired source_identity_conflict payment_invoice_not_allowed

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 409

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

Retry-After

string

/^[0-9]+$/

Segundos que debes esperar antes de repetir esta solicitud o volver a consultar el recurso.

413

El cuerpo de la solicitud es más grande de lo que acepta este endpoint.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "El cuerpo de la solicitud es más grande de lo que acepta este endpoint.",
  "status": 413,
  "code": "request_body_too_large",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: request_body_too_large

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 413

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

415

El cuerpo de la solicitud tiene un tipo de contenido que este endpoint no acepta.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "El cuerpo de la solicitud tiene un tipo de contenido que este endpoint no acepta.",
  "status": 415,
  "code": "unsupported_media_type",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: unsupported_media_type

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 415

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

422

La solicitud tiene un formato válido, pero no se puede ejecutar.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La solicitud tiene un formato válido, pero no se puede ejecutar.",
  "status": 422,
  "code": "merchant_account_not_ready",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: merchant_account_not_ready merchant_checkout_policy_invalid merchant_profile_incomplete payment_description_required sale_amount_invalid 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_government_eligibility_required fiscal_government_eligibility_not_allowed taxpayer_unregistered taxpayer_inactive

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 422

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

500

La solicitud no pudo completarse. Recupera el resultado con la referencia guardada o repite la solicitud con la misma clave de idempotencia.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "La solicitud no pudo completarse. Recupera el resultado con la referencia guardada o repite la solicitud con la misma clave de idempotencia.",
  "status": 500,
  "code": "internal_error",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: internal_error

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 500

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

503

Un servicio requerido no está disponible temporalmente. Inténtalo de nuevo con la misma referencia o la misma clave de idempotencia.

application/problem+json

Ejemplo

{
  "type": "about:blank",
  "title": "Un servicio requerido no está disponible temporalmente. Inténtalo de nuevo con la misma referencia o la misma clave de idempotencia.",
  "status": 503,
  "code": "business_fiscal_binding_unavailable",
  "requestId": "request_000000000000000000000001"
}

Campos y códigos de la respuesta

Detalles de problema RFC 9457. Cada fallo de esta API es uno de estos objetos y cada operación limita code al subconjunto que puede emitir.

object

code

obligatorio

Código estable legible por máquinas. Toma decisiones con este código, nunca con title.

string

Valores permitidos: business_fiscal_binding_unavailable business_fiscal_setup_unavailable integration_authorization_unavailable payments_contract_migration_required merchant_payments_api_paused taxpayer_directory_unavailable

requestId

obligatorio

string

status

obligatorio

integer format: int32

>= 400 <= 599

Valor permitido: 503

title

obligatorio

string

type

obligatorio

string

Valores permitidos: about:blank

Campos opcionales

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>

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

Cabeceras

request-id

obligatorio

string

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

Retry-After

string

/^[0-9]+$/

Segundos que debes esperar antes de repetir esta solicitud o volver a consultar el recurso.

Crear un pago

Autenticación

Parámetros

Parámetros de cabecera

Cuerpo de la solicitudobligatorio

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Respuestas

200

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Cabeceras

201

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Ejemplo

Cabeceras

400

Ejemplo

Cabeceras

401

Ejemplo

Cabeceras

403

Ejemplo

Cabeceras

404

Ejemplo

Cabeceras

409

Ejemplo

Cabeceras

413

Ejemplo

Cabeceras

415

Ejemplo

Cabeceras

422

Ejemplo

Cabeceras

500

Ejemplo

Cabeceras

503

Ejemplo

Cabeceras

Cuerpo de la solicitud^obligatorio