--- title: "Refund a payment" method: POST path: "/payment-sessions/{paymentSessionId}/refunds" tags: ["Payments"] --- # Refund a payment `POST /payment-sessions/{paymentSessionId}/refunds` Use this endpoint to refund an already captured payment session. Unlike voids, which are typically completed in minutes, refunds can take several days to be cleared by the card schemes. ## Path parameters - `paymentSessionId` string, required ## Headers - `Account` string ## Request body - CreateRefundRequestBody - `amount` integer, nullable — The amount to refund in minor digits. Can be omitted when not using partial captures or splits; the remaining amount will be refunded. - `reason` string, nullable — The reason for the refund - `refundPlatformFee` boolean, nullable — A flag to indicate whether the platform fee should be refunded. If the payment amount is fully refunded, the platform fee will be too. If this is a partial refund then the platform fee will be refunded proportionally to the amount being refunded. By default this flag is false. - `splits` object, nullable - `items` SplitPaymentRefundItem[] - `id` string, required — The unique identifier for the split payment to refund. - `amount` integer, nullable — How much to refund from this split payment. If left `null`, we will issue a full refund for the original amount. If this is a partial amount, we will not refund the `fee` unless you specify an explicit amount inside the `fee.amount` field. - `fee` object, nullable - `amount` integer — Specify how much should be refunded from the fee you collected from the split payment. The fee will be refunded too if the total amount in the split payment item is fully refunded and you don't specify this field. - `captureTransaction` object, nullable — Required if you have actioned multiple captures against a single PaymentSession. This must match the Id of a particular capture transaction as returned from the /captures endpoint. Note that the amount to refund cannot exceed the amount you captured for that /captures request. - `id` string — The unique Id of the partial capture transaction ## Response `202` Refund request successfully accepted (Pending / Succeeded / Failed). If the status is `Pending` then the transaction will be completed asynchronously. Listen to the `PaymentSession.refunded` event on your webhook to be notified of the outcome. - PaymentTransaction - `id` string — The unique identifier for the transaction - `paymentSessionId` string — The unique paymentSessionId that this transaction relates to - `amount` integer — The amount of the transaction in minor digits - `currency` string — The ISO currency code - `type` 'Authorization' | 'Void' | 'Capture' | 'Refund' | 'Chargeback' | 'ChargebackReversal' - `status` 'Pending' | 'Failed' | 'Succeeded' - `refundedAmount` integer, nullable — The amount of the transaction that has been refunded, in minor digits. - `platformFee` integer, nullable — Only supplied for 'capture' transactions. The amount of the capture that will be taken and applied to the platform account, in minor digits. - `platformFeeRefundedAmount` integer, nullable — Only supplied for 'capture' transactions. The amount of the capture that has been refunded to the platform account, in minor digits. - `processingFee` integer, nullable — This field is now deprecated. Please use the /balance-transactions endpoint to see the fees paid on these transactions. The processing fee that was taken for this transaction. - `reason` string, nullable — An optional reason to describe this transaction. Typically used for refunds whereby the reason for the refund is recorded. - `captureType` 'Final' | 'NotFinal', nullable — Only supplied for 'capture' transactions. The type of capture. Typically only used for payments that support multi-capture. Once `Final`, any remaining uncaptured amount will be marked as void within 7 days. - `paymentMethod` PaymentSessionPaymentMethod, nullable - `type` 'Card' - `tokenizedDetails` PaymentSessionPaymentMethodTokenizedDetails, nullable — The details of any tokenized payment method used - `id` string — The Id of the tokenized payment method - `stored` boolean — Flag to indicate whether or not the tokenized payment method was stored (against the customer) - `card` object, nullable — Details of the card used - `scheme` 'Visa' | 'Mastercard' | 'Amex' - `last4` string — The last 4 digits of the card used - `binDetails` CardBinDetails, nullable — The specific details obtained from the BIN/IIN of the card. Note that this is not always available. - `issuer` string, nullable — Name of the card issuer - `issuerCountry` string, nullable — The two-character ISO 3166 country code of the card issuer - `fundingType` 'Debit' | 'Credit' | 'Prepaid' | 'DeferredDebit' | 'Charge', nullable — Refers to how money for purchases comes to the card. - `productType` 'Consumer' | 'Corporate', nullable — The category the issuer assigns to the particular card - `wallet` object, nullable — Details of the wallet used (Google Pay / Apple Pay) - `type` 'GooglePay' | 'ApplePay' - `billingAddress` CustomerAddress, nullable - `firstName` string — The first name of the customer - `lastName` string — The last name of the customer - `lineOne` string — First line of the address - `lineTwo` string — Second line of the address - `city` string — The address city/town - `country` string, required — The two-character ISO country code - `postalCode` string, required — The postal code/zip of the address - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code - `checks` PaymentMethodChecks, nullable - `avsResponseCode` string, nullable — The response from Address Verification Service (AVS) that determines the match or partial match of the customer's billing address. Possible values: - A - Partial Match (street address matches, postal/zip code does not match) - B - Partial Match (street address matches, postal/zip code not verified) - C - No Match (street address and postal/zip code not verified) - D - Full Match (street address and postal/zip code match) - F - Full Match (street address and postal/zip code match) - G - Not Supported (address information not verified) - I - No Match (address information not verified) - M - Full Match (street address and postal/zip code match) - N - No Match (neither street address not postal/zip code match) - P - Partial Match (postal/zip code matches, street address not verified) - R - System Unavailable (unable to perform verification) - S - Not Supported (AVS currently not supported by issuer) - U - System Unavailable (address information not verified due to no data from issuer) - W - Partial Match (postal/zip code matches, street address does not match) - X - Full Match (street address and postal/zip code match) - Y - Full Match (street address and postal/zip code match) - Z - Partial Match (postal/zip code matches, street address does not match) - `cvvResponseCode` string, nullable — The response from the check on the Card Verification Value (CVV/CVV2/CVC) Possible values: - M - Match (Visa and MC) - Y - Match (Amex) - N - No Match - P - Not Processed - S - Should be on card - U - Issuer does not participate - `splitPaymentDetail` SplitPaymentDetail, nullable - `items` SplitPaymentItem[] - `id` string — The unique identifier for this split payment item. Note that this will be the id of the `SplitPayment` created once payment is captured. - `accountId` string — The ID of the sub account who will receive this split payment amount in the form of a `SplitPayment`. **Must** be unique, i.e. you cannot have > 1 splits to the same account in your request. - `amount` integer - `fee` object - `amount` integer - `description` string — A short description of this split that will be displayed to the account. - `metadata` object, nullable — The metadata to attach to this part of the split. This will be used to populate `metadata` on the `SplitPayment` once it is subsequently created. - `processingDetail` PaymentTransactionProcessingDetail, nullable - `issuerResponseCode` string, nullable — The response code returned by the issuer. - `authorizationCode` string, nullable — The authorization code returned by the issuer. - `acquirerReferenceNumber` string, nullable — The Acquirer Reference Number (ARN) for the transaction. - `inPersonDetail` InPersonPaymentDetail, nullable - `terminalDetail` InPersonPaymentTerminalDetail - `id` string — The ID of the in-person terminal the payment was processed through - `createdTimestamp` integer — The epoch timestamp (seconds) when the transaction was initiated - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the transaction was last updated ## Other responses - `400` — Invalid request (e.g. invalid refund amount) - `500` — An unexpected error occurred when executing this request --- [API](https://skmtc.net/ryftpay/apis/ryft-payment-api.md) · [All operations](https://skmtc.net/ryftpay/apis/ryft-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ryftpay/ryft-payment-api/versions/a042f64d4305/schema)