> ## Documentation Index > Fetch the complete documentation index at: https://docs.slm.m1amdocs.com/llms.txt > Use this file to discover all available pages before exploring further. # List All Chargebacks > Retrieves a list of all Chargebacks. ## OpenAPI ````yaml /portal/SubscribeAPI.yaml get /chargebacks openapi: 3.0.0 info: title: Subscribe API description: > # Overview The REST API for Subscribe provides predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients # Subscribe OpenAPI YAML Reference See the [Subscribe OpenAPIs](https://docs.vindicia.com/bundle/SubscribeAPI/page/index.html) YAML file located in the [Developer Hub](https://docs.vindicia.com/category/developerhub) section of the Knowledge Center. # Environment Subscribe provides two distinct environments for testing and production: ## The Staging Environment The Staging environment allows you to test your application against the code currently running in **Production:** **https://api.staging.us-west.vindicia.com** ## The Production Environment The **Production** environment is for real-world use for actual billing and subscription activity. **https://api.vindicia.com** *Note: The examples in this API reference use the Production URL. Replace with the Staging URL, as needed.* # Interacting with the API ## Making Requests As per RESTful design patterns, the Subscribe API implements the following HTTP verbs: | Verb | Description | | ------------ | --------------------------------------------------------------------------| | GET | Retrieve resources (as a list or single record fetch) | | POST | Create new resources or update existing ones (overloading during create/update is permitted where specified) | | DELETE | Remove an ownership or hierarchical association between certain resources | Requests and Responses are made in JSON. When making requests, set the Content-Type header to **application/json**. Vindicia supports gzip compression. To receive the response body compressed in gzip format, send **content-encoding:gzip** in your request header. ## Example ``` POST /transactions Content-Type: application/json Content-Length: 94 { "object" : "Transaction", "id" : "tx_1234", "created" : "2020-01-01T00:55:47Z" } ``` ## Status Codes Subscribe uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the **2xx** range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.), and codes in the **5xx** range indicate an error with Vindicia’s servers (these are rare). When an error occurs additional information will be returned in the [error response](https://docs.vindicia.com/bundle/b_Subscribe_REST_API_Guide/page/topics/Errors.html). | Code |Status | Description | |---------|-----------------------|---------------------------------------------------------------------------| | 200 | Ok | Everything worked as expected. | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 | Authorization | Couldn’t authenticate your request | | 402 | Authorization Failure | Authorization failed | | 403 | Forbidden | Authentication failed - check your username and password | | 404 | Not Found | The requested resource doesn’t exist | | 429 | Too Many Requests | Too many requests hit the API too quickly. | | 500 | Internal Server Error | | | 503 | Forbidden | Authentication failed - check your username and password | ## Example Basic HTTP Response ``` HTTP/1.1 200 OK Content-Type: application/json Content-Length: 150 Request-Id: d837becba3325b62adddb2b0f1d7ab48824ff248 Connection: close { "object" : "Transaction", "id" : "tx_1234", "vid" : "40f24148bdc282640b46ad281eec31f7dfd9202e", "created" : "2020-01-01T00:55:47Z" } ``` ## Fields All resources are represented by a unique, Vindicia identifier - a vid. Many resources also provide an id field for you to record your unique identifier which can contain any alphanumeric character but must not contain a /. When referring to a resource either the vid or the id may be used. `GET https://api.vindicia.com/transactions/:id` `GET https://api.vindicia.com/transactions/:vid` Resources also have an object field which represents the resource type. #### Example Call ``` { "object" : "Transaction", "id" : "tx_1234", "vid" : "40f24148bdc282640b46ad281eec31f7dfd9202e", "created" : "2020-01-01T00:55:47Z", "url" : "/transactions/tx_1234" } ``` #### Timestamps All timestamps are represented in ISO8601 format. Timestamps may be submitted in any timezone but will be returned in UTC Time standard. #### Strings All strings are 1,024 characters unless otherwise noted. Submitting values in excess of this limit will return an error. #### Enumerable Values Some fields like **object** have a constant set of values. Submitting any value other than those documented will result in an error being returned with a status code of **400**. #### Arrays and Lists The API returns multiple resources as list objects containing JSON array. Lists provide the ability to sparsely represent the resources they contain. Additional data can be accessed through [pagination](https://docs.vindicia.com/bundle/b_Subscribe_REST_API_Guide/page/topics/Pagination.html). #### Example Request (Excerpt) ``` { "object" : "Subscription", "id" : "sub_1234", "items": [ { "object": "SubscriptionItem", "id": "sub_1234.1", "product": { "object": "Product", "id": "prod_1234" } }, { "object": "SubscriptionItem", "id": "sub_1234.2", "product": { "object": "Product", "id": "prod_1235" } } ] ... } ``` #### Example Response (Excerpt) ``` { "items": { "object": "List", "data": [ { "object": "SubscriptionItem", "id": "sub_1234.1", "index": 0, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" }, { "object": "SubscriptionItem", "id": "sub_1234.2", "index": 0, "product": {...}, "quantity": 1, "created": "2020-05-27T05:52:02-07:00", "starts": "2020-05-27T00:00:00-07:00" } ], "total_count": 2 } ``` ## Creating and Updating Objects For expedience and convenience most create calls for a certain object allow for the creation of sub-objects when doing the initial creation. However, updating is purposefully always an atomic operation relating to only one object to prevent accidental data loss. For example: When creating an Account you can concurrently create a new Payment Method. When updating, you will need to separately update a Payment Method by using the Payment Methods endpoints. # Authentication Authentication to the API is performed via HTTP Basic Auth using your environment specific API user and key as the username and password. *Note: All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.* Example cURL Api Key Usage ```curl "https://api.vindicia.com/subscriptions" -u acaff38d462f9430d5cbcbaf:a575771fc679b9de``` Example JavaScript Api Key Usage ```constsubscribe_api_key="acaff38d462f9430d5cbcbaf:a575771fc679b9de";``` # Pagination All **GET** endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource in the list as a starting_after parameter for the next call. To make it easier, the API will assign the next call into next attribute together with all the currently used pagination parameters. You know that you have paginated all the results when the return is empty (**next** value will be undefined, as well). Using cursor-based pagination protects against the situation when the resulting object list changes during pagination (new resource gets added or removed). The default limit is set to 20 but values up to 100 are permitted.
 Parameter    test    Description 
 limit   optional   A limit on the number of objects to be returned, between 1 and 100. 
 starting_after   optional   A cursor for use in pagination. starting_after is an object id that
