Skip to content
TimbroTimbroTimbro

List payments

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

Returns newest payments first with a deterministic opaque cursor.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 20 >= 1 <= 100
cursor
string
>= 1 characters <= 512 characters
status
Any of:
string
Allowed value: requires_customer_action
saleReference
string
>= 1 characters <= 128 characters
merchantInvoiceNumber
string
>= 1 characters <= 20 characters
merchantOrderNumber
string
>= 1 characters <= 20 characters
createdAfter
string format: date-time
createdBefore
string format: date-time

Responses

Section titled “Responses”

200

Section titled “200”

Default Response

Media typeapplication/json
PaymentListPage
object
object
required
string
Allowed value: list
data
required
Array<object>
Payment

The one durable money object for one sale.

object
id
required

Payment identifier. Opaque; do not parse beyond the prefix.

string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/
object
required
string
Allowed value: payment
status
required

partially_authorized means some shares have reserved funds, authorized means every share is reserved and awaits the organizer's capture command, capturing means capture is running, and releasing means reserved funds are being released. verifying is a real, non-terminal status; it is not an error or decline.

string
Allowed values: requires_customer_action processing partially_authorized authorized capturing partially_paid releasing verifying succeeded declined canceled expired
amount
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
voluntaryTip
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
totalAmount
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
saleReference
required

Merchant-owned searchable business reference. It is immutable after create, need not be unique, and does not identify command retries.

string
>= 1 characters <= 128 characters
returnUrl

Merchant web destination offered after Checkout. Payment status must be retrieved from the API.

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

Merchant-authored context label such as Mesa 12.

string
<= 24 characters
description

Concise description of the product or service being purchased.

string
>= 1 characters <= 80 characters
breakdown
Breakdown

Server-computed money composition. The only totals a checkout page renders.

object
taxableBases
required
Array<object>
BreakdownTaxableBase
object
taxTreatment
required
string
Allowed values: itbis_18 itbis_16 zero_rated
baseMinorUnits
required
integer
taxMinorUnits
required
integer
exemptMinorUnits
required
integer
serviceCharges
required
Array<object>
BreakdownServiceCharge
object
kind
required
string
Allowed values: propina_legal
minorUnits
required
integer
taxesMinorUnits
required
integer
totalMinorUnits
required
integer
groups
Array<object>
BreakdownGroup
object
group
required
string
>= 1 characters <= 64 characters
subtotalMinorUnits
required
integer
checkoutDisplay
required
CheckoutDisplay

Read-only checkout presentation assembled from merchant configuration.

object
mode
required
string
Allowed values: itemized grouped amount_only
locale
required
string
>= 2 characters <= 16 characters
merchant
required
CheckoutDisplayMerchant
object
legalName
required
string
>= 1 characters <= 256 characters
rnc
required
string
/^\d{9}$/
displayName
required
string
>= 1 characters <= 128 characters
supportPhone
required
string
>= 1 characters <= 32 characters
supportEmail
string format: email
<= 254 characters
permanentAddress
CheckoutDisplayPermanentAddress
object
line1
required
string
>= 1 characters <= 160 characters
line2
string
>= 1 characters <= 160 characters
city
required
string
>= 1 characters <= 80 characters
province
string
>= 1 characters <= 80 characters
postalCode
string
>= 1 characters <= 20 characters
countryCode
required
string
/^[A-Z]{2}$/
deliveryPolicy
Any of:
object
kind
required
string
Allowed value: not_offered
statementDescriptor
required
string
>= 1 characters <= 22 characters
fiscal
required
CheckoutDisplayFiscal
object
availableKinds
required
Array<object>
FiscalAvailableKind
object
kind
required
string
Allowed values: consumer fiscal_credit government
isAvailable
required
boolean
buyerRequirement
required
string
Allowed values: none optional required
isLocked
required
boolean
serviceCharges
required
CheckoutDisplayServiceCharges
object
isPropinaApplicable
required
boolean
wallets
required
Array<string>
Allowed values: apple_pay google_pay
acceptedCardBrands

