> ## 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. # Fetch a Retain Transaction > Vindicia Retain returns the Transaction identified by the input. Use this method to fetch a specific transaction. To retrieve multiple results in a single call, use the `GET /retain/transactions` API call instead of this one. Note: The recommended way to determine the final state of a Retain transaction is by using Push Notifications, or the `GET /transactions` API. This means that all final state results should be received through one of these mechanisms. Making this call with a transaction id that was received through either of those mechanisms provides the same results. ### Accepts None. ### Returns A specific `transaction` object. ## OpenAPI ````yaml /portal/retainAPILatest.yaml get /retain/transactions/{id} 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/transactions/{id}: get: tags: - Retain Transactions summary: Fetch a Retain Transaction description: >- Vindicia Retain returns the Transaction identified by the input. Use this method to fetch a specific transaction. To retrieve multiple results in a single call, use the `GET /retain/transactions` API call instead of this one. Note: The recommended way to determine the final state of a Retain transaction is by using Push Notifications, or the `GET /transactions` API. This means that all final state results should be received through one of these mechanisms. Making this call with a transaction id that was received through either of those mechanisms provides the same results. ### Accepts None. ### Returns A specific `transaction` object. operationId: getTransaction parameters: - name: id in: path 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) required: true style: simple explode: false schema: type: string - name: related in: query description: >- If set to true, all Retain transactions (submitted Failed and all retries) related to the Transaction identified by `id` are returned. required: false schema: type: boolean default: false example: true responses: '200': description: List of Transactions with pagination links content: application/json: schema: $ref: '#/components/schemas/inline_response_200' '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: type: object properties: object: type: string enum: - List data: type: array items: $ref: '#/components/schemas/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_count: 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 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' submitted_ts: type: string description: >- Read Only, The datetime in which the failed transaction was submitted to Retain by the merchant. Appears in UTC time in ISO-8601:2019 format. 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: 11.64 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' 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) associted with this transaction. allOf: - $ref: '#/components/schemas/subscription' previous_billing_count: type: integer description: >- The number of previous successful billings associated with the subscription. Note:For merchants using forced deposit, in order to avoid forced deposit on a specific Transaction, set the value to -1. 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 (D)) or Hard Failure (R) 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 is_network_token: type: integer description: >- Indicates if the payment method is a network token. When using network token as the payment method with the payment provider, do the following: * Provide the token in the payment_method.id field * Set is_network_token to true (1). * Set is_tokenized to true (1). * If you use cryptograms, enter it in transaction.cryptogram field. * If used with 3DS, enter the ECI value in transaction.eci_indicator field. * 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. cryptogram: type: string description: >- The cryptogram is a unique code that can be generated for payment method authorization, adding an extra layer of security. It is used to verify the authenticity of the payment method (card, network token) and the integrity of the data sent during the transaction. This field is required by payment providers when using cryptogram with network tokens. eci_indicator: type: string description: >- Electronic Commerce Indicator (ECI) value is relevant for 3DS transactions and is returned to indicate the authentication results of the customer's credit card payment. 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.