Invoices: Refunds the payments collected against an invoice.
POST
/api/invoicing/invoices/{id}/refund
deprecated
Requires: Invoicing.Invoices, Invoicing.Invoices.Refund, merchant scope.
Returns the money to the payer and moves the invoice to Refunded. Gateway payments delegate to the payment platform, which returns the money with whichever operation the originating transaction's settlement state permits. Manually-recorded payments are reversed in place and require a reason.
Example request
Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.
The request body is a RefundInvoiceInput. See the Request body section below for its fields.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id
required |
path | string (uuid) | |
suppressNulls
required |
query | boolean | If true, omit properties with null values. |
Request body
application/json
, required
| Field | Type | Description |
|---|---|---|
reason
required |
string | Operator-supplied reason for the refund. Recorded on the refund entry and on the invoice's activity timeline, and threaded onto the gateway operation's audit note. nullablemax length 500 |
idempotencyKey
required |
string | Optional caller-supplied idempotency key. When omitted, the service derives a deterministic key per refunded payment so a retry after a timeout replays the original outcome rather than returning the money twice. Conditional: When IdempotencyKey is not empty. Pattern: ^[A-Za-z0-9._:-]+$. nullablemax length 128 |
This request body has no documented fields.
Responses
200 The refund completed and the invoice reflects it.
Body: InvoiceDto
Each item has these fields.
| Field | Type | Description |
|---|---|---|
extraProperties
required |
object | nullableread only |
id
required |
string (uuid) | |
creationTime
required |
string (date-time) | The date and time when this entity was created. |
creatorId
required |
string (uuid) | The ID of the user who created this entity. nullable |
lastModificationTime
required |
string (date-time) | The date and time when this entity was last modified. nullable |
lastModifierId
required |
string (uuid) | The ID of the user who last modified this entity. nullable |
isDeleted
required |
boolean | Indicates whether this entity has been deleted. |
deleterId
required |
string (uuid) | The ID of the user who deleted this entity, if it is deleted. nullable |
deletionTime
required |
string (date-time) | The date and time when this entity was deleted, if it is deleted. nullable |
tenantId
required |
string (uuid) | nullable |
billerId
required |
string (uuid) | |
billerType
required |
InvoicePartyType | Identifies the type of entity acting as the biller or recipient on an invoice. one of: GatewayOwner, Reseller, Merchant, Customer |
recipientId
required |
string (uuid) | |
recipientType
required |
InvoicePartyType | Identifies the type of entity acting as the biller or recipient on an invoice. one of: GatewayOwner, Reseller, Merchant, Customer |
invoiceNumber
required |
string | nullable |
status
required |
InvoiceStatus | Represents the lifecycle status of an invoice. one of: Draft, Issued, Sent, Viewed, PartiallyPaid, Paid, PastDue, Closed, Uncollectible, Cancelled, Refunded |
isLocked
required |
boolean | nullable |
billerSnapshot
required |
InvoicePartySnapshotDto | Read DTO for denormalized biller/recipient info frozen at invoice issuance. |
recipientSnapshot
required |
InvoicePartySnapshotDto | Read DTO for denormalized biller/recipient info frozen at invoice issuance. |
currency
required |
string | nullable |
subtotal
required |
number (double) | nullable |
taxTotal
required |
number (double) | nullable |
discountTotal
required |
number (double) | nullable |
grandTotal
required |
number (double) | nullable |
amountPaid
required |
number (double) | nullable |
balanceDue
required |
number (double) | nullable |
invoiceLevelDiscount
required |
InvoiceDiscountDto | DTO for an invoice-level discount. |
issueDate
required |
string (date-time) | nullable |
dueDate
required |
string (date-time) | nullable |
sentAt
required |
string (date-time) | nullable |
viewedAt
required |
string (date-time) | nullable |
paidAt
required |
string (date-time) | nullable |
paymentTermsValue
required |
all of PaymentTerms | nullable |
customPaymentDays
required |
integer (int32) | nullable |
allowPartialPayment
required |
boolean | nullable |
minimumPaymentAmount
required |
number (double) | nullable |
partialPaymentTolerance
required |
number (double) | nullable |
allowedPaymentMethods
required |
array of string | nullable |
vaultRestriction
required |
all of VaultRestriction | nullable |
applyConvenienceFee
required |
boolean | Per-invoice override of the merchant's convenience fee on this invoice's payments. `null` inherits the merchant and feature decision. `true` applies the fee only when invoice convenience fees are enabled for the tenant. nullable |
depositRequest
required |
all of InvoiceDepositRequestInfoDto | The deposit request on this invoice, if any. Null when no deposit was requested. |
hppPageId
required |
string (uuid) | nullable |
templateId
required |
string (uuid) | nullable |
sourceType
required |
all of InvoiceSourceType | nullable |
sourceReferenceId
required |
string | nullable |
notes
required |
array of EntityNote | nullable |
recipientNote
required |
string | nullable |
footerText
required |
string | nullable |
reminderConfig
required |
InvoiceReminderConfigDto | DTO for invoice reminder configuration. Each member overrides the tenant's reminder default on its own; a member that is null or omitted inherits that default. |
lineItems
required |
array of InvoiceLineItemDto | nullable |
payments
required |
array of InvoicePaymentDto | nullable |
activities
required |
array of InvoiceActivityDto | nullable |
customFields
required |
array of CustomFieldValueDto | nullable |
concurrencyStamp
required |
string | nullable |
entityVersion
required |
integer (int32) |
This response has no documented body fields.
403 Forbidden
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
401 Unauthorized
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
400 The request itself needs correcting. Callers branch on `error.code`: `Invoicing:Refund:ManualReversalRequiresReason` (a manually recorded payment is being reversed and no reason was supplied) or `Invoicing:Refund:AmountInvalid`.
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
404 The invoice does not exist, or is not visible to this caller (`Invoicing:Biller:ForeignBillerNotAllowed`).
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
501 Not Implemented
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
500 Internal Server Error
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
409 The invoice's current state refuses the refund. Callers branch on `error.code`: `Invoicing:Refund:NotAllowedForStatus`, `Invoicing:Refund:NoRefundablePayments`, `Invoicing:Refund:ExceedsAmountPaid`, `Invoicing:Refund:RequiresMerchantScope`, `Invoicing:Refund:RejectedByGateway`, or `Invoicing:Refund:PartialFailure` (some payments were returned before the sequence stopped; inspect the invoice before retrying).
Body:
Each item has these fields.
| Field | Type | Description |
|---|
This response has no body.
default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. See the error-code reference in this document's description for the values `error.code` can take.
Body: RemoteServiceErrorResponse
Each item has these fields.
| Field | Type | Description |
|---|---|---|
error
required |
RemoteServiceErrorInfo |
This response has no documented body fields.
429 The request was refused because a rate limit was exceeded. Wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling.
Body: RateLimitProblemDetails
Each item has these fields.
| Field | Type | Description |
|---|---|---|
type
required |
string | The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. nullable |
title
required |
string | A short, human-readable summary of the problem type. nullable |
status
required |
integer (int32) | The HTTP status code, repeated in the body as the problem-details format defines. |
detail
required |
string | A human-readable explanation of this occurrence of the problem. nullable |
retryAfterSeconds
required |
integer (int32) | How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. |
This response has no documented body fields.
Errors
A failed request returns the platform error envelope. The
error reference lists every value
error.code can carry and shows the four response shapes.