Payments

Create a payment

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":"Maintenance service","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": "Maintenance service", "returnUrl": "https://merchant.example/orders/123" }'

Creates the durable money object for one sale and returns the customer-facing next action.

A declined attempt does not end the Payment: it returns to status: "requires_customer_action" with lastDecline, and a payment.declined event is delivered. The payer can try again until the Payment expires. An ambiguous provider result is 201 with status: "verifying".

A live Payment that asks Checkout to issue its Invoice (invoicing.mode automatic or merchant) needs Timbro to report production e-CF types ready: its type and, unless isTypeLocked, every type in allowedTypes; without allowedTypes it allows only the types ready at creation. Otherwise creation answers 409 business_fiscal_setup_incomplete, or 503 business_fiscal_setup_unavailable when Timbro cannot answer. A live Payment that asks for no Invoice, or names an existing one, is created without reading Timbro readiness.

Idempotency-Key is optional. Omission derives a stable key from the reference. Retrying with the same key replays the original Payment’s current state through its retained resource identity. Reusing the key with different caller intent returns 409. paymentReference identifies one immutable request within merchant and TEST/LIVE scope. Replay precedes current defaults, including for terminal Payments.

Authentication

secretKey
integrationToken
payments:test
integrationToken
payments:live

Parameters

Header parameters

idempotency-key

string

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

Optional key for repeating this request. If omitted, Timbro uses a key based on paymentReference. Use printable ASCII characters.

Request body^required

Collect by amount, with items, or by invoice. The amount includes tax: for an amount payment, configure the tax or send tax.includedAmount. With items, Timbro computes the totals. By invoice, send only invoicing with an accepted invoice’s invoiceId; the amount and items come from it (collect an invoice).

application/json

Example

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

object

paymentReference

required

Unique reference for this payment. To repeat the request, use the same reference and the same data.

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

description

required

string

>= 1 characters <= 80 characters

Optional fields

returnUrl

Merchant page the customer can open when leaving Checkout. Omit for QR or POS payments.

string format: uri

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

serviceLabel

Context for the payment, such as Table 12.

string

<= 24 characters

expiresAfterSeconds

Seconds the hosted checkout stays open, from 300 (5 minutes) to 86400 (24 hours). Omitted: 1800 with returnUrl, 3600 without. Renewing an expired split bill reopens it for at most this long, never longer than 1800. Part of the request identity.

integer

>= 300 <= 86400

checkoutDisplay

object

mode

required

string

Allowed values: itemized grouped amount_only

metadata

Your reference data, stored and deleted with the payment. Up to 20 keys of 1 to 40 characters, each with a text value of up to 500 characters. Timbro does not use this data to process payments or send it to providers, customers, or webhooks. Do not include personal or card data.

object

<= 20 properties

key

additional properties

string

<= 500 characters

merchantAccountId

Merchant account to use. If omitted, Timbro selects the merchant account.

string

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

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bank alternatives this Payment offers, from the banks the Checkout policy adopted. An empty list offers none; omit it to follow the policy.

Array

<= 2 items unique items

paymentPage

TEST only. true collects on the acquirer’s own payment page (Azul Payment Page or CardNet Botón de Pago) of the Merchant Account that enabled one, instead of Checkout’s card form. The page is then the only method, so it cannot be combined with splits, tips, wallets, or banks. Omit it or send false to use Checkout’s methods.

boolean

testOptions

object

threeDs

boolean

source

Immutable commercial source coordinate supplied by the merchant adapter.

object

required

string

>= 1 characters <= 256 characters

version

required

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 characters

tax

object

includedAmount

required

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

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

Example

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

object

paymentReference

required

Unique reference for this payment. To repeat the request, use the same reference and the same data.

string

>= 1 characters <= 128 characters

currency

required

Example

DOP

string

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

items

required

Array<object>

>= 1 items

object

description

required

string

>= 1 characters <= 80 characters

unitPrice

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,4})?$/

tax

required

object

kind

required

Any of:

string

Allowed value: itbis_18

included

required

boolean

string

>= 1 characters <= 128 characters

product

Presentation metadata. It is excluded from the fiscal canonical content.

