Refunds

Refund a completed payment by sending the payment_intent_id and the amount to return. TurnStay routes the refund to the original payment provider automatically.

Create a refund

curl -X POST "https://staging.turnstay.com/api/v1/refund" \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": 12345,
    "billing_amount": 100000,
    "reason": "Guest cancelled booking",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }'

Field	Type	Required	Description
payment_intent_id	integer	Yes	The payment intent to refund.
billing_amount	integer	Yes	Amount to refund in billing currency (minor units).
reason	string	Yes	Why the refund is being issued.
idempotency_key	string	No	Client-generated unique key to prevent duplicate refund submissions.

Refund statuses

A refund moves through these states:

Status	Meaning
INITIALIZED	Refund created, processing started.
PENDING	Waiting for customer bank details (bank deposit refunds only).
APPLIED	Provider confirmed the refund is processed (card refunds).
COMPLETED	Refund finalized and recorded in ledger.
FAILED	Processing error — check the error field.

Card refunds vs bank deposit refunds

Card refunds follow the standard path: INITIALIZED → APPLIED → COMPLETED. The refund goes back to the original card automatically.

Bank deposit refunds require the customer to submit their bank details. The flow is:

1. Refund is created with status INITIALIZED.
2. Customer receives a link to submit their bank account details.
3. Status moves to PENDING while bank details are collected and verified.
4. Once the payout is disbursed and confirmed, the refund is COMPLETED.

Check existing refunds

Before creating a new refund, check if one already exists for the payment intent:

curl -X POST "https://staging.turnstay.com/api/v1/refund/check-existing" \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent_id": 12345
  }'

Idempotency

Use the idempotency_key field to safely retry refund requests. If you send the same key twice, TurnStay returns the existing refund instead of creating a duplicate.