RefundBooking

POST

/wink.partner.v1.Booking/RefundBooking

const url = 'https://example.com/wink.partner.v1.Booking/RefundBooking';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"bookingId":"example","idempotencyKey":"example","reason":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/wink.partner.v1.Booking/RefundBooking \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "bookingId": "example", "idempotencyKey": "example", "reason": "example" }'

Immediately refund one booking

Full refund inside the configured immediate-refund window. MOVES MONEY, so idempotency_key is REQUIRED with the same semantics as CreateBooking — a retried refund is a double refund.

Returns NOT_FOUND for an unknown or other-agency booking, and FAILED_PRECONDITION when the booking is outside the immediate-refund window or already refunded.

Authorizations

oauth2ClientCredentials

Request Body^required

application/json

Request for RefundBooking.

object

bookingId

string

idempotencyKey

Idempotency key. REQUIRED — a retried refund is a double refund.

string

reason

Why the refund is being issued. Recorded against the booking.

string

Example^generated

{
  "bookingId": "example",
  "idempotencyKey": "example",
  "reason": "example"
}

Responses

200

The RPC completed with gRPC status OK.

application/json

Response for RefundBooking.

object

booking

The booking after the refund has been applied. Read refund.status: a PENDING refund is settling normally and must NOT be retried.

object

bookingId

Wink’s identifier for this booking.

string

bookingCode

The human-facing reference shown to the traveller, e.g. on the confirmation email.

string

groupId

Present when this booking was made as part of a group; RefundBookings operates on this value.

string

status

Where the booking is in its lifecycle.

LIFECYCLE ONLY — this does NOT report refunds. BOOKING_STATUS_PARTIALLY_REFUNDED and BOOKING_STATUS_FULLY_REFUNDED are retained for bookings written before the lifecycle and refund axes were separated, and are never emitted for anything refunded after that. They were always lossy: a refund settling used to overwrite a cancellation here, so only one of the two facts survived. Read refund (field 14) for whether money came back and how much; a refunded booking that was not cancelled now correctly reports BOOKING_STATUS_PAYMENT_SUCCEEDED here.

string

Allowed values: BOOKING_STATUS_UNSPECIFIED BOOKING_STATUS_INITIALIZED BOOKING_STATUS_TEST_PAYMENT_SUCCEEDED BOOKING_STATUS_PAYMENT_SUCCEEDED BOOKING_STATUS_PAYMENT_FAILED BOOKING_STATUS_FAILED BOOKING_STATUS_CANCELLED

creation

How the booking came to exist.

string

Allowed values: BOOKING_CREATION_TYPE_UNSPECIFIED BOOKING_CREATION_TYPE_NORMAL BOOKING_CREATION_TYPE_TEST BOOKING_CREATION_TYPE_FAILED

createdAt

When the booking was created. ISO-8601 instant, UTC.

string

currencyCode

ISO 4217 currency every monetary field on this message is denominated in. This is the SOURCE currency — the one the property settles in — which is not necessarily the one the traveller was shown. See the note on net_total_sales_amount.

string

property

The property and stay.

object

propertyId

string

name

string

address

A postal address.

object

address1

Street line 1.

string

address2

Street line 2, when the property supplies one.

string

state

State, province or region.

string

postalCode

Postal or ZIP code.

string

city

City name.

string

countryCode

ISO 3166-1 alpha-2 country code, e.g. “TH”.

string

country

Country name in the requested language.

string

fullAddress

The full address pre-formatted for display, newline-free.

string

phone

Direct contact for the property, for when the agency needs to call about a booking.

string

email

string

timeZone

IANA zone, e.g. “Asia/Bangkok”. Check-in and check-out below are LOCAL to the property, so without this an agency cannot tell whether a same-day cancellation is still same-day.

string

stay

The stay itself.

object

checkIn

Local dates at the property, ISO-8601 (YYYY-MM-DD).

string

checkOut

string

nights

Nights between them, precomputed so nobody has to reimplement the date arithmetic.

integer format: int32

roomTypeName

What was booked.

string

ratePlanName

string

quantity

How many rooms of the above, and who is in each.

integer format: int32

adults

integer format: int32

childAges

One entry per child, carrying that child’s age at check-in. Ages drive pricing, so an empty list means no children rather than unknown ages.

Array<integer>

booker

Who booked it, and who is staying. Frequently the same person, and deliberately still two fields: an agency books on behalf of a traveller far more often than not.

object

firstName

string

lastName

string

email

string

phone

string

guest

A person on the booking. Deliberately not the platform’s user model: an agency needs to contact somebody about a stay, not to know their account.

object

firstName

string

lastName

string

email

string

phone

string

earnings

What the agency earns and what the sale was worth.

object

netTotalSalesAmount

Net sale value in currency_code, summed across SALE-type beneficiaries.

The SOURCE currency, meaning the one the property settles in. A booking sold in one currency and settled in another carries an exchange spread, and that spread is intentional platform behaviour — do not reconcile this against what the traveller was charged and expect equality.

string format: int64

netAmount

Net amount attributable to the booking after fees, in currency_code.

string format: int64

commissionPercent

The agency’s commission on this booking, as a percentage at booking time. Percentages rather than amounts because that is how they are agreed and how they survive a partial refund.

string

agencyFeePercent

The agency’s own agency-fee percentage at booking time.

string

commissionPercentAfterRefund

Commission percentage restated after any refund. Equal to commission_percent until something is refunded, and the value to reconcile against once something is.

string

cancellation

Present once cancelled.

object

cancelledAt

ISO-8601 instant, UTC.

string

reason

Free text supplied by whoever cancelled.

string

source

Who cancelled. An agency cancelling on the traveller’s behalf and a property cancelling on the agency are different conversations.