object

required

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

Allowed values: 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

Any of:

string
string

string

Allowed value: good

legalTip

object

applied

required

boolean

group

string

>= 1 characters <= 64 characters

Optional fields

returnUrl

Merchant page the customer can open when leaving Checkout. Omit for QR or POS payments.

string format: uri

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

serviceLabel

Context for the payment, such as Table 12.

string

<= 24 characters

expiresAfterSeconds

integer

>= 300 <= 86400

checkoutDisplay

object

mode

required

string

Allowed values: itemized grouped amount_only

metadata

object

<= 20 properties

key

additional properties

string

<= 500 characters

merchantAccountId

Merchant account to use. If omitted, Timbro selects the merchant account.

string

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

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bank alternatives this Payment offers, from the banks the Checkout policy adopted. An empty list offers none; omit it to follow the policy.

Array

<= 2 items unique items

paymentPage

boolean

testOptions

object

threeDs

boolean

source

Immutable commercial source coordinate supplied by the merchant adapter.

object

required

string

>= 1 characters <= 256 characters

version

required

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 characters

invoicing

discriminator: mode

object

type

required

string

Allowed values: E31 E32 E45

mode

required

string

Allowed value: automatic

buyer

Any of:

object

kind

required

string

Allowed value: anonymous

recipientEmail

Buyer email the Invoice is delivered to once issued.

string format: email

<= 254 characters

allowedTypes

Array<string>

>= 1 items

Allowed values: E31 E32 E45

isTypeLocked

boolean

isBuyerLocked

boolean

governmentEligibility

Any of:

object

entityKind

required

string

Allowed value: central_government

authorityReference

required

string

>= 1 characters <= 128 characters

invoiceReference

string

>= 1 characters <= 128 characters

object

mode

required

string

Allowed value: existing

invoiceId

required

string format: uuid

receipt

Restricted receipt access for an Invoice owned by an independent Source. Keep the token private.

object

required

string format: uuid

accessToken

required

string

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

recipientEmail

Buyer email the Invoice is delivered to. Not accepted together with receipt; Invoices owned by an independent Source are delivered by their owner.

string format: email

<= 254 characters

expectedTotals

object

net

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

tax

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

legalTip

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

total

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

Collects an accepted Invoice’s full payable total by its id. The Payment takes the sale, its currency, and its totals from the Invoice. To collect part of the total, send CreateInvoicePartPaymentRequest with an amount. An Invoice is collected in full by one Payment or in parts by several, never both ways at once.

Example

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

object

paymentReference

required

Unique reference for this payment. To repeat the request, use the same reference and the same data.

string

>= 1 characters <= 128 characters

invoicing

required

object

mode

required

string

Allowed value: existing

invoiceId

required

string format: uuid

receipt

Restricted receipt access for an Invoice owned by an independent Source. Keep the token private.

object

required

string format: uuid

accessToken

required

string

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

recipientEmail

Buyer email the Invoice is delivered to. Not accepted together with receipt; Invoices owned by an independent Source are delivered by their owner.

string format: email

<= 254 characters

Optional fields

returnUrl

Merchant page the customer can open when leaving Checkout. Omit for QR or POS payments.

string format: uri

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

serviceLabel

Context for the payment, such as Table 12.

string

<= 24 characters

expiresAfterSeconds

integer

>= 300 <= 86400

metadata

object

<= 20 properties

key

additional properties

string

<= 500 characters

merchantAccountId

Merchant account to use. If omitted, Timbro selects the merchant account.

string

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

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bank alternatives this Payment offers, from the banks the Checkout policy adopted. An empty list offers none; omit it to follow the policy.

Array

<= 2 items unique items

paymentPage

boolean

testOptions

object

threeDs

boolean

source

Immutable commercial source coordinate supplied by the merchant adapter.

object

required

string

>= 1 characters <= 256 characters

version

required

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 characters

Collects part of an accepted Invoice’s payable total by its id. The Payment collects only amount, with no lines of its own, and stays linked to the Invoice.

Example

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

object

paymentReference

required

Unique reference for this payment. To repeat the request, use the same reference and the same data.

