> ## 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. # Refund Retain Transactions > Directs Vindicia Retain to refund a captured Transaction or to discontinue further retry attempts to capture a Transaction. This call can be used in different scenarios such as when a customer has cancelled a subscription, or has paid the bill independent of Retain processing. This call also supports partial refunds by adding the **amount** attribute to the refund request. Partial Refunds are allowed up to the original captured amount (or a sum of previous partial refunds up to the captured amount) If a requested refund fails Retain input validation it is returned in the response array, along with information indicating the issue. After Retain processes the refund API call, Push Notifications for each refund processed are sent. You can call `GET retain/refunds` for the datetime range in which the refund(s) were performed, or use `GET retain/refunds/{id}`, to get details of the refund operation(s) for a specific Transaction. ## OpenAPI ````yaml /portal/retainAPILatest.yaml post /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: post: tags: - Retain Refunds summary: Refund Retain Transactions description: >- Directs Vindicia Retain to refund a captured Transaction or to discontinue further retry attempts to capture a Transaction. This call can be used in different scenarios such as when a customer has cancelled a subscription, or has paid the bill independent of Retain processing. This call also supports partial refunds by adding the **amount** attribute to the refund request. Partial Refunds are allowed up to the original captured amount (or a sum of previous partial refunds up to the captured amount) If a requested refund fails Retain input validation it is returned in the response array, along with information indicating the issue. After Retain processes the refund API call, Push Notifications for each refund processed are sent. You can call `GET retain/refunds` for the datetime range in which the refund(s) were performed, or use `GET retain/refunds/{id}`, to get details of the refund operation(s) for a specific Transaction. operationId: refundTransactions parameters: - name: dryrun in: query description: >- Indicates if the refunds are being submitted only for primary data validation, without formal commit of the actual data to Retain for processing. required: false style: form explode: true schema: maximum: 1 minimum: 0 type: integer format: int32 default: 0 requestBody: $ref: '#/components/requestBodies/refund_request' responses: '200': description: | All submitted refunds accepted for processing. content: application/json: schema: $ref: '#/components/schemas/inline_response_200_2' '207': description: > API request received, understood and accepted but invalid properties prevent processing one or more refund requests. content: application/json: schema: $ref: '#/components/schemas/refund_validation_errors' '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. callbacks: Refund status: https://webhook.merchant.com/path4: post: summary: Refund Completed description: >- Requested refund has been sent and successfully processed by payment provider. Request body contains - `header` object with event_name property with a value of "refund completed" - `content` object containing a `transaction` object (see Schema below) including details of refunds. requestBody: content: application/json: schema: required: - content - header type: object properties: header: $ref: '#/components/schemas/push_header' content: $ref: '#/components/schemas/transaction' example: header: author_id: qa_retain_push_wildcard_soap class_name: retain event_name: refund completed event_timestamp: '2019-08-24T14:15:22.000Z' merchant_vid: 0f8022cddeb9a78aae1be18ebdf4da2ffb333231 message_id: stringstringstringstringstr submitted: '2019-08-24T14:15:22.000Z' payload_id: dc42d9305652c787d179c6beb0e59b1209889b38 transaction_id: TX12345678 content: vid: dc42d9305652c787d179c6beb0e59b1209889b38 id: TX12345678 timestamp: '2020-05-18T20:39:03.000Z' amount: 21.64 currency: USD status: Refunded division_number: 349641 retain_transaction_id: VIN1234567 refunds: - vid: f147870b2c86a00fb1264fb64c0a8b58fcd95b4d id: VIN3456789 amount: 21.64 status: Completed timestamp: '2023-02-16T20:39:03.000Z' processor_transaction_id: '1234567890' account: vid: 659649a98f9b2c688b6217b3c642e1f3262a3427 id: Cust-2125551212 email: foo@example.com subscription: id: Sub-2125551212 starts: '2022-05-15T18:24:05.000Z' payment_method: vid: 659649a98f9b2c688b6217b3c642e1f3262a3427 id: XY-0266667018640 account: vid: 659649a98f9b2c688b6217b3c642e1f3262a3427 id: Cust-2125551212 external_id: asdf1234 email: foo@example.com account_holder: Lily Munster billing_address: line1: 1313 Mockingbird Ln. line2: Floor 13 line3: Suite 13 city: Mockingbird Heights county: San Bernardino district: CA postal_code: 92415 country: US is_tokenized: false type: CreditCard credit_card: account: 411111XXXXX1111 account_hash: 68bfb396f35af3876fc509665b3dc23a0930aab1 expiration_date: 202204 primary: 1 metadata: {} auth_code: 200 avs_code: Y:2341234234 cvn_code: M:2341234234 auth_code_description: Authorized payment_network_transaction_id: SCI123456 retry_number: 1 forced_deposit: false required: true responses: '202': description: Receiving server returns this code if it accepts the message method: post type: path path: https://webhook.merchant.com/path4 https://webhook.merchant.com/path5: post: summary: Refund Failed description: >- A refund request to the Payment Provider was declined or not approved. requestBody: content: application/json: schema: required: - content - header type: object properties: header: $ref: '#/components/schemas/push_header' content: $ref: '#/components/schemas/transaction' example: header: author_id: qa_retain_push_wildcard_soap class_name: retain event_name: refund failed event_timestamp: '2019-08-24T14:15:22.000Z' merchant_vid: 0f8022cddeb9a78aae1be18ebdf4da2ffb333231 message_id: stringstringstringstringstr submitted: '2019-08-24T14:15:22.000Z' payload_id: dc42d9305652c787d179c6beb0e59b1209889b38 transaction_id: TX12345678 content: vid: dc42d9305652c787d179c6beb0e59b1209889b38 id: TX12345678 timestamp: '2020-05-18T20:39:03.000Z' amount: 21.64 currency: USD status: Captured division_number: 349641 retain_transaction_id: VIN1234567 refunds: - vid: f147870b2c86a00fb1264fb64c0a8b58fcd95b4d id: VIN3456789 amount: 21.64 status: Failed timestamp: '2023-02-16T20:39:03.000Z' processor_transaction_id: '1234567890' account: vid: 659649a98f9b2c688b6217b3c642e1f3262a3427 id: Cust-2125551212 email: foo@example.com subscription: id: Sub-2125551212 starts: '2022-05-15T18:24:05.000Z' payment_method: vid: 659649a98f9b2c688b6217b3c642e1f3262a3427 id: XY-0266667018640 account: vid: 659649a98f9b2c688b6217b3c642e1f3262a3427 id: Cust-2125551212 external_id: asdf1234 email: foo@example.com account_holder: Lily Munster billing_address: line1: 1313 Mockingbird Ln. line2: Floor 13 line3: Suite 13 city: Mockingbird Heights county: San Bernardino district: CA postal_code: 92415 country: US is_tokenized: false type: CreditCard credit_card: account: 411111XXXXX1111 account_hash: 68bfb396f35af3876fc509665b3dc23a0930aab1 expiration_date: 202204 primary: 1 metadata: {} auth_code: 200 avs_code: Y:2341234234 cvn_code: M:2341234234 auth_code_description: Authorized payment_network_transaction_id: SCI123456 retry_number: 1 forced_deposit: false required: true responses: '202': description: Receiving server returns this code if it accepts the message method: post type: path path: https://webhook.merchant.com/path5 components: requestBodies: refund_request: description: Array of Transaction identifiers to refund or terminate reprocessing. content: application/json: schema: type: object properties: refunds: minItems: 1 type: array items: $ref: '#/components/schemas/refund' example: refunds: - id: '12345' - id: '67890' amount: 5 required: true schemas: inline_response_200_2: type: object properties: message: type: string example: refunds received for processing refund_validation_errors: type: object properties: success_count: type: integer description: >- Integer count of the number of refunds that have succeeded Retain data validation. error_count: type: integer description: >- Integer count of the number of refund that have failed Retain data validation. rejected: type: array items: $ref: '#/components/schemas/refund_validation_errors_rejected' description: >- API request received, understood, and accepted, but invalid properties prevent one or more refunds from being processed by Retain. example: error_count: 2 rejected: - id: TX_ID_1 errors: - code: RET027 message: >- Unable to refund this transaction as requested amount exceeds refundable amount - id: TX_ID_2 errors: - code: RET015 message: >- The transaction has been cancelled and is no longer in the retry phase for capture. Hence, we cannot proceed with Refund. 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 push_header: type: object properties: author_id: type: string description: The author_id corresponds to the merchant login. payload_id: maxLength: 40 minLength: 40 type: string description: >- For non `validtion_failed` events, it will have value of transaction_vid with a length of 40. class_name: type: string description: Vindicia name for the message class default: retain event_name: type: string description: Identifying name for the event triggering this specific message. enum: - retry succeeded - retry failed - refund completed - refund failed - validation failed event_timestamp: type: string description: >- ISO 8601-1:2019 extended format date and time (including fracational seconds AND time zone offset ±hh:mm) of the Retain event triggering the message. format: date-time merchant_vid: maxLength: 40 minLength: 40 type: string description: Vindicia internal UUID for specific Merchant message_id: maxLength: 27 minLength: 27 type: string description: Vindicia unique identifier for this specific message. submitted: type: string description: >- ISO 8601-1:2019 extended format date and time (including fracational seconds AND time zone offset ±hh:mm) the message was submitted to the delivery system. format: date-time transaction_id: type: string description: >- The Merchant supplied identifier of a transaction that failed billing in the Merchant's billing system (aka a 'Failed' transaction identifier) 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. 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' refund_validation_errors_rejected: type: object properties: id: $ref: '#/components/schemas/id' errors: type: array items: anyOf: - $ref: '#/components/schemas/RET014' - $ref: '#/components/schemas/RET015' - $ref: '#/components/schemas/RET016' - $ref: '#/components/schemas/RET017' - $ref: '#/components/schemas/RET018' - $ref: '#/components/schemas/RET019' - $ref: '#/components/schemas/RET020' - $ref: '#/components/schemas/RET021' - $ref: '#/components/schemas/RET022' - $ref: '#/components/schemas/RET023' - $ref: '#/components/schemas/RET024' - $ref: '#/components/schemas/RET027' - $ref: '#/components/schemas/RET028' - $ref: '#/components/schemas/RET030' 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 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 RET014: type: object properties: code: type: string default: RET014 message: type: string default: Unable to retrieve Refund with this ID readOnly: true RET015: type: object properties: code: type: string default: RET015 message: type: string default: >- The transaction has been cancelled and is no longer in the retry phase for capture. Hence, we cannot proceed with Refund. readOnly: true RET016: type: object properties: code: type: string default: RET016 message: type: string default: >- Unable to refund - total captured amount has previously been refunded readOnly: true RET017: type: object properties: code: type: string default: RET017 message: type: string default: No transactions submitted (input may have been malformed) readOnly: true RET018: type: object properties: code: type: string default: RET018 message: type: string default: Some (or all) refunds failed; check notes. readOnly: true RET019: type: object properties: code: type: string default: RET019 message: type: string default: Refunds failed; check VIDs, notes. readOnly: true RET020: type: object properties: code: type: string default: RET020 message: type: string default: FAILED to cancel autobill with subscription identifier readOnly: true RET021: type: object properties: code: type: string default: RET021 message: type: string default: Unrefundable Transaction readOnly: true RET022: type: object properties: code: type: string default: RET022 message: type: string default: Refund transaction is not associated with a subscription readOnly: true RET023: type: object properties: code: type: string default: RET023 message: type: string default: Failed to load Transaction readOnly: true RET024: type: object properties: code: type: string default: RET024 message: type: string default: Failed to load autobill readOnly: true RET027: type: object properties: code: type: string default: RET027 message: type: string default: >- Unable to refund this transaction as requested amount exceeds refundable amount readOnly: true RET028: type: object properties: code: type: string default: RET028 message: type: string default: Transaction cannot be Partially Refunded as it was not Captured readOnly: true RET030: type: object properties: code: type: string default: RET030 message: type: string default: Merchant doesn't allow refunding readOnly: true 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.