Card brands certified for this Payment's Merchant Account snapshot.

Array<string>
<= 3 items unique items
Allowed values: visa mastercard amex
threeDsPrograms

3-D Secure programs selected for this immutable Payment journey. An empty list means card submission does not use 3DS.

Array<string>
<= 3 items unique items
Allowed values: visa_secure mastercard_identity_check amex_safekey
checkoutReference
required

Unpredictable bearer handle for the full receipt projection after terminal payment. Possession reveals buyer identity and itemization; keep it private.

string
/^checkout_[0-9a-hjkmnp-tv-z]{24,}$/
nextAction
One of: discriminator: kind
RedirectToUrlAction

Send the customer to the hosted checkout page.

object
kind
required
string
Allowed value: redirect_to_url
url
required

Open in a top-level browsing context.

string format: uri
expiresAt
required
string format: date-time
decline
required
Any of:
Decline

Present only while status is declined.

object
code
required

Normalized decline code. Raw provider codes are not public.

string
Allowed values: 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 suspected_fraud do_not_honor issuer_unavailable generic_decline
canTryAgain
required
boolean
message
required

Customer-safe explanation. Wording may change.

string
fiscalDocument
required
Any of:
One of: discriminator: status
RequestedFiscalDocument
object
id
required

Fiscal document identifier.

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

Payment that requested the fiscal document.

string
/^payment_[0-9a-hjkmnp-tv-z]{24,}$/
kind
required
string
Allowed values: consumer fiscal_credit government
issuanceMode
required

Whether fiscal issuance is required before Checkout presents the purchase as complete or may finish after the paid receipt is shown.

string
Allowed values: required deferred
merchantInvoiceNumber
required
string
>= 1 characters <= 20 characters
merchantOrderNumber
required
string
>= 1 characters <= 20 characters /^[0-9]+$/
revision
required
integer
>= 1
buyer
FiscalBuyer
object
identityKind
required
string
Allowed values: domestic foreign
taxId
required
Any of:
string
/^\d{9}$|^\d{11}$/
foreignId
required
Any of:
string
>= 1 characters <= 20 characters /^[A-Za-z0-9][A-Za-z0-9._/-]{0,19}$/
legalName
required
string
>= 1 characters <= 256 characters
address
string
>= 1 characters <= 100 characters
contactName
string
>= 1 characters <= 80 characters
email
string format: email
<= 80 characters
governmentEligibility
Any of:
object
entityKind
required
string
Allowed value: central_government
authorityReference
required
string
>= 1 characters <= 128 characters
lines
required
Array<object>
>= 1 items
FiscalLine
object
sourceLineId
required
string
>= 1 characters <= 128 characters
description
required
string
>= 1 characters <= 80 characters
quantity
required
string
/^(?=[0-9.]*[1-9])[0-9]{1,16}(\.[0-9]{1,2})?$/
measurementUnit
required
string
Allowed values: unit kilogram litre metre piece
unitPriceMinorUnits
required
integer
itemKind
required
string
Allowed values: good service
taxTreatment
required
string
Allowed values: itbis_18 itbis_16 zero_rated exempt non_billable
isLegalTipApplicable
required

Whether this line belongs to the merchant's mandatory legal-tip base. Non-billable lines cannot be eligible.

boolean
group
string
>= 1 characters <= 64 characters
delivery
required
Any of:
One of: discriminator: status
WaitingFiscalDelivery
object
email
required
string format: email
<= 320 characters
status
required
string
Allowed value: waiting_for_document
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
status
required
string
Allowed value: requested
verification
required
Any of:
Verification

Reconciliation progress while status is verifying.

object
startedAt
required
string format: date-time
nextCheckAt
required
string format: date-time
isEscalated
required
boolean
paymentMethodSummary
required
Any of:
One of: discriminator: kind
CardPaymentMethodSummary
object
kind
required
string
Allowed value: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
split
required
Any of:
MerchantSplit
object
status
required
SplitStatus

Aggregate split state. captured is settled money; authorized is reserved money; releasing and released describe authorization release.

