Operation

Create refund

POST/payments/{paymentId}/refunds

Create a refund for a payment: back to how it was paid, or (`destination: 'account_credit'`) into the order's customer's account credit, which succeeds at once and moves nothing at the payment provider: the payment's holder keeps the money and owes the organisation, which owes the customer. An order with no customer cannot be refunded to credit (STORED_VALUE_CUSTOMER_REQUIRED). A gift card or credit spent goes back onto its balance, which must be active or frozen (STORED_VALUE_NOT_ACTIVE otherwise: refund it to account credit).

Path parameters

paymentIdstringRequired: Payment ID

Headers

X-Ticketlayer-ChannelstringOptional: Slug of the sales channel to act through. A channel-scoped credential supplies its own channel and this header, when sent, must agree with it. On a read it filters to what that channel sells, at its resolved prices; on a cart it is required; on an order operation it is derived from the order and may only confirm it, never contradict it.
Idempotency-KeystringOptional: Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.

Body

amount*numberRefund amount

reason*stringReason for refund

notesstringAdditional notes

metadataobjectCustom metadata

destination"original" | "account_credit"Where the money goes: back to how it was paid (`original`, the default), or into the order's customer's account credit.

Returns

Refund created successfully

Errors

400: Bad Request - Invalid input
401: Unauthorized - Authentication required
403: Forbidden - Insufficient permissions
404: Not Found - Resource not found
500: Internal Server Error

Every error names its code and links to it. All error codes

curl -X POST "https://api.ticketlayer.com/v1/payments/pay_abc123xyz789/refunds" \  -H "Authorization: Bearer tlak_..." \  -H "X-Ticketlayer-Org: your-org-slug" \  -H "Content-Type: application/json" \  -d '{    "amount": 48.5,    "reason": "requested_by_customer",    "notes": "Customer unable to attend",    "metadata": {      "ticketNumber": "T-001"    },    "destination": "account_credit"  }'

Response 201

{
  "refund": {
    "id": "ref_abc123xyz789",
    "paymentId": "pay_abc123xyz789",
    "externalRefundId": "re_xxx",
    "refundRequestId": "rfr_2mK9xB4nQ7rT1pLd3vZs",
    "source": "platform",
    "destination": "original",
    "storedValueAccountId": null,
    "amount": 4850,
    "status": "succeeded",
    "reason": "requested_by_customer",
    "notes": "Customer unable to attend",
    "failureCode": null,
    "failureMessage": null,
    "completedAt": "2024-01-15T11:00:00Z",
    "failedAt": null,
    "metadata": {
      "ticketNumber": "T-001"
    },
    "createdAt": "2024-01-15T10:50:00Z",
    "updatedAt": "2024-01-15T11:00:00Z"
  }
}

Create refund

Path parameters

Headers

Body

Returns

Errors

Try it in test mode

Path parameters

Body