string

>= 1 characters <= 128 characters

invoicing

required

The accepted Invoice a part collects. A part never delivers the Invoice and collects only an Invoice issued through this business’s own Source, so it takes no recipientEmail or receipt.

object

mode

required

string

Allowed value: existing

invoiceId

required

string format: uuid

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

Optional fields

returnUrl

Merchant page the customer can open when leaving Checkout. Omit for QR or POS payments.

string format: uri

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

serviceLabel

Context for the payment, such as Table 12.

string

<= 24 characters

expiresAfterSeconds

integer

>= 300 <= 86400

metadata

object

<= 20 properties

key

additional properties

string

<= 500 characters

merchantAccountId

Merchant account to use. If omitted, Timbro selects the merchant account.

string

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

checkoutPreferences

object

splits

boolean

tips

boolean

wallets

Array

<= 2 items unique items

banks

Bank alternatives this Payment offers, from the banks the Checkout policy adopted. An empty list offers none; omit it to follow the policy.

Array

<= 2 items unique items

paymentPage

boolean

testOptions

object

threeDs

boolean

source

Immutable commercial source coordinate supplied by the merchant adapter.

object

required

string

>= 1 characters <= 256 characters

version

required

string

>= 1 characters <= 128 characters

saleReference

string

>= 1 characters <= 128 characters

tax

The ITBIS included in a part amount. If you omit it, Timbro gives the part the share of the Invoice’s ITBIS that matches its amount, rounded to the cent (half a cent rounds up). When every other part used this share, the part that completes the total takes the ITBIS left. A part’s ITBIS cannot be more than the part’s amount or the Invoice’s ITBIS the other parts do not yet cover.

object

includedAmount

required

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

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

description

Description of a part Payment. Defaults to Factura <e-NCF>.

string

>= 1 characters <= 80 characters

Responses

200

One durable merchant payment request.

application/json

Response fields and codes

One durable merchant payment request.

object

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

Only succeeded, canceled, and expired are terminal. A declined attempt returns the Payment to requires_customer_action with lastDecline, so the payer can try again until the Payment expires. 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 canceled expired

source

required

Immutable commercial source coordinate supplied by the merchant adapter.

object

required

string

>= 1 characters <= 256 characters

version

required

string

>= 1 characters <= 128 characters

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

checkoutDisplay

required

Read-only checkout presentation assembled from merchant configuration.

object

mode

required

string

Allowed values: itemized grouped amount_only

locale

required

Interface language. Amount notation and currency are independent of language.

string

Allowed values: es en

merchant

required

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

object

line1

required

string

>= 1 characters <= 160 characters

city

required

string

>= 1 characters <= 80 characters

countryCode

required

string

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

line2

string

>= 1 characters <= 160 characters

province

string

>= 1 characters <= 80 characters

postalCode

string

>= 1 characters <= 20 characters

deliveryPolicy

Any of:

object
object

object

kind

required

string

Allowed value: not_offered

statementDescriptor

required

string

>= 1 characters <= 22 characters

fiscal

required

object

availableKinds

required

Array<object>

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

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,}$/

lastDecline

required

Any of:

PaymentDecline
null

The most recent declined attempt. A decline ends the attempt, not the Payment; the payer can try again until the Payment expires. Submitting the next attempt, canceling the Payment, or creating, replacing, or renewing its split clears it; expiry keeps it.

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 authentication_unavailable suspected_fraud do_not_honor issuer_unavailable generic_decline confirmation_timeout

message

required

Customer-safe explanation. Wording may change.

string

attemptedAt

required

When the gateway recorded the provider’s decline of this attempt.

string format: date-time

problem

required

Any of:

PaymentProblem
null

An approved payment whose settlement evidence needs operator resolution. It does not withdraw the approval.

object

code

required

Normalized classification of a settlement problem found after approval.

string

Allowed values: settlement_amount_mismatch settlement_record_not_found settlement_amount_unverified

message

required

string

>= 1 characters <= 500 characters

invoiceId

required

Any of:

string
null

Canonical Timbro Invoice UUID when admitted.

string format: uuid