string
Allowed values: open partially_authorized authorized capturing partially_paid releasing released succeeded expired
captured
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
authorized
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
remainingToAuthorize
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
remainingToCapture
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
capturedCount
required
integer
<= 10
authorizedCount
required
integer
<= 10
partCount
required
integer
>= 2 <= 10
parts
required
Array<object>
>= 2 items <= 10 items
object
ordinal
required
integer
>= 1 <= 10
amount
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
allocatedItbis
required
Money

A monetary amount. Never a floating-point number.

object
currency
required

ISO 4217 alphabetic code.

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

Amount in base-10 minor units of currency. DOP and USD use two decimal places, so 125000 is 1,250.00.

integer
status
required
SplitPartStatus

Authorization and capture state for one share. authorized means funds are reserved; succeeded means the reservation was captured.

string
Allowed values: unpaid processing authorized capturing releasing verifying declined succeeded released expired
paymentMethodSummary
required
Any of:
One of: discriminator: kind
CardPaymentMethodSummary
object
kind
required
string
Allowed value: card
brand
string
>= 1 characters <= 32 characters
last4
string
/^\d{4}$/
isLiveMode
required
boolean
expiresAt
required
string format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
metadata
object
<= 20 properties
key
additional properties
string
<= 500 characters
hasMore
required
boolean
nextCursor
required
Any of:
string
>= 1 characters
Example
{
  "object": "list",
  "data": [
    {
      "object": "payment",
      "status": "requires_customer_action",
      "amount": {
        "currency": "DOP",
        "minorUnits": 125000
      },
      "voluntaryTip": {
        "currency": "DOP",
        "minorUnits": 125000
      },
      "totalAmount": {
        "currency": "DOP",
        "minorUnits": 125000
      },
      "breakdown": {
        "taxableBases": [
          {
            "taxTreatment": "itbis_18"
          }
        ],
        "serviceCharges": [
          {
            "kind": "propina_legal"
          }
        ]
      },
      "checkoutDisplay": {
        "mode": "itemized",
        "merchant": {
          "deliveryPolicy": {
            "kind": "not_offered"
          }
        },
        "fiscal": {
          "availableKinds": [
            {
              "kind": "consumer",
              "buyerRequirement": "none"
            }
          ]
        },
        "wallets": [
          "apple_pay"
        ],
        "acceptedCardBrands": [
          "visa"
        ],
        "threeDsPrograms": [
          "visa_secure"
        ]
      },
      "nextAction": {
        "kind": "redirect_to_url"
      },
      "decline": {
        "code": "insufficient_funds"
      },
      "fiscalDocument": {
        "object": "fiscal_document",
        "kind": "consumer",
        "issuanceMode": "required",
        "buyer": {
          "identityKind": "domestic"
        },
        "governmentEligibility": {
          "entityKind": "central_government"
        },
        "lines": [
          {
            "measurementUnit": "unit",
            "itemKind": "good",
            "taxTreatment": "itbis_18"
          }
        ],
        "delivery": {
          "status": "waiting_for_document"
        },
        "status": "requested"
      },
      "paymentMethodSummary": {
        "kind": "card"
      },
      "split": {
        "status": "open",
        "captured": {
          "currency": "DOP",
          "minorUnits": 125000
        },
        "authorized": {
          "currency": "DOP",
          "minorUnits": 125000
        },
        "remainingToAuthorize": {
          "currency": "DOP",
          "minorUnits": 125000
        },
        "remainingToCapture": {
          "currency": "DOP",
          "minorUnits": 125000
        },
        "parts": [
          {
            "amount": {
              "currency": "DOP",
              "minorUnits": 125000
            },
            "allocatedItbis": {
              "currency": "DOP",
              "minorUnits": 125000
            },
            "status": "unpaid",
            "paymentMethodSummary": {
              "kind": "card"
            }
          }
        ]
      }
    }
  ]
}

400

Section titled “400”

The request could not be understood or is not valid for this merchant account.

