> ## 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. # Submit Retain Transactions > Use this call to submit an array of Transactions to Vindicia Retain for processing and recovery. Use Push Notifications to automatically listen to Transaction recovery results or proactively retrieve the list of Transactions using the Get `GET /retain/transactions`call. # Accepts Vindicia Retain accepts an array of up to 1000 Transactions per individual API call. Submitted Transactions must include the following: * transaction id * amount * currency * timestamp * transaction auth code * subscription id * customer id * payment method id * tokenized * credit card - required if tokenized is set to false (0) * cc expiration date - required if tokenized is set to false (0) * division number Additional input is optional but recommended for recovery: * account holder and billing address details * cit mit (card-on file) processor id * cvn code * avs code ### Notes ### Returns * All submitted Transactions undergo input validations for required fields and formats. * If all Transactions in the request body successfully pass the validation, Vindicia Retain responds with a 200 HTTP return code and no response body. Transactions that sucessfully pass input validations are saved and processed. * If some of the submitted Transactions in the request fail input validations, Vindicia Retain responds with a 207 HTTP return code and a response as described in `transaction_validation_errors`. It contains an error message for each invalid Transaction listing the following: - Identifier of the Transaction - Retain error code - Error message indicating the reason for the validation failure. All other transactions in the request are saved to Retain and undergo undergo an asynchronous post-submission system review to detect additional errors prior to processing. ## OpenAPI ````yaml /portal/retainAPILatest.yaml post /retain/transactions 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: post: tags: - Retain Transactions summary: Submit Retain Transactions description: >- Use this call to submit an array of Transactions to Vindicia Retain for processing and recovery. Use Push Notifications to automatically listen to Transaction recovery results or proactively retrieve the list of Transactions using the Get `GET /retain/transactions`call. # Accepts Vindicia Retain accepts an array of up to 1000 Transactions per individual API call. Submitted Transactions must include the following: * transaction id * amount * currency * timestamp * transaction auth code * subscription id * customer id * payment method id * tokenized * credit card - required if tokenized is set to false (0) * cc expiration date - required if tokenized is set to false (0) * division number Additional input is optional but recommended for recovery: * account holder and billing address details * cit mit (card-on file) processor id * cvn code * avs code ### Notes ### Returns * All submitted Transactions undergo input validations for required fields and formats. * If all Transactions in the request body successfully pass the validation, Vindicia Retain responds with a 200 HTTP return code and no response body. Transactions that sucessfully pass input validations are saved and processed. * If some of the submitted Transactions in the request fail input validations, Vindicia Retain responds with a 207 HTTP return code and a response as described in `transaction_validation_errors`. It contains an error message for each invalid Transaction listing the following: - Identifier of the Transaction - Retain error code - Error message indicating the reason for the validation failure. All other transactions in the request are saved to Retain and undergo undergo an asynchronous post-submission system review to detect additional errors prior to processing. operationId: billTransactions parameters: - name: dryrun in: query description: >- When enabled, Transactions are submitted for primary data validation only, without submitting them to Retain for processing. required: false schema: maximum: 1 minimum: 0 type: integer format: int32 default: 0 requestBody: $ref: '#/components/requestBodies/transaction_request' responses: '200': description: >- All Transactions that were submitted to Vindicia Retain have successfully passed all input validations, without exception. No responseBody is returned. '207': description: > API request received, understood and accepted but invalid properties prevent processing one or more transaction requests. content: application/json: schema: $ref: '#/components/schemas/transaction_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: processing status: https://webhook.merchant.com/path: post: summary: Validation Failed description: >- Retain message indicating intake exceptions for submitted transactions. Request body will contain - `header` object with event_name property with a value of "validation failed" - `content` object containing a `transaction_validation_errors` object (see Schema below) listing the submitted transaction identifier, an error code, and an error message describing the reason the transaction could not be accepted by Retain. These messages are related to Retain backend internal validations and will most commonly be related to credit card decryption or de-tokenization issues if those features are used in the submission. requestBody: content: application/json: schema: required: - content - header type: object properties: header: $ref: >- #/components/schemas/push_header_for_validation_failed_event content: $ref: '#/components/schemas/transaction_validation_errors' example: header: author_id: qa_retain_push_wildcard_soap class_name: retain event_name: validation failed event_timestamp: '2019-08-24T14:15:22.000Z' merchant_vid: 0f8022cddeb9a78aae1be18ebdf4da2ffb333231 message_id: afaaa11c2c228659d1e8c446f33f1e274ca6ff6c submitted: '2019-08-24T14:15:22.000Z' payload_id: 16451545b7b0a7a056db5917e1c7744fd request_id: 16451545b7b0a7a056db5917e1c7744fd error_count: 2 content: error_count: 2 rejected: - id: TX_ID_1 errors: - code: RET012 message: >- The 'creditCardAccountHash' parameter ("abc123xyz") to Vindicia::Soap::1_5::SelectServerMethods::billTransactions did not pass validation check - id: TX_ID_2 errors: - code: RET010 message: >- The 'creditCardAccount' parameter ("42677777XXXX9299") to Vindicia::Soap::1_5::SelectServerMethods::billTransactions did not pass the 'luhn_check' callback required: true responses: '202': description: Receiving server returns this code if it accepts the message method: post type: path path: https://webhook.merchant.com/path retry_succeeded: https://webhook.merchant.com/path2: post: summary: Retry Succeeded description: >- Retain has completed reprocessing resulting in a “capture” for the failed transaction. Request body will contain - `header` object with event_name property with a value of "retry succeeded" - `content` object containing a `transaction` object (see Schema below) with the details of the successfully reprocessed transaction. 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: retry succeeded event_timestamp: '2019-08-24T14:15:22.000Z' merchant_vid: 0f8022cddeb9a78aae1be18ebdf4da2ffb333231 message_id: afaaa11c2c228659d1e8c446f33f1e274ca6ff6c 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 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:234123 cvn_code: M:123456 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/path2 retry_failed: https://webhook.merchant.com/path3: post: summary: Retry Failed description: >- All attempts to collect for a failed transaction have completed unsuccessfully. Request body will contain - `header` object with event_name property with a value of "retry failed" - `content` object containing a `transaction` object (see Schema below) with the details of the unsuccessfully reprocessed transaction. 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: retry failed event_timestamp: '2019-08-24T14:15:22.000Z' merchant_vid: 0f8022cddeb9a78aae1be18ebdf4da2ffb333231 message_id: afaaa11c2c228659d1e8c446f33f1e274ca6ff6c 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: Cancelled division_number: 349641 retain_transaction_id: VIN1234567 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 auth_code: 500 avs_code: Y:123456 cvn_code: M:123456 auth_code_description: Hard Fail 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/path3 components: requestBodies: transaction_request: content: application/json: schema: type: object properties: transactions: type: array items: $ref: '#/components/schemas/transaction' example: transactions: - account: id: Your-Customer1-ID amount: 21.64 auth_code: '530' currency: USD division_number: '349641' id: Your-Failed-TX-ID1 payment_method: credit_card: account: '4111111111111111' expiration_date: '202301' id: Your-PayMethod1-ID account_holder: Lily Munster billing_address: city: Mockingbird Heights country: US district: CA line1: 1313 Mockingbird Ln. postal_code: '92415' line2: Floor 13 line3: Suite 13 county: San Bernardino is_tokenized: false subscription: id: Your-Subscription1-ID starts: '2022-08-27T21:47:45.000Z' timestamp: '2023-02-25T21:47:45.000Z' metadata: metadata1: clicks-and-mortar metadata2: metrics avs_code: 'Y' cvn_code: M payment_network_transaction_id: CIT-TX-ID1 - account: id: Your-Customer2-ID amount: 21.64 auth_code: '500' currency: USD division_number: '349641' id: Your-Failed-TX-ID2 payment_method: credit_card: account: '4012888888881881' expiration_date: '202212' id: Your-PayMethod2-ID account_holder: Cousin It billing_address: city: Mockingbird Heights country: US district: CA line1: 1313 Mockingbird Ln. postal_code: '92415' line2: Floor 13 line3: Suite 13 county: San Bernardino is_tokenized: false subscription: id: Your-Subscription2-ID starts: '2022-08-27T21:47:45.000Z' timestamp: '2023-02-25T21:47:45.000Z' avs_code: 'Y' cvn_code: M payment_network_transaction_id: CIT-TX-ID2 required: true schemas: transaction_validation_errors: type: object properties: success_count: type: integer description: >- Integer count of the number of transactions that have succeeded Retain data validation. error_count: type: integer description: >- Integer count of the number of transactions that have failed Retain data validation. rejected: type: array items: $ref: '#/components/schemas/transaction_validation_errors_rejected' description: >- API request received, understood, and accepted, but invalid properties prevent one or more transactions from being processed by Retain. example: error_count: 2 rejected: - id: TX_ID_1 errors: - code: RETDUP2 message: Duplicate transaction from prior submission - id: TX_ID_2 errors: - code: RETDUP message: Duplicate transaction within submission 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_for_validation_failed_event: type: object properties: author_id: type: string description: The author_id corresponds to the merchant login. payload_id: maxLength: 32 minLength: 32 type: string description: >- In the case of `validation_failed` event, the payload_id value will be the request-id from a POST call, with length of 32. request_id: maxLength: 32 minLength: 32 type: string description: It represents request-id of POST call. 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 error_count: type: integer description: >- Integer count of the number of transactions that have failed Retain data validation. 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. transaction_validation_errors_rejected: type: object properties: id: $ref: '#/components/schemas/id' errors: type: array items: anyOf: - $ref: '#/components/schemas/RET001' - $ref: '#/components/schemas/RET002' - $ref: '#/components/schemas/RET003' - $ref: '#/components/schemas/RET004' - $ref: '#/components/schemas/RET005' - $ref: '#/components/schemas/RET006' - $ref: '#/components/schemas/RET007' - $ref: '#/components/schemas/RET008' - $ref: '#/components/schemas/RET009' - $ref: '#/components/schemas/RET010' - $ref: '#/components/schemas/RET011' - $ref: '#/components/schemas/RET012' - $ref: '#/components/schemas/RET900' 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 RET001: type: object properties: code: type: string default: RET001 message: type: string default: Duplicate transaction within submission readOnly: true RET002: type: object properties: code: type: string default: RET002 message: type: string default: Duplicate transaction from prior submission readOnly: true RET003: type: object properties: code: type: string default: RET003 message: type: string default: A Transaction for the same Subscription is still processing readOnly: true RET004: type: object properties: code: type: string default: RET004 message: type: string default: Transaction was previously submitted and processed readOnly: true RET005: type: object properties: code: type: string default: RET005 message: type: string default: System cannot read Transaction readOnly: true RET006: type: object properties: code: type: string default: RET006 message: type: string default: Missing Transaction element readOnly: true RET007: type: object properties: code: type: string default: RET007 message: type: string default: Trial mode without capture. Incompatible configuration readOnly: true RET008: type: object properties: code: type: string default: RET008 message: type: string default: Processing error readOnly: true RET009: type: object properties: code: type: string default: RET009 message: type: string default: Schema validation error readOnly: true RET010: type: object properties: code: type: string default: RET010 message: type: string default: Credit Card number is not valid or incorrectly encrypted readOnly: true RET011: type: object properties: code: type: string default: RET011 message: type: string default: Unable to process provided tokenized payment method readOnly: true RET012: type: object properties: code: type: string default: RET012 message: type: string default: Did not pass validation check readOnly: true RET900: type: object properties: code: type: string default: RET900 message: type: string default: Unable to submit, please try again 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.