> ## Documentation Index > Fetch the complete documentation index at: https://developer.utgl.io/llms.txt > Use this file to discover all available pages before exploring further. # Refund Captured Transaction > **Process a Refund for a Previously Captured Transaction** This endpoint allows merchants to issue **full or partial refunds** for completed transactions. Required parameters: - **`transactionId`**: The UUID of the original captured transaction - **`amount`**: The refund amount (can be less than or equal to original transaction) - **`currency`**: The currency code (must match original transaction) - **`reason`**: The justification for the refund - **`description`**: Additional details about the refund Upon successful processing, a unique **`refundTransactionId`** is returned that can be used to track the refund status. ## OpenAPI ````yaml /merchant/partner-connect/partner-connect.yaml post /partner-connect/transactions/refund openapi: 3.0.2 info: title: Partner Connect API Reference description: > # Partner Connect API Documentation Welcome to the Partner Connect API documentation. This API allows external partners (merchants, service providers) to integrate with our card services for binding customer cards and processing transactions. ## Key Features: - Secure Card Binding: Link customer payment cards to your system securely. - Transaction Processing: Authorize, capture, void, and refund payments using bound cards. ## Notes for API Integration - **Authentication:** Requests must be authenticated using either HTTP Basic Auth or Bearer Token (JWT), as specified in the `securitySchemes`. - **Error Handling:** The API uses standard HTTP status codes. Specific error details are provided in the response body with `code` and `message` fields. Refer to the `components/schemas/ErrorPartnerConnect...` definitions and the specific endpoint `responses` for details on possible errors. - **Idempotency:** Where applicable (e.g., transaction initiation), consider implementing idempotency checks on your side using unique request identifiers if needed, although the API itself may handle idempotency for certain operations like binding initiation. version: '1.0' servers: - url: tbc security: - Basic: [] - Bearer: [] tags: - name: Partner Connect description: >- Endpoints for integrating partner systems with card services, including card binding and transaction processing. paths: /partner-connect/transactions/refund: post: tags: - Transactions summary: Refund Captured Transaction description: > **Process a Refund for a Previously Captured Transaction** This endpoint allows merchants to issue **full or partial refunds** for completed transactions. Required parameters: - **`transactionId`**: The UUID of the original captured transaction - **`amount`**: The refund amount (can be less than or equal to original transaction) - **`currency`**: The currency code (must match original transaction) - **`reason`**: The justification for the refund - **`description`**: Additional details about the refund Upon successful processing, a unique **`refundTransactionId`** is returned that can be used to track the refund status. requestBody: required: true description: >- Requires the `transactionId` of the captured transaction, the `amount` to refund, `currency`, `reason` and a `description` in the request body. content: application/json: schema: type: object required: - transactionId - amount - currency - description - reason properties: transactionId: type: string format: uuid description: Unique identifier of the card. amount: type: number format: float minimum: 0.01 multipleOf: 0.01 description: Requested transaction amount. example: 100 currency: description: Currency code (ISO 4217) of the transaction amount. type: string minLength: 3 maxLength: 3 example: USD description: type: string description: Refund transaction description. example: Partial refund for item X reason: type: string description: Reason for the refund. example: Customer requested responses: '200': description: >- Refund processed successfully. Funds will be returned to the cardholder. The response includes a unique `refundTransactionId`. content: application/json: schema: type: object properties: transactionId: description: >- The unique identifier (UUID) of the original captured transaction that was refunded. type: string format: uuid refundTransactionId: description: >- A unique identifier (UUID) specifically for this refund operation. Useful for tracking. type: string format: uuid status: $ref: '#/components/schemas/PartnerConnectTransactionStatus' description: >- The status of the original transaction after the refund. It becomes `refunded` if fully refunded. If partially refunded, it might remain `captured` or move to a specific partial refund state (behavior depends on system logic - clarify if needed). amountRefunded: description: >- The actual amount refunded in this operation, formatted to 2 decimal places. type: number format: float minimum: 0.01 multipleOf: 0.01 currency: description: Currency code (ISO 4217) of the refunded amount. type: string minLength: 3 maxLength: 3 example: USD refundDate: description: >- The timestamp (ISO 8601 format) when the refund was successfully processed. type: string format: date-time pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}(?::?\d{2})?)$ cardId: description: >- The unique identifier (UUID) assigned to the successfully bound card. **Store this `cardId` securely**, as it is required to reference this card in all subsequent transaction requests (`/verify`, `/purchase`, etc.). type: string format: uuid refId: description: >- A unique transaction identifier provided for the client’s reference. It can be used to track or correlate transactions type: string example: CT6KQDDEC2 example: transactionId: 123e4567-e89b-12d3-a456-426614174000 refundTransactionId: fb1022e5-50d8-4ff8-bfd9-7df68e4541c2 status: refunded amountRefunded: 100 currency: USD refundDate: '2025-03-19T09:46:54.363Z' required: - transactionId - refundTransactionId - status - amountRefunded - currency - refundDate '404': description: >- Transaction Not Found or Invalid State. The `transactionId` does not exist, or the transaction is not in the `captured` state (e.g., not captured, voided, already fully refunded) (`TRANSACTION_NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorPartnerConnectTransactionNotFound' '406': description: >- Refund Failed. The refund could not be processed. This might be because the requested `amount` exceeds the refundable balance (`AMOUNT_EXCEEDS_LIMIT`), or due to downstream processing rules or failures (`REFUND_FAILED`). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorPartnerConnectRefundFailed' - $ref: '#/components/schemas/ErrorPartnerConnectAmountExceedsLimit' '500': $ref: '#/components/responses/InternalServerError' components: schemas: PartnerConnectTransactionStatus: type: string enum: - locked - captured - void - refunded description: > Enum representing the lifecycle status of a Partner Connect transaction: * `locked` - An authorization request was successful. Funds are reserved on the cardholder's account but not yet transferred. This transaction can be captured or released (voided). * `captured` - The previously locked funds have been successfully transferred from the cardholder to the merchant. This transaction can potentially be refunded. * `void` - The previously locked funds have been released back to the cardholder before capture. The authorization is cancelled. * `refunded` - Funds for a previously captured transaction have been returned to the cardholder. ErrorPartnerConnectTransactionNotFound: description: > The transaction was not found or is in an invalid state for the requested operation. Please verify the **transaction ID** and its current status. type: object properties: code: type: string description: Error code, i.e. `TRANSACTION_NOT_FOUND`. default: TRANSACTION_NOT_FOUND message: type: string description: Human-readable error explanation. default: >- No transaction found with the provided transaction ID, or the transaction's current status prevents the requested operation (e.g., trying to capture a non-locked transaction, refunding a non-captured transaction). ErrorPartnerConnectRefundFailed: description: > The refund transaction could not be processed due to processing issues or limitations. Please retry the refund or contact support if the issue continues. type: object properties: code: type: string description: Error code, i.e. `REFUND_FAILED`. default: REFUND_FAILED message: type: string description: Human-readable error explanation. default: >- The refund could not be processed due to downstream system limitations or processing rules (e.g., refund period expired). Please retry later or contact support if the issue persists. ErrorPartnerConnectAmountExceedsLimit: description: > The requested amount exceeds the allowable limit. For captures, it must not exceed the **authorized amount**. For refunds, it must be within the **refundable range** after previous transactions. type: object properties: code: type: string description: Error code, i.e. `AMOUNT_EXCEEDS_LIMIT`. default: AMOUNT_EXCEEDS_LIMIT message: type: string description: Human-readable error explanation. default: >- The requested amount exceeds the allowable limit. For captures, it cannot exceed the authorized amount. For refunds, it cannot exceed the net captured amount (captured minus previous refunds). responses: InternalServerError: description: >- Internal Server Error. A server error occurred. Please try again later; if the problem persists, contact support. content: application/json: schema: type: object properties: code: type: string description: Error code, i.e. `INTERNAL_SERVER_ERROR`. default: INTERNAL_SERVER_ERROR message: type: string description: A brief message indicating a server-side error. default: Your request could not be processed due to a server error. securitySchemes: Basic: type: http scheme: basic Bearer: type: http scheme: bearer bearerFormat: JWT ````