Media typeapplication/json
InvalidRequestError

The request could not be understood or is not valid for this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: parameter_missing parameter_invalid provider_not_available currency_not_supported amount_below_minimum amount_above_maximum checkout_reference_invalid checkout_reference_expired fiscal_buyer_tax_id_invalid fiscal_line_total_invalid fiscal_lines_required payment_split_invalid
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "parameter_missing"
  }
}

401

Section titled “401”

The credential is missing, malformed, or no longer valid.

Media typeapplication/json
AuthenticationError

The credential is missing, malformed, or no longer valid.

object
error
required
object
type
required
string
Allowed value: authentication_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: api_key_missing api_key_invalid checkout_token_invalid checkout_token_expired
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_missing"
  }
}

403

Section titled “403”

The credential is valid but not permitted to perform this operation on this resource.

Media typeapplication/json
PermissionError

The credential is valid but not permitted to perform this operation on this resource.

object
error
required
object
type
required
string
Allowed value: permission_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: merchant_account_not_owned merchant_account_admin_required operation_not_permitted_for_checkout_token live_mode_not_enabled
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "permission_error",
    "code": "merchant_account_not_owned"
  }
}

404

Section titled “404”

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

Media typeapplication/json
NotFoundError

No endpoint serves this method and path, or no resource with this identifier exists within the caller's tenant.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: endpoint_not_found payment_not_found fiscal_document_not_found merchant_account_not_found merchant_profile_not_found payment_split_not_found payment_part_not_found
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "endpoint_not_found"
  }
}

409

Section titled “409”

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

Media typeapplication/json
ConflictError

The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: conflict_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: idempotency_key_reused idempotency_request_in_progress idempotency_key_expired payment_method_already_in_progress payment_awaiting_verification decline_not_retryable checkout_window_closed fiscal_preset_locked payment_not_editable fiscal_buyer_required fiscal_correction_not_allowed payment_split_not_allowed payment_split_exists payment_split_locked payment_split_not_capturable payment_split_not_expired payment_split_not_renewable payment_split_complete payment_split_part_required payment_part_not_payable fiscal_artifact_not_ready
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_key_reused"
  }
}

422

Section titled “422”

The request is well-formed but cannot be carried out for this payment or this merchant account.

Media typeapplication/json
UnprocessableRequestError

The request is well-formed but cannot be carried out for this payment or this merchant account.

object
error
required
object
type
required
string
Allowed value: invalid_request
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: merchant_account_not_ready merchant_profile_incomplete payment_description_required merchant_account_provider_mismatch credential_storage_unavailable provider_not_eligible no_eligible_provider 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_document_kind_unsupported fiscal_government_eligibility_required fiscal_government_eligibility_not_allowed
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "invalid_request",
    "code": "merchant_account_not_ready"
  }
}

429

Section titled “429”

Too many requests. Retry after the interval in the Retry-After header.

Media typeapplication/json
RateLimitError

Too many requests. Retry after the interval in the Retry-After header.

object
error
required
object
type
required
string
Allowed value: rate_limit_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: rate_limit_exceeded
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

500

Section titled “500”

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

Media typeapplication/json
ApiError

The gateway failed before reaching a payment outcome. Retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: api_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: internal_error
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "api_error",
    "code": "internal_error"
  }
}

502

Section titled “502”

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

Media typeapplication/json
ProviderError

The payment provider rejected the request or could not be reached before anything was submitted. Safe to retry with the same Idempotency-Key.

object
error
required
object
type
required
string
Allowed value: provider_error
code
required

Stable machine-readable code. Branch on this, never on message.

string
Allowed values: provider_unavailable provider_rejected_request
message
required

Human-readable. Wording may change; not a stable contract.

string
param

Dotted path to the offending request field.

string
docUrl
required
string format: uri
requestId
required

Correlation id, also returned as the Request-Id header.

string
/^request_[0-9a-hjkmnp-tv-z]{24,}$/
Example
{
  "error": {
    "type": "provider_error",
    "code": "provider_unavailable"
  }
}