Create a full or partial refund

POST

/v1/refunds

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

• Production

Creates a durable refund request against captured Payment money. The request records exact allocation attribution before any provider work begins. refundReference is the immutable identity of this refund within the merchant and mode. Retrying it with the same caller intent returns the current Refund; changing the intent returns a conflict. Omitting amount reserves the remaining captured balance for the selected allocations when the Refund is first created. voluntaryTipAmount declares the exact returned voluntary-tip portion. For a partial refund it defaults to zero; refunding the entire remaining captured balance includes the remaining tip. Each portion must fit its own captured balance. Voluntary tips are excluded from the credit-note amount. source is optional for ERP coordination. When supplied, its immutable ID and version cannot identify a different Refund. taxAmount declares the exact returned ITBIS, never a proportional estimate. Refunding the original full captured balance uses its retained tax when omitted; an explicit amount must match. Later refunds preserve caller-declared tax within the remaining captured tax, and omission leaves it unproven. A Refund is submitted without an operator for the full captured amount of an unsplit DOP TEST card Payment with no earlier Refund other than declined ones. An eligible Azul Sale can instead return one lower amount with an explicit exact taxAmount, within refundable.automaticPartial limits. Partial refunds of authorization captures, CardNet, split, LIVE, wallet, and sandbox Payments remain operator_required. Azul retains the original full capture binding and credentials, submits the exact returned amount and tax on a unique correlation, and requires matching VerifyPayment inquiry. CardNet full refunds use the captured Ztrans transaction and active refund credential; before CardNet’s 7:00 p.m. close, when CardNet refuses the Refund, the same request voids the Sale instead. Read refundable.automaticAmount for the full amount and refundable.automaticPartial for partial support. A submitted Refund can still end declined or operator_required. A successful provider refund never creates a fiscal credit or debit note; associate the accepted credit-note Invoice separately. When Idempotency-Key is omitted, the Refund reference supplies a stable retry key. If a key is provided, reuse it for retries. Retrieve the Refund to confirm its current state.

Authentication

• secretKey
• integrationToken
  refunds:test
• integrationToken
  refunds:live

Parameters

Header parameters

idempotency-key

string

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

Request body^required

Media typeapplication/json

Creates a full refund when amount equals the remaining captured balance, or a partial refund for a lower amount.

object

paymentId

required

Payment with captured money to refund.

string

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

refundReference

required

Stable Refund identity. Retrying the same intent returns the current Refund; changed intent conflicts.

string

>= 1 characters <= 128 characters

Optional fields

source

Immutable commercial source coordinate supplied by the merchant adapter.

object

id

required

string

>= 1 characters <= 256 characters

version

required

string

>= 1 characters <= 128 characters

amount

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

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

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

Array<string>

>= 1 items <= 100 items

Responses

200

200

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

Media typeapplication/json

Response fields and codes

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:

Money

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

null

null

voluntaryTipAmount

required

Any of:

Money

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

null

null

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

string

Allowed value: partial

string

string

Allowed value: full

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

string format: date-time

null

null

nextRetryAt

required

Any of:

string

string format: date-time

null

null

message

string

>= 1 characters <= 500 characters

reasonCode

string

>= 1 characters <= 128 characters

invoiceId

required

Any of:

string

string format: uuid

null

null

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

Optional fields

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

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

201

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

Media typeapplication/json

Response fields and codes

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:

Money

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

null

null

voluntaryTipAmount

required

Any of:

Money

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

null

null

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

string

Allowed value: partial

string

string

Allowed value: full

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

string format: date-time

null

null

nextRetryAt

required

Any of:

string

string format: date-time

null

null

message

string

>= 1 characters <= 500 characters

reasonCode

string

>= 1 characters <= 128 characters

invoiceId

required

Any of:

string

string format: uuid

null

null

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

Optional fields

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

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

400

The request could not be understood.

Media typeapplication/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 request_body_malformed refund_reference_invalid

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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

401

401

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

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

403

403

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

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

404

404

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

Media typeapplication/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 refund_not_found refund_allocation_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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

409

409

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

Media typeapplication/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": "refund_reference_conflict",
  "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: refund_reference_conflict idempotency_key_reused idempotency_request_in_progress idempotency_key_expired refund_source_identity_conflict refund_payment_not_captured refund_exceeds_captured refund_allocation_conflict refund_allocation_ledger_unavailable refund_tip_allocation_unknown

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>

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

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

413

The request body is larger than this endpoint accepts.

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

415

415

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

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

422

422

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

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "The request is well-formed but cannot be carried out.",
  "status": 422,
  "code": "refund_tip_amount_invalid",
  "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: refund_tip_amount_invalid refund_amount_invalid refund_tax_amount_invalid refund_tax_amount_required refund_tax_allocation_unknown refund_currency_mismatch

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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

500

500

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

Media typeapplication/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>

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

Headers

request-id

required

string

Identifies this request. Quote it when you contact support.

503

503

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

Media typeapplication/problem+json

Example

{
  "type": "about:blank",
  "title": "A required service is temporarily unavailable. Retry with the same reference or command identity.",
  "status": 503,
  "code": "integration_authorization_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: integration_authorization_unavailable payments_contract_migration_required merchant_payments_api_paused

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>

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

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.