Ir al contenido
Documentación
Empieza gratis

Reembolsos

Crear un reembolso

POST
/v1/refunds
curl --request POST \
  --url https://api.timbro.do/v1/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "paymentId": "example", "source": { "id": "example", "version": "example" }, "refundReference": "example", "amount": { "currency": "DOP", "value": "example" }, "taxAmount": { "currency": "DOP", "value": "example" }, "voluntaryTipAmount": { "currency": "DOP", "value": "example" }, "allocationIds": [ "example" ] }'

Solicita el reembolso de dinero capturado por un pago. refundReference identifica el reembolso dentro del comercio y del modo. Repetir la misma referencia y los mismos datos devuelve el reembolso vigente; cambiar los datos genera un conflicto. Si omites amount, se reserva una sola vez el saldo capturado restante de las asignaciones seleccionadas. Timbro guarda a qué asignaciones corresponde el reembolso antes de enviarlo al adquirente.

voluntaryTipAmount indica la parte de propina voluntaria que reembolsas. En un reembolso parcial, omitirla declara cero; al reembolsar todo el saldo restante, se incluye la propina restante. Cada parte debe caber en su saldo capturado. La propina voluntaria no forma parte del monto de la nota de crédito.

Un reembolso mueve dinero sin intervención del equipo de Timbro solo cuando reembolsa el monto capturado completo de un pago de tarjeta DOP, sin división, en modo de prueba y sin reembolsos anteriores, salvo los rechazados. Azul usa las credenciales e impuesto de la captura original, una referencia de reembolso única y la consulta VerifyPayment. CardNet reembolsa la captura Ztrans con la credencial de reembolso activa de la afiliación. Un pago de venta Azul DOP en modo de prueba también puede admitir un reembolso parcial con ITBIS exacto en taxAmount, dentro de refundable.automaticPartial. El impuesto queda ligado a la solicitud y no se estima como una proporción. Los reembolsos parciales de capturas de autorización o por CardNet, los parciales sin impuesto exacto y los de pagos divididos, en vivo, con Apple Pay o Google Pay y simulados se crean en operator_required antes de mover dinero con el adquirente. Consulta refundable.automaticAmount para el monto completo y refundable.automaticPartial para los límites parciales. Un reembolso enviado todavía puede terminar en declined o operator_required.

Un reembolso no emite una nota de crédito: asocia por separado la factura E34 aceptada. source es opcional para coordinar con un ERP; su id y versión no pueden identificar otro reembolso. Si omites Idempotency-Key, la referencia proporciona una clave estable; si lo envías, repítelo en los reintentos. Consulta el reembolso para confirmar el resultado.

Autenticación

Sección titulada «Autenticación»

Parámetros

Sección titulada «Parámetros»

Parámetros de cabecera

Sección titulada «Parámetros de cabecera»
idempotency-key
string
>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Cuerpo de la solicitudobligatorio

Sección titulada «Cuerpo de la solicitudobligatorio»
Media typeapplication/json

Crea un reembolso total cuando el importe equivale al saldo capturado restante, o un reembolso parcial cuando es menor.

object
paymentId
obligatorio

Pago con dinero capturado que quieres reembolsar.

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

Identidad estable del reembolso. Repetir la misma intención devuelve el recurso vigente; cambiar la intención genera un conflicto.

string
>= 1 characters <= 128 characters
Campos opcionales
source

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
amount

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

ITBIS exacto reembolsado, sin estimar una proporción. Si lo omites al reembolsar el pago original completo, Timbro usa el impuesto capturado.

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

Parte exacta de propina voluntaria devuelta en el reembolso. No forma parte del importe de la nota de crédito fiscal.

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})?$/
allocationIds
Array<string>
>= 1 items <= 100 items

Respuestas

Sección titulada «Respuestas»

200

Sección titulada «200»

Solicitud de reembolso total o parcial. El movimiento de dinero con el adquirente y la coordinación de la nota de crédito son máquinas de estado independientes.

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

Solicitud de reembolso total o parcial. El movimiento de dinero con el adquirente y la coordinación de la nota de crédito son máquinas de estado independientes.

object
id
obligatorio

Identificador del reembolso.

string
/^refund_[0-9a-hjkmnp-tv-z]{24,}$/
object
obligatorio
string
Valor permitido: refund
paymentId
obligatorio

Pago cuyo dinero capturado se está reembolsando.

string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/
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
refundReference
obligatorio

Identidad inmutable del reembolso dentro de este comercio y 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})?$/
taxAmount
obligatorio
Cualquiera de:

ITBIS exacto reembolsado, sin estimar una proporción. Si lo omites al reembolsar el pago original completo, Timbro usa el impuesto capturado.

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})?$/
voluntaryTipAmount
obligatorio
Cualquiera de:

Parte exacta de propina voluntaria devuelta en el reembolso. No forma parte del importe de la nota de crédito fiscal.

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})?$/
allocationIds
obligatorio
Array<string>
allocationAmounts
obligatorio
Array<object>
object
id
obligatorio

Asignación capturada atribuida a este reembolso.

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})?$/
kind
obligatorio
Cualquiera de:
string
Valor permitido: partial
status
obligatorio

Ciclo de vida del reembolso. verifying significa que el resultado del adquirente es ambiguo y se está recuperando sin volver a enviar el reembolso.

string
Valores permitidos: processing succeeded declined verifying operator_required
providerOutcome
obligatorio

Resultado del adquirente, separado de la coordinación de la nota de crédito fiscal. Las referencias específicas del adquirente no se exponen.

object
status
obligatorio
string
Valores permitidos: not_attempted pending succeeded declined unknown operator_required
lastAttemptAt
obligatorio
Cualquiera de:
string format: date-time
nextRetryAt
obligatorio
Cualquiera de:
string format: date-time
message
string
>= 1 characters <= 500 characters
reasonCode
string
>= 1 characters <= 128 characters
invoiceId
obligatorio
Cualquiera de:
string format: uuid
webhookEvents
obligatorio
Array<object>
object
id
obligatorio

Identificador del evento de webhook relacionado con este reembolso.

string
/^event_[0-9a-hjkmnp-tv-z]{24,}$/
type
obligatorio
string
>= 1 characters <= 128 characters
createdAt
obligatorio
string format: date-time
updatedAt
obligatorio
string format: date-time
Campos opcionales
merchantReference

Etiqueta del comercio conservada de la solicitud original del reembolso.

string
>= 1 characters <= 128 characters
completedAt
string format: date-time
decline
object
code
obligatorio
string
Valor permitido: refund_declined
canTryAgain
obligatorio
boolean
message
obligatorio
string
>= 1 characters <= 256 characters
problem
object
code
obligatorio

Clasificación normalizada de un reembolso sin resolver.

string
Valores permitidos: provider_refund_capability_not_qualified refund_recovery_exhausted refund_provider_reference_unavailable refund_provider_credentials_rejected
message
obligatorio
string
>= 1 characters <= 256 characters

Cabeceras

Sección titulada «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).