> ## Documentation Index > Fetch the complete documentation index at: https://docs.vindicia.com/llms.txt > Use this file to discover all available pages before exploring further. # List Retain Refunds > Returns an array of Transactions that have been refunded based on parameters. ### Accepts None ### Returns JSON - A list array with a data property that contains an array of up to limit number of Transactions, starting after the specified `starting_after` Transaction (or ending before the specified `ending_before` Transaction). Each entry in the array is a full Transaction object. If no more Transactions are available, the resulting array will be empty. This request should never throw an error. Available query parameters are listed below. If you specify no parameters: * `end_timestamp` default is the current Retain system time (UTC). * `start_timestamp` default is the `end_timestamp` minus one day (that is, the last one day). * You can specify `status` and/or `limit` parameters to further filter results. If only the `start_timestamp` is specified, the `end_timestamp` default is the `start_timestamp` plus one day. If only the `end_timestamp` is specified, the `start_timestamp` default is the `end_timestamp` minus one day. If `transaction_id`, `subscription_id`, or `account_id`, are specified: * `start_timestamp` and `end_timestamp` are ignored. * Only those Transactions that have been refunded AND are associated with the specified Transaction, Subscription, or Account identifier are returned If multiple parameters are specified, only the highest precedence filter is applied. The order followed is: 1. `start_timestamp`, `end_timestamp` 2. `transaction_id` 3. `subscription_id` 4. `account_id` `status` is a secondary filter applied to status of refunds that can be used with any of the above parameters and their respective defaults (if any). ## OpenAPI ````yaml /portal/retainAPILatest.yaml get /retain/refunds openapi: 3.0.2 info: title: Vindicia Retain (REST) OpenAPI description: |2- # Vindicia Retain OpenAPI Vindicia Retain OpenAPI follows Representational State Transfer (REST) and is a public API that uses HTTP protocols. Vindicia created this API definition for technical readers implementing the API. You can download the OpenAPI YAML and use it for your integration. license: name: Copyright 2024, Vindicia, Inc. url: https://www.vindicia.com version: '2024.06' servers: - url: https://virtserver.swaggerhub.com/Amdocs_Media/Retain_API/2024.06 description: SwaggerHub API Auto Mocking - url: https://api.staging.us-west.vindicia.com description: Development server - url: https://api.us-west.vindicia.com description: Staging server variables: fqdn: default: api.staging.us-west.vindicia.com enum: - api.staging.us-west.vindicia.com - api.us-west.vindicia.com - virtserver.swaggerhub.com/Amdocs_Media/Retain_API_WIP version: default: v1 enum: - v1 - v2 security: - basicAuth: [] - bearerAuth: [] - cookieAuth: [] tags: - name: Retain Transactions - name: Retain Refunds paths: /retain/refunds: get: tags: - Retain Refunds summary: List Retain Refunds description: >- Returns an array of Transactions that have been refunded based on parameters. ### Accepts None ### Returns JSON - A list array with a data property that contains an array of up to limit number of Transactions, starting after the specified `starting_after` Transaction (or ending before the specified `ending_before` Transaction). Each entry in the array is a full Transaction object. If no more Transactions are available, the resulting array will be empty. This request should never throw an error. Available query parameters are listed below. If you specify no parameters: * `end_timestamp` default is the current Retain system time (UTC). * `start_timestamp` default is the `end_timestamp` minus one day (that is, the last one day). * You can specify `status` and/or `limit` parameters to further filter results. If only the `start_timestamp` is specified, the `end_timestamp` default is the `start_timestamp` plus one day. If only the `end_timestamp` is specified, the `start_timestamp` default is the `end_timestamp` minus one day. If `transaction_id`, `subscription_id`, or `account_id`, are specified: * `start_timestamp` and `end_timestamp` are ignored. * Only those Transactions that have been refunded AND are associated with the specified Transaction, Subscription, or Account identifier are returned If multiple parameters are specified, only the highest precedence filter is applied. The order followed is: 1. `start_timestamp`, `end_timestamp` 2. `transaction_id` 3. `subscription_id` 4. `account_id` `status` is a secondary filter applied to status of refunds that can be used with any of the above parameters and their respective defaults (if any). operationId: getRefunds parameters: - name: start_timestamp in: query description: >- A date-time parameter (as defined by RFC 3339), allowing to filter for a time range. Enter the time of the Transaction submission to Retain that you'd like to see. Defaults to Retain system current date and time minus 1 day. Range with end_timestamp cannot exceed 31 days. schema: type: string format: date-time nullable: true example: '2017-07-21T17:32:28.000Z' - name: end_timestamp in: query description: >- The date-time parameter, (as defined by RFC 3339, section 5.6) allowing to filter for a time range. Enter the date range closing time until which Transactions were submitted to Retain. Defaults to `timestamp` + 1 day. Range with start_timestamp cannot exceed 31 days. schema: type: string format: datetime example: '2017-07-21T17:32:28.000Z' - name: account_id in: query description: >- Merchant's unique identifier for Account/customer related to a submitted Transaction. schema: type: string - name: subscription_id in: query description: >- Merchant's unique identifier for Subscription related to a submitted Transaction. schema: type: string - name: transaction_id in: query description: >- Identifier of Transaction to retrieve. {transaction_id} can be either: - The Merchant supplied identifier of a transaction that failed billing in the Merchant's billing system (aka a 'Failed' transaction identifier) - The Retain generated identifier of a retry transaction (either successful or declined) schema: type: string - name: status in: query description: |- Filters the list of transactions fetched by refund status. Can be: - Error - Complete - Processing required: false style: form explode: true schema: type: array items: type: string enum: - Error - Complete - Processing - name: limit in: query description: |- A limit on the number of objects to be returned, between 1 and 100. If set to greater than 100, the value is set to 100. required: false schema: maximum: 100 minimum: 1 type: integer format: int32 default: 20 - name: starting_after in: query description: >- A cursor for use in pagination. `starting_after` is an object **id** that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. schema: type: string - name: ending_before in: query description: >- A cursor for use in pagination. `ending_before` is an object **id** that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. schema: type: string responses: '200': description: List of Transactions with pagination links content: application/json: schema: $ref: '#/components/schemas/inline_response_200_1' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/inline_response_400' '403': description: Forbidden '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/inline_response_404' '405': description: Method not allowed '500': description: >- The Vindicia server encountered an internal error. That error could occur for various reasons, the most common being an incorrectly populated input object, especially when you are making the call from a client library whose language does not support strict data-type checking. For resolution, especially during the development phase, contact Vindicia Technical Support. '503': description: >- A Vindicia back-end service, such as a database, is unavailable. Retry your call later. components: schemas: inline_response_200_1: type: object properties: object: type: string enum: - List data: type: array items: $ref: '#/components/schemas/refund_transaction' url: type: string description: The query string provided in the request next: type: string description: >- The route (partial URL) to the next Transaction object (string to select the “next”); included id should match that of the last object returned here. previous: type: string description: >- The route (partial URL) to the previous Transaction object (string to select the “previous”); included id should match that of the first object returned here. total_records: type: integer description: Integer count of the number of items in the returned list. inline_response_400: type: object properties: code: type: string example: RET400 message: type: string example: 'Invalid parameter: ' inline_response_404: type: object properties: code: type: string example: RET0404 message: type: string example: No matching results found refund_transaction: type: object properties: vid: $ref: '#/components/schemas/vid' id: maxLength: 128 type: string description: >- Merchant-specified identifier for the submitted Transaction, Payment Method, Account, or Subscription. You use it to retrieve the results of the Retain processing for submitted transactions. During the transaction capture process, Retain creates additional transactions and stores their identifiers in the {retain_transaction_id} field. All generated transactions are linked to the merchant-submitted identifiers. example: TX12345678 timestamp: type: string description: >- ISO-8601:2019 formatted string indicating the date and time of transaction processing time. For Merchant submitted transactions this is the date and time the transaction failed from the Merchant's billing system. For Retain+ generated transactions, this is the date and time the retry transaction, identified by {retain_transaction_id}, was processed. format: date-time example: '2020-05-18T20:39:03.000Z' amount: minimum: 0 exclusiveMinimum: true type: number description: Total amount of the transaction, as a decimal. Must be positive. format: decimal example: 21.64 partial_amount: minimum: 0 exclusiveMinimum: true type: number description: >- Total amount of the transaction if a partial amount authorization was received, as a decimal. Must be positive. format: decimal readOnly: true example: null currency: $ref: '#/components/schemas/currency' status: $ref: '#/components/schemas/transaction_status' division_number: type: string description: >- The Merchant\'s division or group with their payment processor, which this transaction is associated with. PaymenTech refers to this as the division number, Litle as the report group, etc. example: '349641' retain_transaction_id: type: string description: >- Unique identifier generated by Vindicia during Retain processing this transaction after receiving a request via `POST /retain/transactions`. readOnly: true refunds: type: array description: A readOnly array of Retain refund objects items: $ref: '#/components/schemas/refund' refundable_amount: type: number description: Total amount of all refunds processed for this transaction format: decimal readOnly: true example: 21.64 processor_transaction_id: type: string description: >- Identifier in the payment provider's system for a transaction. Commonly used to reconcile transactions with transactions recorded in the payment provider's system. account: description: >- Details of the Merchant's customer associated to this transaction and subscription. allOf: - $ref: '#/components/schemas/account' subscription: description: >- Details of the recurring billing agreement between the Merchant and the Customer (aka subscription) associated with this transaction. allOf: - $ref: '#/components/schemas/subscription' previous_billing_count: type: integer description: >- The number of previous successful billings associated with the subscription. payment_method: $ref: '#/components/schemas/payment_method' metadata: $ref: '#/components/schemas/metadata' next_activity: type: string description: >- RFC-3339 full-date of next retry. Null if no additional retry is scheduled. format: date readOnly: true example: '2022-10-08T00:00:00.000Z' billing_descriptor: type: string description: >- Optional string that should be displayed on a customer's billing statement when they are charged. Support for this string and its allowable format and length depends on payment processor. Please consult Vindicia contact for assistance. auth_code: type: string description: Response code from the payment provider for this transaction. example: '530' avs_code: maxLength: 8 type: string description: >- AVS response code. When reporting a transaction, if AVS code is received as a string along with the authorization code (i.e., 'Y:2341234234' or 'Y-2341234234') copy directly into this field. If AVS code is received separaetly from the authorization code, concatenate them with a colon as a separator as in the first example. example: Y:2341234234 cvn_code: maxLength: 8 type: string description: >- CVN response code. When reporting a transaction, if CVN code is received as a string along with the authorization code (i.e., 'M:2341234234' or 'M-2341234234') copy directly into this field. If CVN code is received separaetly from the authorization code, concatenate them with a colon as a separator as in the first example. example: M:2341234234 auth_code_description: type: string description: >- Vindicia interpreted Payment Provider Authorization Response value Soft Failure or, Hard Failure nullable: true readOnly: true enum: - Soft Failure - Hard Failure payment_network_transaction_id: type: string description: >- Transaction ID for the Transaction that was generated to initiate a subscription.This is the Customer Initiated Transaction that must be referenced in later recurring Merchant Initiated Transactions. Payment processors require this value if it exists. retry_number: type: integer description: >- Indicates the billing attempt for the submitted Transaction in a given Billing Period. - 0 - Index originally assigned to the submitted Transaction. - 1 - First retry for the Transaction in the given Billing Period. readOnly: true example: 1 forced_deposit: type: boolean description: >- Indicates transactions that have been captured without prior authorization. readOnly: true example: false description: Retain Transaction object. vid: maxLength: 40 type: string description: >- Vindicia Globally Unique Identifier (GUID) generated for the merchant-submitted Transaction ID or Refund ID for this object. Vindicia creates this identifier to insure global uniqueness within Retain, and provides it for Merchants who don't track their own internal object identifiers. The 'id' field of the object is generally preferred over this field. readOnly: true example: 659649a98f9b2c688b6217b3c642e1f3262a3427 currency: maxLength: 3 type: string description: |- ISO 4217 currency code (see https://www.xe.com/iso4217.php). Defaults to USD if not specified. example: USD default: USD transaction_status: type: string description: >- Status of the last retry attempt of the submittted Transaction or "Failed" if retry attempts have not yet started. When Transactions are submitted for retry processing, `status` MUST be set to Failed. enum: - Authorized - Captured - Settled - Refunded - Failed - Cancelled - Void - In Retry - Partially Refunded - Stopped - Refund Requested - Stop Requested refund: required: - id type: object properties: vid: description: Vindicia generated GUID for this Refund object. readOnly: true example: f147870b2c86a00fb1264fb64c0a8b58fcd95b4d allOf: - $ref: '#/components/schemas/vid' id: type: string description: Merchant-specified identifier for a Refund object. example: C12345678 amount: type: number description: A decimal representation of a monetary amount for the refund. format: decimal example: 21.64 status: type: string description: |- Status of the refund. - Reported—refund has been issued but has not been processed by the payment processor/issuer. - Processing—refund call has been requested for a transaction that has not yet been captured. The refund will start processing after capture (refunds are batched and sent daily). - Failed—payment processor has rejected the refund. - Completed—refund has been sent and processed by payment processor. readOnly: true example: Completed enum: - Processing - Completed - Failed timestamp: type: string description: >- ISO-8601:2019 formatted string indicating the date and time of the refund. For Merchant submitted transactions this is the date and time the transaction failed from the Merchant's billing system. For Retain+ generated transactions, this is the date and time the retry transaction, identified by {retain_transaction_id}, was processed. format: date-time readOnly: true example: '2023-02-16T20:39:03.000Z' account: required: - id type: object properties: vid: description: Vindicia GUID for a specific Account/customer object. readOnly: true allOf: - $ref: '#/components/schemas/vid' id: maxLength: 128 type: string description: >- Merchant's unique identifier for Account/customer related to the submitted Transaction. example: Cust-2125551212 external_id: maxLength: 128 type: string description: >- An additional unique identifier for this Account. API calls can use either the 'vid', the 'id', or this field to uniquely reference a specific Account. Best practice is to use this field when there are two external (non-Vindicia) systems in use using two different identification schemes for the same customer. Note: Uniqueness or null of 'external_id' is enforced within a Merchant's data by the Vindicia system. Attempting to create an Account with the existing 'external_id' returns 'Failed to update Account'. example: asdf1234 email: type: string description: Email address for this Customer. format: email example: foo@example.com description: Vindicia Retain Account/customer object. subscription: required: - id type: object properties: id: maxLength: 128 type: string description: >- Merchant-specified identifier for the subscription associated with a Retain Transaction. example: Sub-2125551212 starts: type: string description: >- ISO-8601 format datetime string (YYYY-MM-DDThh:mm:ss) of the first successful billing associated with the subscription. format: datetime example: '2022-05-15T18:24:05.000Z' affiliate: description: >- Merchant's identifier for the affiliate that submitted this transaction, if any. allOf: - $ref: '#/components/schemas/id' sub_affiliate: description: >- Merchant's identifier for the sub-affiliate that submitted this transaction. Allows for finer tracking of affiliate programs. allOf: - $ref: '#/components/schemas/id' description: >- A sub-set of a Subscribe Subscription object used by Retain to capture recurring billing details. payment_method: required: - credit_card - id properties: vid: description: Vindicia GUID for a specific PaymentMethod object readOnly: true allOf: - $ref: '#/components/schemas/vid' id: type: string description: >- Merchant identifier for a payment_method object. When providing a tokenized credit card, provide the token value here. The length of this attribute (number of characters) must be within a range acceptable to your payment provider. For example, Worldpay limits this value to 25 characters. example: XY-0266667018640 account: $ref: '#/components/schemas/account' account_holder: maxLength: 255 type: string description: Full name of the account holder from the credit card. example: Lily Munster billing_address: type: object description: >- Physical address for this PaymentMethod. Should match the address on file with the issuing bank. allOf: - $ref: '#/components/schemas/address' is_tokenized: type: boolean description: >- If using tokenization with the payment provider, provide the token in the `payment_method.id` field:\n - Set `is_tokenized` to true\n - The `credit_card.account`is used to hold the 6-8 digit BIN number. - The `credit_card.account` and `credit_card.expiration` fields are optional\n else\n - Set `is_tokenized` to false - The `credit_card.account` and `credit_card.expiration` fields are required example: false default: false type: description: >- Type of this PaymentMethod object. Credit cards are the ONLY method of payment supported by Retain. This field auto-populated by Retain. readOnly: true default: CreditCard credit_card: type: object description: >- credit_card object for this payment_method object for this payment_method allOf: - $ref: '#/components/schemas/credit_card' primary: type: integer description: >- Sets the payment_method to be the primary/default payment method for the Account. Vindicia Retain uses the Primary/default payment method first, then attempts to use the remaining eligible payment method. default: 1 description: >- The payment_method object provides information about the credit card to use for processing failed transactions submitted to Vindicia Retain for recovery. These are the means by which a customer pays for purchases. metadata: type: object description: >- Metadata is a free-form object that contains are sets of key-value pairs for storing additional, structured information on objects. This object is used to store a list of arbitrary keys, created and associated with a text string values. These key-value pairs store custom data for internal tracking or correlation purposes. Vindicia may also use metadata to store additional, read-only data for system defined purposes. The metadata field supports key-value pairs with the following limitations: * Keys are limited to 256 characters * Keys can be any string that is needed, except only Vindicia keys can be prefixed with 'vin:' * Values are limited to 1024 characters In some cases, metadata from one object is inherited automatically by another from which it is derived. For example, metadata on Subscriptions and SubscriptionItems are inherited by Transactions and TransactionItems, respectively generated for that Subscription. id: maxLength: 128 type: string description: A Merchant unique identifier for an object. example: Sub-2125551212 address: type: object properties: line1: maxLength: 255 type: string description: Address line 1. example: 1313 Mockingbird Ln. line2: maxLength: 255 type: string description: Address line 2. example: Floor 13 line3: maxLength: 255 type: string description: Address line 3. example: Suite 13 city: maxLength: 64 type: string description: City. example: Mockingbird Heights county: maxLength: 64 type: string description: County. example: San Bernardino district: maxLength: 255 type: string description: >- District (i.e., state or province). A free-form string of 255 or fewer characters. example: CA postal_code: maxLength: 255 type: string description: >- Postal code (i.e., ZIP code). A free-form string of 255 or fewer characters. example: '92415' country: maxLength: 2 type: string description: Country. The ISO 3166-1 alpha-2 code for the country. example: US credit_card: type: object properties: account: type: string description: >- The credit card account used when billing the Transaction. If tokenization is used with a specific credit card (see `is_tokenized` field), then populate this field with the 6-8 digit BIN. When creating Transactions that are not being retried by Retain, only a masked account that provides the 6-8 digit BIN, and the last 4 digits is necessary. For example, 4111111111111111 would be sent as 411111xxxxxx1111. - When submitting a masked account, you should also use the `credit_card.account_hash` field to provide the SHA1 hash of the masked account. - When submitting transactions using the full account number, Vindicia Retain calculates the SHA1 hash. example: | -----BEGIN PGP MESSAGE----- Version: Crypt::OpenPGP 1.12 hIwDSPki6gFMdzcBBACbOQMTtfNXNwzzbNGb2qRCYEuGZ4PQP8+MIdHb7+v56O9R 9q0nTczets0IBnxktypGLR/yoy7MDVvZ1xBK7pCEM3PDxvqWzg4YxZ0pri9NZwYi HYNxjurmU2jeL9vcgl96w1pbeBcSXxa6xgpfFidLADVaADn7+1nprR8LblUZsKQi 4FfULminxVaqlr/yLXO2qjSHxvhb62JXqS9RnjDq3Zxf+A== =X7h1 -----END PGP MESSAGE----- account_hash: type: string description: >- The SHA1 hash of the full account number. For example, the SHA1 hash of 4111111111111111 is: 68bfb396f35af3876fc509665b3dc23a0930aab1. Any non-numeric characters should be removed prior to hashing. If you provide the full account number, you can leave this field blank - the hash is then calculated by Vindicia. If tokenization is used, `payment_method.id` is used for the token,`credit_card.account`should be used for the BIN, this field is then optional. example: c8958779c12837ffec0520eac5c1f61db88bb5f4 expiration_date: type: string description: >- Expiration date of the credit card forrmatted as 'YYYYMM'. For example, July, 2008 should be sent as '200807'. No validation is performed to check that this date is in the future. If tokenization is used with a credit card then this field is optional. example: '202204' account_updated: type: boolean description: >- If Vindicia was able to retrieve updated credit card account through Account Updater, this field is set to 'true' and the new credit information is returned in the `credit_card.account` and `credit_card.expiration_date` fields. In order to enable this feature a valid PGP public key must be provided to Vindicia Client Services contact. readOnly: true description: Retain credit_card object, which is a payment method. securitySchemes: basicAuth: type: http description: Basic Auth for all servers/paths scheme: Basic x-basicInfoFunc: auth_controller.check_basicAuth bearerAuth: type: http description: Bearer token for internal API authentication only scheme: bearer x-bearerInfoFunc: auth_controller.check_bearerAuth cookieAuth: type: apiKey description: Cookie authentication used by Retain Portal only name: cookie in: cookie x-apikeyInfoFunc: auth_controller.check_cookieAuth ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.