Skip to main content
POST
/
appointments
/
{appointmentId}
/
payments
/
{paymentId}
/
refunds
Refund an appointment payment
curl --request POST \
  --url https://api.guile.app/appointments/{appointmentId}/payments/{paymentId}/refunds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": "456.78",
  "reason": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "paymentMethod": "platform",
  "paymentDirection": "payment",
  "paymentState": "pending",
  "amount": "456.78",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "paymentToken": "<string>",
  "externalId": "<string>",
  "originalPaymentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "refundReason": "<string>"
}

Headers

​
Idempotency-Key
string
required

A client-generated idempotency key to ensure operations are only processed once even if a client retries the operation. The V4 UUID format, as defined in RFC 4122, is recommended to avoid collisions but is not required.

Path Parameters

​
appointmentId
string<uuid>
required

The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

​
paymentId
string<uuid>
required

The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.

Body

application/json

Request body for refunding a payment.

​
amount
string<decimal>
required

The amount to refund. Refunds cannot be issued for an amount greater than the captured amount minus previous refunds.

Example:

"456.78"

​
reason
string

Optional reason for the refund.

Maximum string length: 500

Response

Ok. The operation succeeded.

Represents a payment associated with an appointment.

​
id
string<uuid>
required

Unique identifier for the payment.

​
paymentMethod
enum<string>
required

The method used to process this payment.

Available options:
platform,
external
​
paymentDirection
enum<string>
required

The direction of the payment flow.

Available options:
payment,
refund
​
paymentState
enum<string>
required

The payment state.

Available options:
pending,
authorized,
paid,
failed
​
amount
string<decimal>
required

The amount of this payment.

Example:

"456.78"

​
createdAt
string<date-time>
required

The date-time when this resource was created, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC. This is derived and immutable.

​
updatedAt
string<date-time>
required

The date-time when this resource was updated, in RFC 3339 date-time YYYY-MM-DDThh:mm:ss.sssZ format, UTC. This is derived and immutable.

​
paymentToken
string

For external payments, the token representing the payment.

​
externalId
string

External identifier for the payment from the payment processor or external system.

​
originalPaymentId
string<uuid>

For refund payments, the original payment being refunded.

​
refundReason
string

For refund payments, the reason for the refund.

Maximum string length: 500