Reembolsos

Listar reembolsos

GET

/v1/refunds

const url = 'https://api.timbro.do/v1/refunds?limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

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

Autenticación

secretKey
integrationToken
refunds:test
integrationToken
refunds:live

Parámetros

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.

paymentId

string

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

Filtra los reembolsos de un pago.

refundReference

string

>= 1 characters <= 128 characters

Devuelve solo el reembolso con exactamente este refundReference.

Respuestas

200

Una página de reembolsos, del más reciente al más antiguo.

application/json

Campos y códigos de la respuesta

Una página de reembolsos, del más reciente al más antiguo.

object

object

obligatorio

string

Valor permitido: list

data

obligatorio

Array<object>

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

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

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:

Money
null

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:

Money
null

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

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
string

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
null

string format: date-time

nextRetryAt

obligatorio

Cualquiera de:

string
null

string format: date-time

message

string

>= 1 characters <= 500 characters

reasonCode

string

>= 1 characters <= 128 characters

invoiceId

obligatorio

Cualquiera de:

string
null

string format: uuid

webhookEvents

obligatorio

Array<object>

object

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

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

hasMore

obligatorio

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

boolean

nextCursor

obligatorio

Cualquiera de:

string
null

string

>= 1 characters

Cabeceras

request-id

obligatorio

string

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

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_invalid",
  "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_invalid collection_cursor_invalid

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>

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

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.

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": "integration_authorization_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: integration_authorization_unavailable payments_contract_migration_required merchant_payments_api_paused

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.