Skip to content
Documentation
Get started

Refunds

Attach an accepted credit-note Invoice to a refund

PUT
/v1/refunds/{refundId}/invoice
curl --request PUT \
  --url https://api.timbro.do/v1/refunds/example/invoice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: example' \
  --data '{ "invoiceId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "receipt": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "accessToken": "example" } }'

Verifies the E34 Invoice against the original Invoice, issuer, environment, currency, and refund amount. Independent Sources supply a restricted receipt credential. This association does not change the provider refund outcome. Retry with the same Idempotency-Key, and retrieve the Refund to confirm its current state.

Authentication

Section titled “Authentication”

Parameters

Section titled “Parameters”

Path parameters

Section titled “Path parameters”
refundId
required
string
/^refund_[0-9a-hjkmnp-tv-z]{24,}$/

Refund associated with the credit note.

Header parameters

Section titled “Header parameters”
idempotency-key
required
string
>= 1 characters <= 255 characters /^[\x20-\x7e]+$/

Request bodyrequired

Section titled “Request bodyrequired”
Media typeapplication/json

Examplegenerated

{
  "invoiceId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "receipt": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "accessToken": "example"
  }
}

Associates an accepted credit-note Invoice after verifying its original Invoice, issuer, environment, currency, and amount. An independent Source supplies its restricted receipt credential.

object
invoiceId
required

The accepted E34 Invoice for this refund’s original Invoice.

string format: uuid
Optional fields
receipt
object
id
required
string format: uuid
accessToken
required
string
>= 43 characters <= 43 characters /^[A-Za-z0-9_-]{43}$/

Responses

Section titled “Responses”

200

Section titled “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:

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

object
currency
required

Example

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

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

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

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

object
currency
required

Example

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

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

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

Captured allocation attributed to this refund.

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

An exact decimal monetary amount.

object
currency
required

Example

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

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

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

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

string
Allowed values: processing succeeded declined verifying operator_required
providerOutcome
required

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

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

Webhook event identifier related to this Refund.

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

Section titled “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.