string

Allowed values: CANCELLATION_SOURCE_UNSPECIFIED CANCELLATION_SOURCE_PROPERTY CANCELLATION_SOURCE_GUEST CANCELLATION_SOURCE_ADMIN CANCELLATION_SOURCE_AGENT CANCELLATION_SOURCE_ACQUIRER CANCELLATION_SOURCE_SALES_CHANNEL CANCELLATION_SOURCE_SYSTEM

type

The classification the cancellation was filed under, which is not the same thing as reason: this is the closed list the platform reports on, that is what a human typed.

string

Allowed values: CANCELLATION_TYPE_UNSPECIFIED CANCELLATION_TYPE_DUPLICATE CANCELLATION_TYPE_CANCELLATION CANCELLATION_TYPE_NO_SHOW CANCELLATION_TYPE_CC_INVALID CANCELLATION_TYPE_CC_INSUFFICIENT CANCELLATION_TYPE_DISCRETIONARY

refund

Present once any refund exists, whether from a cancellation or an immediate refund.

object

amount

Amount returned, in currency_code minor units. This is the SOURCE amount — what the property settles — matching every other monetary field on this message.

string format: int64

requestedAt

When the refund was requested, and when it actually settled. processed_at is empty while the status is PENDING or REQUIRES_ACTION, which is the honest answer: it has not been processed yet.

string

processedAt

string

status

Where a refund has got to. Mirrors the domain’s BookingRefundStatus.

REFUND_STATUS_PENDING: Requested and settling. NOT a failure, and NOT to be retried — retrying a PENDING refund is how you refund twice.
REFUND_STATUS_CANCELED: Spelled with one L, matching the payment processor and the domain enum.
REFUND_STATUS_REQUIRES_ACTION: Needs intervention before it can settle; not terminal.

string

Allowed values: REFUND_STATUS_UNSPECIFIED REFUND_STATUS_PENDING REFUND_STATUS_SUCCEEDED REFUND_STATUS_CANCELED REFUND_STATUS_REQUIRES_ACTION REFUND_STATUS_FAILED

reason

Why it was issued, from the closed list, plus whatever free text accompanied it.

string

Allowed values: REFUND_REASON_UNSPECIFIED REFUND_REASON_DUPLICATE REFUND_REASON_FRAUDULENT REFUND_REASON_REQUESTED_BY_CUSTOMER REFUND_REASON_GUEST_COMPLAINT REFUND_REASON_GUEST_BOOKED_INCORRECT_DATE REFUND_REASON_GUEST_SICK REFUND_REASON_OVERBOOKING REFUND_REASON_EMERGENCY REFUND_REASON_FLIGHT_CANCELLED REFUND_REASON_DEATH_IN_FAMILY REFUND_REASON_OTHER REFUND_REASON_EXPIRED_UNCAPTURED_CHARGE REFUND_REASON_AVAILABILITY_CHECK_FAILED

description

string

receiptUrl

Processor-hosted receipt for the traveller, when one exists. Published because an agency fielding “where is my money” needs something to forward; the processor’s refund id and fee do not appear here for the same reason no other payment plumbing does.

string

comment

Free text captured at booking time.

string

specialRequests

string

earlyCheckInCharge

Charges that apply outside the room rate — early check-in, late check-out and anything the property adds. has_additional_charges is the cheap check; additional_charges_summary is the human-readable detail when it is true.

string format: int64

lateCheckOutCharge

string format: int64

hasAdditionalCharges

boolean

additionalChargesSummary

string

paymentType

How the traveller paid.

string

Allowed values: PAYMENT_TYPE_UNSPECIFIED PAYMENT_TYPE_STRIPE PAYMENT_TYPE_AGENT

customizationId

The white-label configuration this booking was made through. The id only — the configuration itself is the agency’s own setup and is managed elsewhere, not published here.

string

statusHistory

Status changes in order, oldest first. Enough to answer “when was this cancelled” without a support ticket.

Array<object>

One lifecycle transition.

object

status

Where a booking is in its lifecycle.

Mirrors the domain enum exactly. PAYMENT_SUCCEEDED is the “booked and paid” state — there is no separate CONFIRMED, and no COMPLETED: a stay that has happened is still PAYMENT_SUCCEEDED.

BOOKING_STATUS_INITIALIZED: In flight. Never returned by this API — see GetBooking.
BOOKING_STATUS_TEST_PAYMENT_SUCCEEDED: Paid against a test payment method. Returned so an agency can tell its own test bookings apart from real ones rather than discovering the difference in a reconciliation.
BOOKING_STATUS_PAYMENT_SUCCEEDED: Booked and paid. The normal terminal state for a stay that goes ahead.
BOOKING_STATUS_FAILED: Never returned: failed bookings are excluded from every response on this service.

string

changedAt

string

idempotentReplay

True when this response replayed an earlier call. Nothing was refunded again.

boolean

Example

{
  "booking": {
    "status": "BOOKING_STATUS_UNSPECIFIED",
    "creation": "BOOKING_CREATION_TYPE_UNSPECIFIED",
    "cancellation": {
      "source": "CANCELLATION_SOURCE_UNSPECIFIED",
      "type": "CANCELLATION_TYPE_UNSPECIFIED"
    },
    "refund": {
      "status": "REFUND_STATUS_UNSPECIFIED",
      "reason": "REFUND_REASON_UNSPECIFIED"
    },
    "paymentType": "PAYMENT_TYPE_UNSPECIFIED",
    "statusHistory": [
      {
        "status": "BOOKING_STATUS_UNSPECIFIED"
      }
    ]
  }
}

RefundBooking

Authorizations

Request Bodyrequired

Examplegenerated

Responses

200

Example

Request Body^required

Example^generated