invoicing

required

Any of:

PaymentInvoicing
null

Retained Invoice instructions and recipient choice. Invoice lifecycle and access credentials are reported separately.

object

mode

required

Any of:

string

Allowed value: automatic

type

required

string

Allowed values: E31 E32 E45

recipientEmail

required

Any of:

string
null

string format: email

<= 320 characters

issuanceProblem

One RFC 9457 problem body returned on the /v1 surface.

object

code

required

string

>= 1 characters

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

title

required

string

type

required

string

Allowed values: about:blank

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

Allowed values: 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

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

buyer

discriminator: kind

object

kind

required

string

Allowed values: anonymous

governmentEligibility

Any of:

object

entityKind

required

string

Allowed value: central_government

authorityReference

required

string

>= 1 characters <= 128 characters

allowedTypes

Array<string>

Allowed values: E31 E32 E45

isTypeLocked

boolean

isBuyerLocked

boolean

revision

Increases each time the Invoice type, buyer, or government eligibility changes.

integer

>= 1

invoiceReference

string

>= 1 characters <= 128 characters

verification

required

Any of:

Verification
null

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:

PaymentMethodSummary
null

discriminator: kind

object

kind

required

string

Allowed value: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

isLiveMode

required

boolean

expiresAt

required

Any of:

string
null

string format: date-time

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

sale

required

discriminator: kind

ItemizedSale
AmountOnlySale

object

kind

required

string

Allowed value: itemized

reference

required

string

>= 1 characters <= 128 characters

currency

required

string

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

items

required

Array<object>

>= 1 items

object

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

unitPrice

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,4})?$/

tax

required

object

kind

required

Any of:

string

Allowed value: itbis_18

included

required

boolean

product

Presentation metadata. It is excluded from the fiscal canonical content.

object

required

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

Any of:

string
string

string

Allowed value: good

legalTip

object

applied

required

boolean

group

string

>= 1 characters <= 64 characters

totals

required

object

net

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

tax

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

legalTip

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

total

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

paymentReference

required

Immutable payment request identity within merchant and TEST/LIVE scope.

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

voluntaryTip

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

totalAmount

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

checkout

required

object

url

required

string format: uri

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

expiresAt

required

Any of:

string
null

string format: date-time

split

required

Any of:

MerchantSplit
null

object

status

required

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

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

authorized

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

remainingToAuthorize

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

remainingToCapture

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

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

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

allocatedItbis

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

status

required

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 succeeded released expired

lastDecline

required

Any of:

PaymentDecline
null

object

code

required

Normalized decline code. Raw provider codes are not public.

string

message

required

Customer-safe explanation. Wording may change.

string

attemptedAt

required

When the gateway recorded the provider’s decline of this attempt.

string format: date-time

paymentMethodSummary

required

Any of:

PaymentMethodSummary
null

discriminator: kind

object

kind

required

string

Allowed value: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

refundable

required

Any of:

object
null

object

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

automaticAmount

required

Any of:

Money
null

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

automaticPartial

required

Any of:

object
null

object

maximumAmount

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

maximumTaxAmount

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

Optional fields

subscriptionId

Subscription owning this billing period

string

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

initiator

Any of:

string
string

string

Allowed value: customer

billingPeriod

object

start

required

string format: date-time

end

required

string format: date-time

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

Server-computed money composition. The invariant is payableTotalMinorUnits = fiscalDeclaredTotalMinorUnits + nonBillableMinorUnits; legal and voluntary tips are never double-counted.

object

taxableBases

required

Array<object>

object

taxTreatment

required

string

Allowed values: itbis_18 itbis_16 zero_rated

baseMinorUnits

required

integer

taxMinorUnits

required

integer

exemptMinorUnits

required

integer

nonBillableMinorUnits

required

integer

serviceCharges

required

Array<object>

object

kind

required

string

Allowed values: propina_legal

minorUnits

required

integer

taxesMinorUnits

required

integer

fiscalDeclaredTotalMinorUnits

required

Fiscal declared total: taxable bases, taxes, exempt lines, and legal tip. Non-billable lines are excluded.

integer

