--- title: "Refund Payment" method: POST path: "/api/v1/payments/{paymentId}/refund" tags: ["Payments"] --- # Refund Payment `POST /api/v1/payments/{paymentId}/refund` ## Request - Base URL: `https://merchant-api.accruesavings.com` - URL: `https://merchant-api.accruesavings.com/api/v1/payments/{paymentId}/refund` - Auth: none declared. Required headers: `Client-ID`, `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) The refund endpoint can be called on a `Payment` that is in the `Processing` or `Sent` status and has at least one successful capture. It supports partial refunds — the refund amount cannot exceed the captured amount, and the sum of all non-failed refunds cannot exceed the captured amount. Calling the refund endpoint will never change the status of the payment so the status of the payment cannot be used to determine if it has been refunded. When a `Payment` is refunded, an associated `Refund` object is created. The `Refund` object has an independent status representing the refund. The refund endpoint returns the `Refund` object created and can be included in the get payment endpoint. **Idempotency**: The `idempotencyKey` field is required to prevent duplicate refund operations. If a refund with the same key already exists, the existing refund will be returned. **Disbursements**: For pay-by-wallet refunds, you can optionally specify `disbursement` to indicate which counterparties to debit and for how much. The sum of disbursement amounts must equal the refund amount. If `disbursement` is omitted, the system automatically derives proportional disbursements from the original payment's disbursement breakdown. The refund amount is distributed across the same counterparties using their original ratios. For full refunds the derived amounts match the original proportions exactly. ## Path parameters - `paymentId` string, uuid, required: Payment ID ## Headers - `Client-ID` string, uuid, required: The unique identifier of the client making the request. This header is required to retrieve the client-specific configuration and ensure that the response is tailored to the client's settings and permissions. - `Authorization` string, uuid, required: Secure secret to access privileged endpoints. ## Request body - object - `data` RefundPayment, required: RefundPayment - `id` string, uuid, required: Unique identifier for the object. - `type` 'RefundPayment', required - `attributes` object, required - `amount` integer, required: Amount to refund in cents - `idempotencyKey` string, required: A unique key to prevent duplicate refund operations. Must be between 1 and 255 characters. If a refund with the same idempotency key already exists, the existing refund will be returned. - `disbursement` object[]: Optional array of disbursement reversals for pay-by-wallet refunds. Each entry specifies a counterparty to debit and the amount to reverse. The sum of all disbursement amounts must equal the refund amount. When omitted, the system automatically derives proportional disbursements from the original payment's disbursement breakdown. - `counterpartyId` string, uuid, required: The ID of the counterparty to whom the funds are being disbursed. - `amount` integer, required: The total amount charged with a particular payment method, represented in the smallest currency unit (e.g., cents for USD). To obtain the value in dollars, divide by 100. - `remit` boolean: Deprecated. This field is accepted but always treated as `true` regardless of the value provided. All disbursements are remitted directly. Will be removed in a future version. ## Response `200` OK - RefundPaymentResponse - `data` object, required - `id` string, required - `type` 'Payment', required - `relationships` object, required - `paymentIntent` object, required - `data` object, required - `id` string, uuid, required - `type` 'PaymentIntent', required - `links` object, required - `self` string, uri, required - `refunds` object, required - `data` object[], required - `id` string, required - `type` string, required - `captures` object, required - `data` object[], required - `id` string, required - `type` string, required - `links` object, required - `virtualDebitCard` string, required - `meta` object: Optional metadata on the Payment resource. Omitted when no processor payload is attached to the response. - `processor` unknown - `attributes` object, required - `id` string, required - `status` 'Canceled' | 'Created' | 'Failed' | 'Processing' | 'Returned' | 'Sent': The current status of the payment. Each status indicates a specific phase in the payment process, such as waiting for authorization, being processed, or having been successfully completed or canceled. - `amount` integer: The total amount of the payment processed, represented in the smallest currency unit (e.g., cents for USD). To obtain the value in dollars, divide by 100. This amount may differ from the initially intended amount due to adjustments, fees, or additional charges. - `channel` string, nullable: External system identifier used to identify the payment channel. E.g. App Name, Activity ID, Checkout Interface, etc. - `reference` string, nullable: Reference to the data inside an external system. - `disbursement` object[]: Array of disbursements associated with this payment, including counterparty IDs, amounts, and fees. - `counterpartyId` string, uuid, required: The ID of the counterparty to whom the funds are being disbursed. - `amount` integer, required: The total amount charged with a particular payment method, represented in the smallest currency unit (e.g., cents for USD). To obtain the value in dollars, divide by 100. - `fee` integer, required: The fee assigned to this particular disbursement based on the whole payment fee, represented in the smallest currency unit (e.g., cents for USD). To obtain the value in dollars, divide by 100. - `remit` boolean, required: Deprecated. Always returns `true`. All disbursements are remitted directly. Will be removed in a future version. - `charges` object: Charges applied to this payment. - `fee` object: Processing fee details - `amount` integer, required: Fee amount in cents - `type` string, required: Fee type identifier - `rewards` integer: Rewards amount spent from wallet balance, in cents - `deductions` object: Legacy charges breakdown. Use `charges` instead. - `rewards` integer, required: Rewards amount spent from wallet balance, in cents - `fees` integer, required: Processing fees charged, in cents - `expiresAt` string, date-time: The field indicates the date and time until which the payment is valid. After this date, the payment will either be automatically cancelled or completed. - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - `links` object, required - `self` string, required - `included` union[], required - union - Refund: A refund - `id` string, uuid, required: Unique identifier for the object. - `type` 'Refund', required - `attributes` object, required - `status` 'Failed' | 'Pending' | 'Sent' | 'Waiting': The current status of the refund. - `amount` integer: The amount refunded, represented in the smallest currency unit (e.g., cents for USD). To obtain the value in dollars, divide by 100. - `message` string: A human-readable message describing the refund status or outcome. - `reference` string, nullable: Reference inherited from the parent Payment. This is not a direct field on the Refund entity. - `charges` object: Charges applied to this refund. - `fee` object: Processing fee details for this refund - … - `rewards` integer: Rewards amount. Always 0 for refunds (rewards are not applicable to refunds). - `deductions` object: Legacy charges breakdown. Use `charges` instead. - `rewards` integer, required: Rewards amount. Always 0 for refunds. - `fees` integer, required: Processing fees charged for this refund, in cents. Same value as `charges.fee.amount`. - `id` string, uuid - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - object - `id` string, uuid, required: Unique identifier for the object. - `type` 'PaymentIntent', required - `attributes` object, required - `balance` object: Optional wallet balance information - `available` integer, required: Available wallet balance in cents - `eligibleReward` integer, required: Eligible reward amount for this transaction in cents - `upperLimit` integer, required: Maximum checkout amount supported for this purchase, in cents - `billingAddress` object, nullable - `street` string, nullable, required - `street2` string, nullable, required - `city` string, nullable, required - `state` string, nullable, required - `postalCode` string, nullable, required - `country` string, nullable, required - `email` string, email, nullable - `error` 'LinkedAccountUnverified' | 'LinkedAccountDisconnected' | 'LinkedAccountMissing' | 'InsufficientBalance' | 'MissingFullName' | 'WrongEmail' | 'InvalidKycStatus', nullable: Specific error associated with the current invalid status. - `expiresAt` string, date-time, nullable: The datetime at which the payment intent is set to expire. After this time, the intent cannot be promoted to a payment and is considered expired. - `fullName` string, nullable - `phoneNumber` string, nullable - `amount` integer: Total purchase amount in cents. - `reference` string, nullable: Reference to the data inside an external system. - `status` 'Promotable' | 'PromotedToPayment' | 'Invalid' | 'Expired' | 'Canceled': The current status of the payment intent. Each status represents a different stage in the payment intent lifecycle, from creation to completion or cancellation. - `userId` string, nullable - `walletId` string, nullable: The ID of the wallet for which the payment intent is created. - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - `relationships` object, required - `client` object, required - `data` object, required - … - Capture: A capture included in the refund response - `id` string, uuid, required: Unique identifier for the object. - `type` 'Capture', required - `attributes` object, required - `id` string, uuid, required - `method` 'Direct' | 'BankRails' | 'VirtualDebitCard', required: The method used for the capture. - `amount` integer, required: The captured amount in cents. - `externalPayments` object: Optional external payment references. - `reference` string, nullable: Optional reference string. - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - Client: A client included in the refund response - `id` string, uuid, required: Unique identifier for the object. - `type` 'Client', required - `attributes` object, required - `id` string, uuid, required - `allowedOrigins` string[], required: Allowed origins for this client. - `preferredStorage` object, required: Preferred storage type. - `Web` 'localStorage' | 'sessionStorage' - `RN` 'localStorage' | 'sessionStorage' - `merchantId` string, uuid, required: The merchant ID associated with this client. - `merchantName` string, required: The merchant name. - `programName` string: The program name. - `cardClearingTime` 'Instant' | 'TwoDays' | 'ThreeDays' | 'FourDays' | 'FiveDays' | 'Default': Card clearing time. One of Instant, TwoDays, ThreeDays, FourDays, FiveDays, Default. - `achClearingTime` 'Instant' | 'TwoDays' | 'ThreeDays' | 'FourDays' | 'FiveDays' | 'Default': ACH clearing time. One of Instant, TwoDays, ThreeDays, FourDays, FiveDays, Default. - `containerPlacements` object, required: Container placements per Flow (Wallet, PaymentMethods) and Widget (WalletBalance, WalletRewards, WalletPaymentSuccess). Every key is optional. - `Wallet` object[] - … - `PaymentMethods` object[] - … - `WalletBalance` object[] - … - `WalletRewards` object[] - … - `WalletPaymentSuccess` object[] - … - `containerDisplayRules` object, required: Container display rules per Flow and Widget. Every key is optional. - `Wallet` object[] - … - `PaymentMethods` object[] - … - `WalletBalance` object[] - … - `WalletRewards` object[] - … - `WalletPaymentSuccess` object[] - … - `containerIntegrityEffects` object, required: Container integrity effects per Flow and Widget. Every key is optional. - `Wallet` string[] - `PaymentMethods` string[] - `WalletBalance` string[] - `WalletRewards` string[] - `WalletPaymentSuccess` string[] - `copyAdjustments` object, required: Optional copy overrides. - `balanceSuccessIcon` string - `balanceSuccessMessage` string - `rewardsFlowType` 'Delayed' | 'Instant', required: Rewards flow type. One of Delayed, Instant. - `rewardsRateType` 'Savings' | 'Purchase', required: Rewards rate type. One of Savings, Purchase. - `widgetCustomizations` object, required: Partial widget customization overrides. Every field is optional. - `walletIconUrl` string - `togglePosition` 'left' | 'right' - `toggleStyle` 'switch' | 'checkbox' - `showToggleStatus` boolean - `textStyle` 'small' | 'smallSemibold' - `paymentSuccessTitle` string - `paymentSuccessDescription` string - `paymentWalletButtonType` 'button' | 'link' - `paymentWalletButtonText` string - `rewardsBackgroundColor` string - `rewardsCopyColor` string - `balanceBreakdownPadding` 'auto' | 'tiny' | 'small' | 'medium' - `rewardsBadgeSignedOutLabel` string - `rewardProfile` object: Reward profile with percentage levels. - `level1pct` number, required - `level2pct` number, required - `level3pct` number, required - `onBoardingReward` number: Onboarding reward amount. - `purchaseReward` number: Purchase reward amount. - `updatedAt` string, date-time, required - `createdAt` string, date-time, required - `meta` object, required - `message` string, required ## Other responses - `400`: Bad Request. Also returned when the payment does not exist, or cannot be refunded for the requested amount. --- [API](https://skmtc.dev/byaccrue/apis/accrue-merchant-api.md) - [All operations](https://skmtc.dev/byaccrue/apis/accrue-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/byaccrue/apis/accrue-merchant-api/revisions/3e2d97ef2e6e?raw)