Skip to content
Documentation
Get started

Refunds

List refunds

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

Authentication

Section titled “Authentication”

Parameters

Section titled “Parameters”

Query parameters

Section titled “Query parameters”
limit
integer
default: 20 >= 1 <= 100

Rows on one page.

cursor
string
>= 1 characters <= 512 characters

The nextCursor of the previous page. A cursor belongs to the list, tenant, mode, and filter set that minted it.

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

Filter refunds for one Payment.

refundReference
string
>= 1 characters <= 128 characters

Return only the Refund with exactly this refundReference.

Responses

Section titled “Responses”

200

Section titled “200”

One page of Refunds, newest first.

Media typeapplication/json
Response fields and codes

One page of Refunds, newest first.

object
object
required
string
Allowed value: list
data
required
Array<object>

A durable full or partial refund request. Provider money movement and fiscal note coordination are independent state machines.

object
id
required

Refund identifier.

string
/^refund_[0-9a-hjkmnp-tv-z]{24,}$/
object
required
string
Allowed value: refund
paymentId
required

Payment whose captured money is being returned.

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

Immutable commercial source coordinate supplied by the merchant adapter.

object
id
required
string
>= 1 characters <= 256 characters
version
required
string
>= 1 characters <= 128 characters
refundReference
required

Immutable Refund identity within this merchant and TEST/LIVE mode.

string
>= 1 characters <= 128 characters
amount
required

An exact decimal monetary amount.

object
currency
required

Example

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

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

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

Exact returned ITBIS, never inferred proportionally. A full original refund uses captured tax when omitted.

object
currency
required

Example

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

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

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

Exact voluntary-tip portion of the refund’s returned money, excluded from the fiscal credit-note amount.

object
currency
required

Example

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

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

string
/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/
allocationIds
required
Array<string>
allocationAmounts
required
Array<object>
object
id
required

Captured allocation attributed to this refund.

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

An exact decimal monetary amount.

object
currency
required

Example

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

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

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

Refund lifecycle. verifying means the provider outcome is ambiguous and is being recovered without resubmitting the refund.

string
Allowed values: processing succeeded declined verifying operator_required
providerOutcome
required

Provider outcome kept separate from fiscal credit-note coordination. Provider-specific references are not exposed.

object
status
required
string
Allowed values: not_attempted pending succeeded declined unknown operator_required
lastAttemptAt
required
Any of:
string format: date-time
nextRetryAt
required
Any of:
string format: date-time
message
string
>= 1 characters <= 500 characters
reasonCode
string
>= 1 characters <= 128 characters
invoiceId
required
Any of:
string format: uuid
webhookEvents
required
Array<object>
object
id
required

Webhook event identifier related to this Refund.

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

Merchant label retained from the original refund request.

string
>= 1 characters <= 128 characters
completedAt
string format: date-time
decline
object
code
required
string
Allowed value: refund_declined
canTryAgain
required
boolean
message
required
string
>= 1 characters <= 256 characters
problem
object
code
required

Normalized classification of an unresolved refund.

string
Allowed values: provider_refund_capability_not_qualified refund_recovery_exhausted refund_provider_reference_unavailable refund_provider_credentials_rejected
message
required
string
>= 1 characters <= 256 characters
hasMore
required

True when a further page follows this one.

boolean
nextCursor
required
Any of:
string
>= 1 characters

Headers

Section titled “Headers”
request-id
required
string

Identifies this request. Quote it when you contact support.