payableTotalMinorUnits

required

Commercial payable total: fiscalDeclaredTotalMinorUnits plus nonBillableMinorUnits. This is the amount collected before a voluntary tip.

integer

groups

Array<object>

object

group

required

string

>= 1 characters <= 64 characters

subtotalMinorUnits

required

integer

nextAction

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

paymentChannel

object

kind

required

string

Allowed value: bank_checkout

bank

required

Any of:

string
string

string

Allowed value: popular

processingReason

string

Allowed value: awaiting_company_approval

metadata

Merchant-owned keys carried with this Payment: at most 20 keys of 1 to 40 characters, each holding a string of at most 500 characters. Checkout stores it opaquely, never branches on it, never sends it to a payment provider, and never repeats it in a webhook body or a payer projection. It lives as long as its Payment and is deleted with it. Never put personal data or card data in it.

object

<= 20 properties

key

additional properties

string

<= 500 characters

tax

object

includedAmount

required

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

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

provenance

required

Any of:

string

Allowed value: explicit

policyRevision

integer

capturedPayment

object

allocations

required

Array<object>

>= 1 items

object

required

Stable identifier for one captured payment allocation.

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

paymentMethodSummary

required

Any of:

PaymentMethodSummary
null

discriminator: kind

object

kind

required

string

Allowed value: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

Idempotent-Replayed

string

Allowed value: true

true when this response replays the stored result of an earlier request with the same Idempotency-Key.

201

One durable merchant payment request.

application/json

Response fields and codes

One durable merchant payment request.

object

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

string

Allowed values: requires_customer_action processing partially_authorized authorized capturing partially_paid releasing verifying succeeded canceled expired

source

required

Immutable commercial source coordinate supplied by the merchant adapter.

object

required

string

>= 1 characters <= 256 characters

version

required

string

>= 1 characters <= 128 characters

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

checkoutDisplay

required

Read-only checkout presentation assembled from merchant configuration.

object

mode

required

string

Allowed values: itemized grouped amount_only

locale

required

Interface language. Amount notation and currency are independent of language.

string

Allowed values: es en

merchant

required

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

object

line1

required

string

>= 1 characters <= 160 characters

city

required

string

>= 1 characters <= 80 characters

countryCode

required

string

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

line2

string

>= 1 characters <= 160 characters

province

string

>= 1 characters <= 80 characters

postalCode

string

>= 1 characters <= 20 characters

deliveryPolicy

Any of:

object
object

object

kind

required

string

Allowed value: not_offered

statementDescriptor

required

string

>= 1 characters <= 22 characters

fiscal

required

object

availableKinds

required

Array<object>

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

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,}$/

lastDecline

required

Any of:

PaymentDecline
null

object

code

required

Normalized decline code. Raw provider codes are not public.

string

message

required

Customer-safe explanation. Wording may change.

string

attemptedAt

required

When the gateway recorded the provider’s decline of this attempt.

string format: date-time

problem

required

Any of:

PaymentProblem
null

An approved payment whose settlement evidence needs operator resolution. It does not withdraw the approval.

object

code

required

Normalized classification of a settlement problem found after approval.

string

Allowed values: settlement_amount_mismatch settlement_record_not_found settlement_amount_unverified

message

required

string

>= 1 characters <= 500 characters

invoiceId

required

Any of:

string
null

Canonical Timbro Invoice UUID when admitted.

string format: uuid

invoicing

required

Any of:

PaymentInvoicing
null

Retained Invoice instructions and recipient choice. Invoice lifecycle and access credentials are reported separately.

object

mode

required

Any of:

string

Allowed value: automatic

type

required

string

Allowed values: E31 E32 E45

recipientEmail

required

Any of:

string
null

string format: email

<= 320 characters

issuanceProblem

One RFC 9457 problem body returned on the /v1 surface.

object

code

required

string

>= 1 characters

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

title

required

string

type

required

string

Allowed values: about:blank

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

buyer

discriminator: kind

object

kind

required

string

Allowed values: anonymous

governmentEligibility

Any of:

object

entityKind

required

string

Allowed value: central_government

authorityReference

required

string

