Refund a payment
Gives back all that is left of a succeeded payment, or `amount` of it in the payment's minor unit, to the card it was paid with. Answers the payment once the refund is recorded: `status` is `refunded` or `partially_refunded` and `refunded_amount` has grown, and a `refund.succeeded` event goes out. Utopia's fee is not returned, so `net_amount` can fall below zero. A live refund is drawn on your balance in the payment's currency and is refused while that balance does not cover it (`409 INSUFFICIENT_BALANCE`). More than what is left of the payment is refused (`400 AMOUNT_TOO_LARGE`), as is a payment that has not succeeded or is refunded already (`409 NOT_REFUNDABLE`, `ALREADY_REFUNDED`). Some payments can be refunded only in full: one charged in the customer's own currency (`409 FULL_REFUND_ONLY`), and some payments made today, until they settle overnight (`409 NOT_SETTLED`; a full refund is possible at once). When the card processor cannot be reached the refund is not made (`502 REFUND_FAILED`); try again later. The card holder usually sees the money back within a few working days, depending on their bank. Send `Idempotency-Key` so a retried request does not refund twice.
Gives back all that is left of a succeeded payment, or amount of it in the payment's minor unit, to the card it was paid with. Answers the payment once the refund is recorded: status is refunded or partially_refunded and refunded_amount has grown, and a refund.succeeded event goes out. Utopia's fee is not returned, so net_amount can fall below zero.
A live refund is drawn on your balance in the payment's currency and is refused while that balance does not cover it (409 INSUFFICIENT_BALANCE). More than what is left of the payment is refused (400 AMOUNT_TOO_LARGE), as is a payment that has not succeeded or is refunded already (409 NOT_REFUNDABLE, ALREADY_REFUNDED). Some payments can be refunded only in full: one charged in the customer's own currency (409 FULL_REFUND_ONLY), and some payments made today, until they settle overnight (409 NOT_SETTLED; a full refund is possible at once). When the card processor cannot be reached the refund is not made (502 REFUND_FAILED); try again later.
The card holder usually sees the money back within a few working days, depending on their bank. Send Idempotency-Key so a retried request does not refund twice.
Authorization
secretKey Your secret key: sk_live_… or sk_test_….
In: header
Path Parameters
The payment's id, which starts with pay_.
^pay_[0-9a-f]{32}$Header Parameters
Retrying with the same key returns the first response instead of creating a duplicate. 1 to 255 printable ASCII characters (INVALID_IDEMPOTENCY_KEY otherwise), remembered for 24 hours per key's merchant and mode. A replayed answer carries idempotent-replayed: true. The same key with a different body is refused with 422 IDEMPOTENCY_KEY_REUSED; while the first request is still running, 409 IDEMPOTENCY_KEY_IN_USE. A request that failed with a 5xx is not remembered, so it can simply be retried.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/payments/pay_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c/refunds" \ -H "Content-Type: application/json" \ -d '{}'{ "object": "payment", "payment_id": "pay_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "status": "processing", "total_amount": 0, "refunded_amount": 0, "fee_amount": 0, "net_amount": 0, "currency": "AED", "description": "string", "customer": { "customer_id": "cus_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "name": "string", "email": "user@example.com", "phone_number": "string" }, "checkout_session_id": "cks_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "subscription_id": "sub_3f2b8c1e9a4d4e7b8c2a1d5e6f7a8b9c", "billing_reason": "payment", "metadata": { "property1": "string", "property2": "string" }, "livemode": true, "created_at": "2019-08-24T14:15:22Z", "paid_at": "2019-08-24T14:15:22Z"}List payments GET
Lists payments, newest first, including every subscription renewal. Filter by `status`, by the customer who paid, or by the checkout session a payment came from. One page carries `items`, `has_more` and `next_cursor`; pass `next_cursor` back as `cursor` for the next page. A page is read from a fixed point in the list, so payments arriving while you walk it do not shift the pages still ahead of you. Only payments belonging to the key's merchant and mode are listed.
Retrieve a subscription GET
Returns one subscription: its status, what it charges and how often, the card it renews with, when the current period started, when it renews next, and once it has ended, when and why. Grant access while the status is `active` or `on_hold`, and read the subscription after each `subscription.*` event rather than keeping your own copy of the schedule. `next_retry_at` is filled in only while a subscription that Utopia renews is `on_hold`; when the card processor renews it, the processor decides when to retry and this stays null. Only subscriptions belonging to the key's merchant and mode are visible.