> ## Documentation Index > Fetch the complete documentation index at: https://docs.rc.cleverhub.co/llms.txt > Use this file to discover all available pages before exploring further. # Refund Payment > Initiate a refund request on a completed payment with a `received` status. This endpoint processes a refund using the available balance in your account. If there is insufficient balance, you will either receive a top-up notification or need to wait for additional funds from new payments (Payins) to complete the refund. Refunds can be partial or full, depending on the `refund_amount` specified. A reason for the refund is required for tracking and documentation purposes. ## OpenAPI ````yaml /api/openapi/v1-reference.yaml post /v1/payment_requests/refund openapi: 3.0.3 info: title: Payment APIs (AUD only) description: >- ## Introduction The Payment API Solution (AUD) offers developers a comprehensive suite of API services to build innovative AUD payment solutions efficiently. These APIs enable seamless transactions using various payment methods and functionalities, ensuring a robust, reliable, and scalable payment infrastructure tailored for the Australian market. ### Key Features - **Payment Methods**: - **Payment Link**: Supports payments via card and PayID. - **PayID**: Provides instant payments using a unique identifier. - **PayTo**: Enables scheduled or recurring payments. - **BSB/Account Number**: Allows direct bank transfers. - **Payout**: Manage payouts to designated accounts. - **Additional Functionalities**: - **Balance Management**: Real-time balance inquiries and updates. - **Reporting Services**: Generate detailed transaction and payment reports. This documentation provides detailed guidance for integrating these capabilities into your application. termsOfService: https://helloclever.co/terms contact: email: support@helloclever.co version: 1.0.11 servers: - url: https://api.cleverhub.co/api description: Sandbox Environment - url: https://api-merchant.helloclever.co/api description: Production Environment security: [] paths: /v1/payment_requests/refund: post: tags: - AUD PayID summary: Refund Payment description: > Initiate a refund request on a completed payment with a `received` status. This endpoint processes a refund using the available balance in your account. If there is insufficient balance, you will either receive a top-up notification or need to wait for additional funds from new payments (Payins) to complete the refund. Refunds can be partial or full, depending on the `refund_amount` specified. A reason for the refund is required for tracking and documentation purposes. operationId: refundPayment requestBody: required: true content: application/json: schema: type: object required: - payment_request_id - reason properties: payment_request_id: type: integer description: >- The unique identifier for the original payment request that is to be refunded. example: 1 refund_amount: type: number description: > The amount to be refunded. If this is not specified, the refund will default to the total original payment amount. example: 100 reason: type: string description: > The reason for the refund, which must be at least 5 characters long. This is required for record-keeping and can help in cases of partial refunds. example: Partial refund due to customer request responses: '200': description: Refund initiated successfully. content: application/json: schema: type: object properties: refund_payid: type: string description: >- The PayID to which the refund amount should be paid to complete the refund process. example: refund_payid@example.com refund_amount: type: number description: The total amount that was refunded. example: 100 reason: type: string description: The reason provided for the refund. example: Partial refund due to customer request payment_request: $ref: '#/components/schemas/PayIDObject' '400': description: Bad Request '401': description: Unauthorized '422': description: Unprocessable Entity security: - app-id: [] secret-key: [] components: schemas: PayIDObject: type: object properties: id: type: integer description: > A unique identifier assigned to the payment request, used for tracking and referencing purposes within the system. example: 123456 balance_id: type: string description: > The identifier of the balance associated with this payment request, allowing for account management and tracking of specific transactions. example: HDCHJSS name: type: string description: > The name of the individual or entity associated with the payment request. This helps identify the payer or payee involved. example: John Doe request_payid: type: string description: > The PayID generated for the payment request, used to uniquely identify and route the payment to the correct recipient. example: payid123@example.com merchant_name: type: string description: > The name of the merchant managing or handling the payment. This field is useful for recognising the party to whom the payment is being made. example: Merchant Co. gst: type: boolean description: > Indicates whether Goods and Services Tax (GST) applies to the transaction. A value of `true` means GST is included. example: true amount: type: string description: > The amount requested for the payment, excluding any applicable taxes. This field represents the base value of the transaction. example: '100.0' total: type: string description: > The total amount due, including all applicable taxes such as GST. This is the final amount the payer needs to pay. example: '110.0' gst_amount: type: string description: > The portion of the total amount that is attributable to GST. This helps in breaking down the tax components of the payment. example: '10.0' expired_at: type: string format: date-time description: > The expiration date and time of the PayID, indicating until when the PayID is valid for making the payment. example: '2024-12-31T23:59:59Z' external_id: type: string description: > A custom identifier provided for tracking purposes, such as an internal reference or an invoice number. example: custom-id-12345 cashback_amount: type: string description: > The cashback amount, if applicable, that the payer is eligible to receive as part of the transaction. example: '5.0' pay_by: type: string format: date-time description: > The last date by which the payment must be made. This provides a clear deadline for the payer. example: '2024-12-30T23:59:59Z' paid_at: type: string format: date-time description: > The date and time when the payment was successfully completed. This is used for record-keeping and verification. example: '2024-12-25T12:34:56Z' status: type: string enum: - pending - received - expired - return_pending - return_received - return_expired - return_rejected description: | The current status of the payment request. Possible values include: - `pending`: The payment request is still open and awaiting payment. - `received`: The payment has been received. - `expired`: The payment request has expired. - `return_pending`: A return of funds is in process. - `return_received`: Returned funds have been received. - `return_expired`: The return process has expired. - `return_rejected`: The return request was rejected. example: pending description: type: string description: > A description accompanying the payment request, providing additional information such as the purpose of the payment or related invoice details. example: 'Payment for invoice #1234' nonce: type: string description: > A unique value used to validate the transaction, preventing replay attacks and ensuring the integrity of the payment request. example: unique_nonce_string stage: type: string enum: - overpaid - underpaid - unmatched_nonce - null description: > Represents the specific stage within the `pending` status. This value is `null` unless the transaction is flagged for being overpaid, underpaid, or having an unmatched nonce. example: overpaid refund_information: type: object description: > Details about any refunds that are associated with this payment. This includes information about the refund PayID, refund amount, and any reasons provided. properties: refund_payid: type: string description: > The PayID used to top up for a refund, if the refund is needed. This helps identify the source of refund. example: sample@payid.com refund_amount: type: number description: > The amount that is being refunded to the payer. This helps in tracking the value being returned. example: 0.1 request_date: type: string format: date-time description: > The date and time when the refund was requested. This is important for record-keeping and verification purposes. example: '2024-12-31T23:59:59Z' reason: type: string description: > The reason provided for the refund, giving context to the request. This can include reasons such as product issues or cancellation. example: Broken product sender_details: type: object description: > Information about the sender of the payment, including reference details, bank information, and account holder's name. properties: reference: type: string description: > A reference provided by the sender for the transaction, used for identifying the purpose or source of the funds. example: SenderRef123 description: type: string description: > Additional description provided by the sender, adding context to the payment. example: Payment from John Doe bsb: type: string description: > The Bank-State-Branch (BSB) number of the sender, which is used to identify the bank and branch involved in the transaction. example: '123456' account_number: type: string description: > The account number from which the payment is being sent, helping in tracing the source of the payment. example: '987654321' account_name: type: string description: > The name on the account from which the payment is being sent. This helps in verifying the identity of the sender. example: John Doe short_invoice_url: type: string format: uri description: > A shortened version of the invoice URL for convenience. This can be used to quickly share or access the invoice details. Note: this field is deprecated. example: https://short.example.com/invoice/123456 deprecated: true invoice_url: type: string format: uri description: > The full URL of the invoice related to the payment request. This provides access to the detailed invoice online. Note: this field is deprecated. example: https://example.com/invoice/123456 deprecated: true metadata: type: object description: Optional custom metadata to attach to the transaction. example: custom_note: Priority customer securitySchemes: app-id: type: apiKey in: header name: app-id description: | A unique identifier assigned to each application. secret-key: type: apiKey in: header name: secret-key description: | A secure token associated with the `app-id`. ```` ## Related topics - [Refund Payment](/api/cards/refund-payment.md) - [Issue and Manage Card Payments](/developer-reference/api-use-cases/issue-and-manage-cards.md) - [Managing Payins in the Merchant Portal](/portal/payins.md)