>= 1 characters <= 128 characters

allowedTypes

Array<string>

Allowed values: E31 E32 E45

isTypeLocked

boolean

isBuyerLocked

boolean

revision

Increases each time the Invoice type, buyer, or government eligibility changes.

integer

>= 1

invoiceReference

string

>= 1 characters <= 128 characters

verification

required

Any of:

Verification
null

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:

PaymentMethodSummary
null

discriminator: kind

object

kind

required

string

Allowed value: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

isLiveMode

required

boolean

expiresAt

required

Any of:

string
null

string format: date-time

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

sale

required

discriminator: kind

ItemizedSale
AmountOnlySale

object

kind

required

string

Allowed value: itemized

reference

required

string

>= 1 characters <= 128 characters

currency

required

string

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

items

required

Array<object>

>= 1 items

object

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

unitPrice

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,4})?$/

tax

required

object

kind

required

Any of:

string

Allowed value: itbis_18

included

required

boolean

product

Presentation metadata. It is excluded from the fiscal canonical content.

object

required

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

Any of:

string
string

string

Allowed value: good

legalTip

object

applied

required

boolean

group

string

>= 1 characters <= 64 characters

totals

required

object

net

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

tax

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

legalTip

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

total

required

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

paymentReference

required

Immutable payment request identity within merchant and TEST/LIVE scope.

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

voluntaryTip

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

totalAmount

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

checkout

required

object

url

required

string format: uri

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

expiresAt

required

Any of:

string
null

string format: date-time

split

required

Any of:

MerchantSplit
null

object

status

required

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

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

authorized

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

remainingToAuthorize

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

remainingToCapture

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

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

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

allocatedItbis

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

status

required

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 succeeded released expired

lastDecline

required

Any of:

PaymentDecline
null

object

code

required

Normalized decline code. Raw provider codes are not public.

string

message

required

Customer-safe explanation. Wording may change.

string

attemptedAt

required

When the gateway recorded the provider’s decline of this attempt.

string format: date-time

paymentMethodSummary

required

Any of:

PaymentMethodSummary
null

discriminator: kind

object

kind

required

string

Allowed value: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

refundable

required

Any of:

object
null

object

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

automaticAmount

required

Any of:

Money
null

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

automaticPartial

required

Any of:

object
null

object

maximumAmount

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

maximumTaxAmount

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

Optional fields

subscriptionId

Subscription owning this billing period

string

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

initiator

Any of:

string
string

string

Allowed value: customer

billingPeriod

object

start

required

string format: date-time

end

required

string format: date-time

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

Server-computed money composition. The invariant is payableTotalMinorUnits = fiscalDeclaredTotalMinorUnits + nonBillableMinorUnits; legal and voluntary tips are never double-counted.

object

taxableBases

required

Array<object>

object

taxTreatment

required

string

Allowed values: itbis_18 itbis_16 zero_rated

baseMinorUnits

required

integer

taxMinorUnits

required

integer

exemptMinorUnits

required

integer

nonBillableMinorUnits

required

integer

serviceCharges

required

Array<object>

object

kind

required

string

Allowed values: propina_legal

minorUnits

required

integer

taxesMinorUnits

required

integer

fiscalDeclaredTotalMinorUnits

required

Fiscal declared total: taxable bases, taxes, exempt lines, and legal tip. Non-billable lines are excluded.

integer

payableTotalMinorUnits

required

Commercial payable total: fiscalDeclaredTotalMinorUnits plus nonBillableMinorUnits. This is the amount collected before a voluntary tip.

integer

groups

Array<object>

object

group

required

string

>= 1 characters <= 64 characters

subtotalMinorUnits

required

integer

nextAction

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

paymentChannel

object

kind

required

string

Allowed value: bank_checkout

bank

required

Any of:

string
string

string

Allowed value: popular

processingReason

string

Allowed value: awaiting_company_approval

metadata

object

<= 20 properties

key

additional properties

string

<= 500 characters

tax

object

includedAmount

required

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

string

/^(0|[1-9][0-9]{0,15})(\.[0-9]{1,2})?$/

provenance

required

Any of:

string