defines your place in the list. For instance, if you make a list request and receive 100 objects,
ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. 
 ending_before   optional   A cursor for use in pagination. ending_before is an object id that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list. 
Example Call ``` GET /foos Content-Type: application/json Content-Length: 32509 ``` Example Collection Pagination ``` { "object": "List", "data": [...], "total_count": 31, "url": "/foos", "next": "/foos?starting_after=Montly+Stream", "previous": "/foos?ending_before=Daily+Stream" } ``` # Errors All error responses will return an error object. ## Attributes
 Name   Type   Description 
 object   string   Value is “Error”. 
 message   string   A human-readable message providing more detailed information about the error. 
## Example Error JSON ``` { "object" : "Error", "message" : "Not implemented yet." } ``` # Versioning The API version is based on the date of the last breaking change. The current version is 20190501. To set the API version on a specific request send an **X-API-Version** header on your first call. The system will default according to your first call. Most additions to the API will not require a new version of the API. If no version is specified in the X-API Version header, the default API version will be used. # Request Ids Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution. # Endpoints The Subscribe REST API exposes key resources as endpoints, which can be manipulated using standard methods. Critical sub-resources which only work in the context of their parent are defined here under their endpoint; other sub-resources, shared between other objects but not directly manipulated are documented in the Resources section. *Note: HTTP request examples in this reference use the Production path. For the Staging environment, substitute **staging.us-west.vindicia** in place of vindicia.* Subscribe provides a RESTful API to integrate recurring and one-time payments as well as other billing concepts into your business or application. The API provides predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific object contact: email: support@vindicia.com license: name: Vindicia url: https://www.vindicia.com/ version: '2024.09' servers: - url: https://virtserver.swaggerhub.com/Amdocs_Media/Subscribe_API_WIP/2024.09 description: Subscribe OpenAPI specification - url: https://api.staging.us-west.vindicia.com description: Subscribe Staging for Testing - url: https://api.vindicia.com description: Subscribe Production security: - basicAuth: [] tags: - name: Accounts description: >- The Account represents a merchant’s customer. As such it can contain as much or as little information as you collect about the customers (people or organizations) to which you offer billing and subscriptions. Subscriptions and Transactions must belong to an Account - as such, Accounts will be required in Subscribe for billing. Read More in our User Guide An Account can have any number of children accounts and may have up to one parent account. Read more in our User Guide. An Account owns the “on file” payment methods to be used by it in billing - name: Activities description: >- The Activity object enables you to record activities (events) on your site that are not direct purchase transactions, such as when customers access for-pay content like song downloads. That information can serve as evidence for chargeback disputes should they occur. You make calls available for the Activity object to submit the activity data once per event. Alternatively, queue and submit the data periodically in a batch process. Usually, you collect events of interest only. For example, you need not record every page view by a customer, only those page views that contain for-pay content that the customer accessed or downloaded. - name: Address description: '' - name: Billing Plans description: >- A Billing Plan represents a pre-defined billing and pricing schedule. Every subscription is billed according to its assigned Billing Plan. A Billing Plan can be a complex object made up of one or more Billing Periods, each of which have configurable rules for how many cycles they repeat, as well as other billing, entitlement, and communication rules. The API allows you to create or update Billing Plans. You can retrieve individual plans as well as a list of all Billing Plans. - name: Campaigns description: >- Subscribe Campaigns are discounts, such as special offers or limited-time pricing, you can apply to your Products or Billing Plans. Discounts can be currency-based or percentage-based, and applied to one-time purchases or applied to a recurring subscription for a specific period. - name: Campaign Codes description: >- Subscribe Campaigns are discounts, such as special offers or limited-time pricing, you can apply to your Products or Billing Plans and are handled by the Campaigns object. Campaign Codes are the codes provided to customers that are used to redeem the campaign. - name: Cancel Fee Policy description: Cancel Fee Policy - name: Cancel Reasons description: Merchant specified reason for cancelling a subscription. - name: Chargebacks description: >- A chargeback is initiated by a customer to reverse a specific transaction charge on their billing statement. - name: Charges description: >- This model is a REST-level representation of TransactionBillingItem with type of NonRecurringCharge. Note that Charge represents only positive TBIs. An as yet unbuilt model Adjustment will represent negative TBIs. - name: Currency Amount description: >- The CurrencyAmount object represents the currency credit detail associated with a particular grant of currency credits. - name: Diagnostics description: '' - name: Discount Tickets description: >- Discount Tickets is a list of campaign codes to be applied to a Subscription/Subscription Billing Plan/Subscription Item/Charge. They provide the discounts as defined in the Campaigns. They allow you to offer multiple campaign discounts simultaneously as an array to Subscriptions or Transactions and to manage the application of these discounts. - name: Entitlements description: >- The entitlement object represents the services to which a customer is entitled. Entitlement can reside at the Account (granted directly to the Customer) or the Subscription level (granted due to purchase or presence of an active subscription). - name: Events description: >- The Event object represents a specific measured/reported usage record. You can create, retrieve, list, and edit (update) individual usage event records using the Event object. - name: Event Summary description: >- This model is a REST-level representation of Event summary of next billing item. - name: GDPR Erase description: >- Removes personal information from an account (merchant_customer) for GDPR compliance. You must provide merchant_customer_id, It should be valid and should return only a single customer account for the merchant. - name: Gift Cards description: >- Gift cards are prepaid cards used to purchase products. The Gift card holds an amount of money and currency that can be redeemed to Subscribe. The gift card object holds the information of the card itself but does not allow to redeem it, instead use Gift Card Redemptions. - name: Gift Card Redemptions description: >- Gift cards are prepaid cards used to purchase products. The Gift card holds an amount of money and currency that can be redeemed to Subscribe. The redeemed amount of the gift card is credited to the Account as a credit balance and can then serve as payment balance for existing or new subscriptions.The gift card therefore does not serve as a payment method rather a crediting mechanism of the customer's account. - name: Invoices description: >- An Invoice presents the details for a particular billing - including the charges, taxes, credits, and payments related for a particular one-time purchase or subscription billing period. The API allows you to retrieve individual Invoices as well as a list of all of your Invoices using defined filters and/or pagination. - name: Payments description: >- The Payment object is a record of a payment made against an outstanding balance. This object can be used to accept Merchant Accepted Payment methods such as cash or check or to record payments made with other active payment methods such as Paypal or credit cards. For a recorded payment, a corresponding transaction is generated and processed through the auth/capture cycle appropriate to the payment method. - name: Payment Methods description: >- The PaymentMethod object represents an on-file payment instrument, for example, credit card, PayPal, ECP, direct debit. The API allows you to create, fetch, and update Payment Methods. You can retrieve individual PaymentMethods, as well as a list of all. - name: Products description: >- The Product object represents a unique merchant product, with its own pricing, description and entitlement assignments. The API allows you to create, fetch, and update products. You can retrieve individual Product objects, as well as a list of all - name: Rate Plans description: >- Rate Plans represents a pre-defined rating schedule--tier-based pricing for rated products (usage). Both pre-paid (License-based) and post-paid (metered, that is, usage-based) services use pre-defined tiers to rate recorded events. Rate Plans support flat and per-unit pricing, volume discounts, standard consumption-based prices, included units with overage, and maximum/minimum charge limits. - name: Refunds description: >- The Refund object provides a way to reverse a charge, refunding money to the customer. You can create, and retrieve individual Refunds; as well as list all existing Refunds. Refunds require a transaction – a refund can only be executed against an existing, successfully captured transaction. Refunds can be issued for any valid amount (in the currency of the original transaction) up to the as-yet un-refunded balance of the original transaction. You can issue any number of refunds on a given transaction (until it has been fully refunded). - name: Season Sets description: >- A SeasonSet object allows you to create groups of time intervals, which may be used with Billing Plans to define both Billing Cycles, and Entitlement grants. Note :- Season Sets are best described using the Subscribe user interface, rather than the API. - name: Reason Code description: Reason codes by type. - name: Subscription description: >- Subscriptions allow you to bill an Account over time and/or on a recurring basis. A subscription ties an Account to a particular billing plan and set of purchased products (subscription items) you’ve created. The API allows you to create, update and amend/modify your subscriptions. You can retrieve individual Subscriptions as well as a list of all your Subscriptions. - name: Transactions description: >- The Transaction object provides a way to charge a customer. You can create one-time transactions, retrieve individual transactions, fetch individual transactions, and list all Transactions for a given account or subscription. Posting with a new Transaction creates a new one-time Transaction object. If “to_be_captured” is false, the request will trigger an authorization attempt (based on the provided payment method’s authorization process). If successfully authorized, a subsequent post to the transaction’s actions/capture endpoint will capture the authorized transaction. If you post a new transaction with “to_be_captured” true, it will authorize and immediately capture the transaction if successful. To refund transactions, use the refunds endpoint. - name: Tokens description: >- The token object provides a way to offer virtual currencies or track the balance of a consumable service item. paths: /chargebacks: get: tags: - Chargebacks summary: List All Chargebacks description: Retrieves a list of all Chargebacks. operationId: searchChargebacks parameters: - name: limit in: query description: A limit on the number of objects to be returned, between 1 and 100. schema: maximum: 100 minimum: 1 type: integer format: int32 default: 20 - name: starting_after in: query description: >- A cursor for use in pagination. starting_after is an object **id** that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. schema: type: string - name: ending_before in: query description: >- A cursor for use in pagination. ending_before is an object **id** that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list. schema: type: string - name: account in: query description: The Account **id** or **vid** to filter list by. schema: $ref: '#/components/schemas/ID' - name: include_children in: query description: If filtering by Account, include child accounts. schema: type: boolean default: false - name: case_number in: query description: Filter Chargebacks list by your banks case number required: false schema: type: string - name: reference_number in: query description: Filter Chargebacks list by your banks case number. required: false schema: type: string - name: status in: query description: >- Can be Challenged, CollectionsLost, CollectionsNew, CollectionsWon, Duplicate, Expired, Incomplete, Legitimate, Lost, New, NewSecondChargeback, Pass, Represented, Responded, Retrieval, Won required: false schema: type: string - name: transaction in: query description: Transaction **id** or **vid** to filter chargeback list by required: true schema: type: string responses: '200': description: >- JSON A list array with a data property that contains an array of up to limit Chargebacks, starting after the specified starting_after Chargeback (or ending before the specified ending_before Chargeback). Each entry in the array is a full Chargeback object. If no more Chargebacks are available, the resulting array will be empty. This request should never throw an error. A list of CancelReason objects matching the query. Also: * “total_count”: Integer count of the number of CancelReason in the returned list. * “url”: The query string provided in the request * “next”: The route (partial URL) to the next CancelReason object (string to select the “next”); included vid should match that of the last object returned here * “previous”: The route (partial URL) to the previous CancelReason object (string to select the “previous”); included vid should match that of the first object returned here content: application/json: schema: type: array example: >- { "object": "List", "data": [ { "object": "Chargeback", "vid": "3d72d92cc1680ae6e7717aa66ac3e216454a3b14", "amount": 27.99, "currency": "USD", "presentment_currency": "USD", "reason_code": "8885", "reference_number": "12345", "transaction_id": "00000001", "transaction_timestamp": "2022-04-05T06:58:09+00:00", "processor_received_timestamp": "2022-09-05T06:58:09+00:00", "posted_timestamp": "2022-09-05T06:58:09+00:00", "status_changed_timestamp": "2022-09-06T09:19:42+00:00", "status": "Challenged", "merchant_user_id": "Account_1649141886", "metadata": {} } ], "total_count": 2, "url": "/chargebacks?limit=1", "next": "/chargebacks?starting_after=3d72d92cc1680ae6e7717aa66ac3e216454a3b14", "previous": "/chargebacks?ending_before=3d72d92cc1680ae6e7717aa66ac3e216454a3b14" } items: $ref: '#/components/schemas/ChargebacksList' '400': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Error - 401 Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: '' '404': description: Error - 404 Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: >- { "object": "Error", "message": "This endpoint does not exist. Check our API docs." } '500': description: Internal server error components: schemas: ID: maxLength: 128 type: string description: >- A unique identifier. Optionally, this object can also be identified by its vid. Using a unique custom identifier is strongly encouraged. ChargebacksList: type: object properties: object: type: string enum: - List total_count: type: integer description: Integer count of the number of items in the returned list. data: type: array items: $ref: '#/components/schemas/Chargebacks' url: type: string description: The query string provided in the request next: type: string description: >- The route (partial URL) to the next Chargebacks 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 Chargebacks object (string to select the “previous”); included id should match that of the first object returned here. description: A list of Chargebacks. Error: required: - code type: object properties: code: type: string message: type: string description: The object contains information about the error. Chargebacks: type: object properties: object: type: string description: Value is “Chargeback” vid: description: >- A Globally Unique Identifier (GUID) for this object. Assigned by CashBox. allOf: - $ref: '#/components/schemas/VID' amount: type: number description: >- This chargeback’s settlement amount, which usually matches the amount of the original transaction. In some cases, customers charge back only part of a transaction. (Vindicia does not provide information on the items that are charged back.) example: 26.99 currency: type: string description: >- ISO 4217 Currency Code of this chargeback’s settlement amount. The default is USD. default: USD presentment_amount: type: number description: >- The amount charged back (in the presentment currency), which usually matches the amount of the original transaction. Specify this attribute if the original transaction was processed with Chase Paymentech in a currency other than USD. example: 26.99 presentment_currency: type: string description: >- The ISO 4217 currency code of this transaction at presentment. The default is USD default: USD division_number: type: string description: >- The number of your division or group your payment processor used when processing the original Transaction. Chase Paymentech refers to this number as the Division Number; Litle calls it the Report Group; MeS calls it the Profile ID. reason_code: type: string description: Your bank’s case number for this Chargeback object, if any. reference_number: type: string description: Your bank’s reference number for this Chargeback object, if any. merchant_number: type: string description: Your bank’s merchant number, which identifies you as the merchant. transaction_id: type: string description: >- Your unique identifier for the transaction associated with this Chargeback object. If CashBox generated the transaction, for example, for a recurring bill, CashBox created this ID for you when processing the transaction with your payment processor. If you did not process the transaction through CashBox, but only reported it to Vindicia, then this ID must match the order number you used when processing the transaction with your payment processor. transaction_timestamp: type: string description: >- A time stamp that specifies the date and time when the original transaction occurred. format: date-time processor_received_timestamp: type: string description: >- A time stamp that specifies the date and time when your bank received the chargeback from the customer. format: date-time posted_timestamp: type: string description: >- A time stamp that specifies the date and time when the chargeback was posted in the Vindicia database. The difference in time between the chargeback, and this posted time stamp, will depend on the frequency at which Vindicia downloads chargebacks from your bank or payment processor. format: date-time status_changed_timestamp: type: string description: >- A time stamp that specifies the date and time for the last status change. format: date-time status: type: string description: >- Can be Challenged, CollectionsLost, CollectionsNew, CollectionsWon, Duplicate, Expired, Incomplete, Legitimate, Lost, New, NewSecondChargeback, Pass, Represented, Responded, Retrieval, Won enum: - Challenged - CollectionsLost - CollectionsNew - CollectionsWon - Duplicate - Expired - Incomplete - Legitimate - Lost - New - NewSecondChargeback - Pass - Represented - Responded - Retrieval - Won merchant_user_id: type: string description: >- Your unique identifier for the account of the customer who conducted the original transaction. note: type: string description: >- Notes on the Chargeback object. Vindicia personnel might make entries here during the dispute process. metadata: type: string description: >- A set of key/value pairs that you can attach to an object. Useful for storing additional information. VID: maxLength: 128 type: string description: >- A Globally Unique Identifier (GUID) for this object. This value is generated by Vindicia. securitySchemes: basicAuth: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.