Skip to main content
POST

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.

Maximum string length: 255

Path Parameters

​
barberId
string
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.

​
appointmentId
string
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 creating an external payment.

​
amount
string<decimal>
required

The full amount recorded for the external payment, including any tip.

Pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
Example:

"456.78"

​
currencyCode
string

The ISO 4217 currency code for this payment's monetary values.

Required string length: 3
Example:

"USD"

​
tipAmount
string<decimal>

The tip included in amount. This value cannot exceed amount.

Pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
Example:

"456.78"

​
paymentToken
string

Optional external payment token or reference (e.g., Venmo transaction ID).

Maximum string length: 255
​
notes
string

Optional notes about the external payment.

Maximum string length: 500

Response

Created.

Represents a payment associated with an appointment.

​
id
string
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,
processing,
authorized,
paid,
failed
​
amount
string<decimal>
required

The amount of this payment.

Pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
Example:

"456.78"

​
guileFeeAmount
string<decimal>
required

The Guile fee charged with this payment.

Pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
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.

​
paymentType
enum<string>

The appointment obligation this payment addresses, when known.

Available options:
authorization,
deposit,
balance
​
authorizationScheduledAt
string<date-time>

When a saved-card authorization hold is scheduled to be placed for this payment.

​
failureReason
enum<string>

The authorization failure reason when a hold attempt fails.

Available options:
declined,
cardUnusable,
processingError,
other
​
providerDeclineCode
string

The provider decline code returned by the payment processor, when one is available.

​
networkAdviceCode
string

The card network advice code returned by the payment processor, when one is available.

​
currencyCode
string

The ISO 4217 currency code for this payment's monetary values.

Required string length: 3
Example:

"USD"

​
tipAmount
string<decimal>

The tip included in the payable total, when one has been selected.

Pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
Example:

"456.78"

​
offHoursFeeAmount
string<decimal>

The off-hours fee included in this payment, when the payment settles that preserved booking component.

Pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
Example:

"456.78"

​
payableTotal
string<decimal>

The full amount due for the appointment, including the selected tip.

Pattern: ^-?(0|[1-9][0-9]*)\.[0-9][0-9]$
Example:

"456.78"

​
paymentProblem
enum<string>

A payment issue requiring follow-up.

Available options:
authorizationRepairFailed
​
paymentToken
string

For external payments, the token representing the payment.

​
externalId
string

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

​
card
object

The card charged for this payment, when Guile recorded the network and last four digits from the payment processor. Omitted for cash or external payments, and when Guile never recorded a card for the charge.

​
originalPaymentId
string

For refund payments, the original payment being refunded.

​
refundReason
string

For refund payments, the reason for the refund.

Maximum string length: 500