Allowed value: explicit

policyRevision

integer

capturedPayment

object

allocations

required

Array<object>

>= 1 items

object

required

Stable identifier for one captured payment allocation.

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

paymentMethodSummary

required

Any of:

PaymentMethodSummary
null

discriminator: kind

object

kind

required

string

Allowed value: card

brand

string

>= 1 characters <= 32 characters

last4

string

/^\d{4}$/

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

Idempotent-Replayed

string

Allowed value: true

true when this response replays the stored result of an earlier request with the same Idempotency-Key.

400

The request could not be understood.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not be understood.",
  "status": 400,
  "code": "parameter_missing",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: 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

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 400

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

401

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

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is missing, malformed, or no longer valid.",
  "status": 401,
  "code": "api_key_missing",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: api_key_missing api_key_invalid integration_token_invalid checkout_token_invalid checkout_token_expired

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 401

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

403

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

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The credential is valid but not permitted to perform this operation.",
  "status": 403,
  "code": "operation_not_permitted",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: operation_not_permitted

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 403

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

404

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

application/problem+json

Example

{
  "type": "about:blank",
  "title": "No endpoint serves this method and path, or no resource with this identifier exists within the caller's scope.",
  "status": 404,
  "code": "payment_not_found",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: payment_not_found

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 404

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

409

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

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request conflicts with the current state of the resource or with a previous request using the same Idempotency-Key.",
  "status": 409,
  "code": "business_fiscal_setup_incomplete",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: 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

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 409

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

Retry-After

string

/^[0-9]+$/

Seconds to wait before repeating this request or reading the resource again.

413

The request body is larger than this endpoint accepts.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request body is larger than this endpoint accepts.",
  "status": 413,
  "code": "request_body_too_large",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: request_body_too_large

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 413

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

415

The request body carries a content type this endpoint does not accept.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request body carries a content type this endpoint does not accept.",
  "status": 415,
  "code": "unsupported_media_type",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: unsupported_media_type

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 415

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

422

The request is well-formed but cannot be carried out.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request is well-formed but cannot be carried out.",
  "status": 422,
  "code": "merchant_account_not_ready",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: 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

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 422

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

500

The request could not complete. Recover by the retained resource reference or retry with the same command identity.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "The request could not complete. Recover by the retained resource reference or retry with the same command identity.",
  "status": 500,
  "code": "internal_error",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: internal_error

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 500

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

503

A required service is temporarily unavailable. Retry with the same reference or command identity.

application/problem+json

Example

{
  "type": "about:blank",
  "title": "A required service is temporarily unavailable. Retry with the same reference or command identity.",
  "status": 503,
  "code": "business_fiscal_binding_unavailable",
  "requestId": "request_000000000000000000000001"
}

Response fields and codes

RFC 9457 problem details. Every failure of this API is one of these, and each operation narrows code to the subset it can emit.

object

code

required

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

string

Allowed values: business_fiscal_binding_unavailable business_fiscal_setup_unavailable integration_authorization_unavailable payments_contract_migration_required merchant_payments_api_paused taxpayer_directory_unavailable

requestId

required

string

status

required

integer format: int32

>= 400 <= 599

Allowed value: 503

title

required

string

type

required

string

Allowed values: about:blank

Optional fields

detail

string

invoiceId

Present only when the rejected request produced a Fiscal operation.

string

issuanceBlockers

Present only when the authoritative issuance rules refused to issue.

Array<string>

problems

Present only when the rejection points at a value the request carried.

Array<object>

One stable public document problem retained for a rejected admission.

object

code

required

string

message

required

string

path

required

string

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

Retry-After

string

/^[0-9]+$/

Seconds to wait before repeating this request or reading the resource again.

Create a payment

Authentication

Parameters

Header parameters

Request bodyrequired

Example

Example

Example

Example

Example

Example

Example

Responses

200

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Headers

201

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Headers

400

Example

Headers

401

Example

Headers

403

Example

Headers

404

Example

Headers

409

Example

Headers

413

Example

Headers

415

Example

Headers

422

Example

Headers

500

Example

Headers

503

Example

Headers

Request body^required