> ## Documentation Index
> Fetch the complete documentation index at: https://docs.m1amdocs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieves all Billing Plans.
> Retrieves filtered list of recorded Billing Plan.
## OpenAPI
````yaml /marketONE/MarketONEAPIs.yaml get /slmgw/v1/billing_plans
openapi: 3.0.1
info:
title: MarketONE APIs
description: >
The MarketONE OpenAPIs provide a quick and easy way to access MarketONE
features and your data. These APIs let Resellers (Service Providers) and
Merchants work together to resell products and handle billing on a single
platform.
With an API key, you can authenticate and perform various tasks, like
accessing and managing data. You can use an HTTP client in any programming
language to send HTTP requests to MarketONE to create, edit, or delete data.
The data you work with, like subscriptions or entitlements, are called
resources, and each resource has its own endpoint (URL).
The MarketONE OpenAPIs use built-in HTTP features, like HTTP authentication
and HTTP verbs, which are easy for standard HTTP clients to understand. They
also use HTTP response codes to indicate errors. All responses, including
errors, are in JSON format, but our API libraries convert them into objects
that are specific to the programming language you're using.
You can also download the MarketONE OpenAPIs in a YAML file, which is easy
to read and manage.
For more information about the MarketONE OpenAPIs, see the [API Reference
Guide for Merchants](https://docs.saas.amdocs.com/bundle/b_partnerAPIGuide/)
and the [API Reference Guide for Resellers (Service
Providers)](https://docs.saas.amdocs.com/bundle/b_aggregatorAPIGuide).
## Other MarketONE APIs
Other MarketONE APIs, such as the [Reseller (CSP) Adapter
OpenAPIs](https://docs.saas.amdocs.com/bundle/MarketONECSPAdapter/page/index.html),
the [Merchant (OTT) Service
Callbacks](https://docs.saas.amdocs.com/bundle/MarketONEOTTServiceCallbacks/page/index.html),
and the [Commerce Gateway
OpenAPIs](https://docs.saas.amdocs.com/bundle/Amdocs_Media-Commerce-Gateway-Latest-resolved/page/index.html),
are available to provide additional services for specific organizations.
# Environments
MarketONE provides two distinct environments for testing and production:
- **Prodtest environment**: this is a pre-production environment allowing
you to test your application with test data. Use server
.
- **Production environment**: this is the live environment for the
real-world implementation of data. Use server .
# HTTP Verbs
The MarketONE OpenAPIs support the following HTTP verbs:
- **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).
- **PUT**: Create a new resource or replace a resource with the request
payload.
- **DELETE**: Remove ownership or hierarchical association between certain
resources.
# Example
## Request Example
```
POST /v1/entitlement
Content-Type: application/json
{
"account": {
"id": "2922fbf1-1dc4-2293-9d0e-c9a46630ad6e"
},
"subscriptionId": "ef1917b8-4a06-4595-9998-718799a33ed6",
"productCodes": [
"Basic_Addon"
],
"metadata": {
"email": "j.smith@email.com"
}
}
```
## Response Example
```
Response: 200 OK
Content-Type: application/json
[
{
"partnerSubscriptionId": "80e08955-b0e9-4ba6-b882-b24230bfc703",
"account": {
"id": "0006fbf1-1ac4-4793-9d0e-c0a0080ad6e",
"partnerCustomerId": "1bbbb3a5-0f05-4009-b4ae-b01f7eba7g"
},
"subscriptionId": "ef1417b8-4a06-7775-8518-718714a33ed2",
"externalPartnerSubscriptionId": "7d50531-31eb-45f9-91ce-6355250f5501",
"partnerCode": "PRTNR",
"productCode": "Basic_Addon",
"createdDate": "2024-05-04T17:38:10.889",
"updatedDate": "2024-05-04T17:38:11.160",
"startServiceDate": "2024-05-04T17:38:10.889",
"serviceStatus": "PROVISION-COMPLETE"
}
]
```
# Status Codes
MarketONE uses the following HTTP response codes to indicate the success or
failure of an API request.
| Code | Status | Description |
| ------- | ------ | ------------------- |
| **200** | OK | Everything worked as expected. |
| **201** | OK | Everything worked as expected. |
| **400** | Bad Request | The request was unacceptable, often due to missing
a required parameter. Other possibilities include: - A parameter
doesn't fit the data type
- A parameter is outside the maximum or
minimum boundaries of what can be accepted.
|
| **401** | Unauthorized | Couldn’t authenticate your request. This could be
due to a wrong or invalid API key. |
| **403** | Forbidden | Authentication failed. Check your username and
password. |
| **404** | Not Found | The requested resource doesn’t exist. |
| **409** | Conflict | |
| **429** | Too Many Requests | Too many requests were made to the API too
quickly. |
| **500** | Internal Server Error | |
| **501** | Not Implemented | |
| **503** | Service Unavailable | We’re temporarily offline for maintenance.
Please try again later. |
# Authentication
API keys are required to make requests to the MarketONE OpenAPIs. In Partner
Ecosystem Management, Resellers (Service Providers) can conveniently
[generate an API
key](https://docs.saas.amdocs.com/bundle/b_userGuideForResellers/page/topics/apiKeysAggregatorManage_t.html).
Merchants can also [generate an API key for each Reseller (Service Provider)
partnership](https://docs.saas.amdocs.com/bundle/b_userGuideForMerchants/page/topics/apiKeysManage_t.html)
in Partner Ecosystem Management. After you authenticate with your API
key(s), you can access resources through the MarketONE OpenAPIs.
Each API key is a JSON Web Token (JWT) that doesn't expire. For every API
call you make to the MarketONE OpenAPIs, the API key must be included in the
header (`X-API-KEY`) of the call to ensure trusted communication. All
communication is HTTP(s) based and supports SSL/TLS encryption.
# Errors
All error responses will return an error object.
# Attributes
| Name | Type | Required/Optional | Description |
| ------- | ------ | ------ | ------ |
| **code** | string | required | The error type, such as
"authentication-required" (401) or "not-found" (404). |
| **message** | string | required | A human-readable message providing more
detailed information about the error. |
| **validationErrors** | object | optional | An array of validation errors
with **code** and **message** attributes provided. |
license:
name: Amdocs Inc.
url: http://www.amdocs.com
version: Released
servers:
- url: https://int-prodtest.m1amdocs.io/
description: Sandbox server (uses test data)
- url: https://int.m1amdocs.com/
description: Production server (uses live data)
security: []
paths:
/slmgw/v1/billing_plans:
get:
tags:
- billing plans
- marketplace
summary: Retrieves all Billing Plans.
description: |
Retrieves filtered list of recorded Billing Plan.
operationId: searchAllBillingPlan
parameters:
- name: M1-Organization-Code
in: header
description: >-
The aggregator organization code. Organization code must be provided
either via HTTP header or query parameter. If both are provided,
HTTP header will be used.
required: false
style: simple
explode: false
schema:
maxLength: 16
type: string
- name: organizationCode
in: query
description: >-
The aggregator organization code. Organization code must be provided
either via HTTP header or query parameter. If both are provided,
HTTP header will be used.
required: false
style: form
explode: true
schema:
maxLength: 16
type: string
- name: limit
in: query
description: A limit on the number of objects to be returned, between 1 and 100.
required: false
style: form
explode: true
schema:
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.
required: false
style: form
explode: true
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.
required: false
style: form
explode: true
schema:
type: string
- name: filter
in: query
description: >
The filtering conditions: property names or property paths using
filtering operators and values.
The supported operators are:
| Operator | Description |
| ------- | --------|
| eq | Equal |
| ne | Not equal
| gt | Greater than
| ge | Greater than or equal
| lt | Less than
| le | Less than or equal
| sw | Start with
| ew | End with
| co | Contains
| and | Logical and
| or | Logical or
| not | Logical negation
| ( ) | Precedence grouping
Precedence order for logical operators: not, and, or.
required: false
style: form
explode: true
schema:
type: string
responses:
'200':
description: >-
JSON A list array with a data property that contains an array of up
to limit Billing Plan, starting after the specified starting_after
Billing Plan (or ending before the specified ending_before Account).
Each entry in the array is a full Billing Plan object. If no more
Billing Plan are available, the resulting array will be empty. This
request should never throw an error.
* “total_count”: Integer count of the number of Billing Plans in the
returned list.
* “url”: The query string provided in the request
* “next”: The route (partial URL) to the next Billing Plan object
(string to select the “next”); included id should match that of the
last object returned here
* “previous”: The route (partial URL) to the previous Billing Plan
object (string to select the “previous”); included id should match
that of the first object returned here
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BillingPlanList'
example: >-
{ "object": "List", "data": [ { "object": "BillingPlan", "id":
"plan_496968", "vid":
"161b240d52e6f344ec3206c7f06f334e566d2d3c", "created":
"2022-03-31T11:50:32+00:00", "description": "Simple Monthly Plan
with Trial", "status": "Active", "periods": { "object": "List",
"data": [ { "object": "BillingPlanPeriod", "type": "Day",
"quantity": 7, "cycles": 1, "prices": { "object": "List",
"data": [ { "object": "BillingPlanPrice", "amount": 10,
"currency": "USD" } ], "total_count": 1 },
"do_not_notify_first_bill": false }, { "object":
"BillingPlanPeriod", "type": "Month", "quantity": 1, "cycles":
1, "prices": { "object": "List", "data": [ { "object":
"BillingPlanPrice", "amount": 49.99, "currency": "USD" } ],
"total_count": 1 } } ], "total_count": 2 },
"skip_initial_billing_notification": false, "metadata": { "plan
info": "trial billing plan" }, "entitlements": { "object":
"List", "data": [ { "object": "Entitlement", "id": "ent_p1235",
"description": "Access to ent_p1235" } ], "total_count": 1 },
"times_to_run": "1", "used_on_subscriptions": false } ],
"total_count": 3, "url": "/billing_plans?limit=1", "next":
"/billing_plans?limit=1&starting_after=plan_496968", "previous":
"/billing_plans?limit=1&ending_before=plan_496968" }
'400':
description: Invalid Request
content:
application/json:
schema:
$ref: '#/components/schemas/400Error'
'401':
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/404Error'
'500':
description: Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/500Error'
security: []
components:
schemas:
BillingPlanList:
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/BillingPlan_1'
limit:
type: string
description: A limit on the number of objects to be returned, between 1 and 100.
starting_after:
type: string
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.
ending_before:
type: string
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
description: A list of Billing Plan.
400Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- invalid-request
message:
type: string
validationErrors:
type: array
items:
$ref: '#/components/schemas/400ValError'
Error:
required:
- code
type: object
properties:
code:
type: string
message:
type: string
description: The object contains information about the error.
404Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- not-found
message:
type: string
500Error:
required:
- code
type: object
properties:
code:
type: string
enum:
- server-error
message:
type: string
BillingPlan_1:
type: object
properties:
object:
type: string
description: Value is "BillingPlan"
enum:
- BillingPlan
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The date and time the plan was created.
format: datetime
description:
type: string
description: A CSP-specified description of this offering.
status:
type: string
description: >-
CSPs may define whether they want to declare a plan as available to
offer. Values can be Active,Suspended
enum:
- Active
- Suspended
tax_classification:
type: string
description: >-
The tax classification or code to be used with any plan-level
charges.
br_tax_category:
type: string
description: enum(Category)
trial:
description: Optionally declares an initial trial period for this plan.
allOf:
- $ref: '#/components/schemas/BillingPlanPeriod'
periods:
type: array
description: >-
Defines the sequential billing periods in the plan, each with its
own billing schedule and terms.
items:
$ref: '#/components/schemas/BillingPlanPeriod'
billing_notification_days:
type: integer
description: >-
Number of days prior to schedule billing at which CashBox will send
email notification.
trial_end_notification_days:
type: integer
description: >-
For the trial period, this replaces billing_notification_days,
indicating the number of days prior to end of a trial to send the
trial end email.
skip_initial_billing_notification:
type: boolean
description: >-
Determines whether to send a billing notification for the initial
period.
end_of_life:
type: string
description: The date after which the plan should not be offered.
format: datetime
metadata:
$ref: '#/components/schemas/METADATA_1'
entitlements:
type: array
description: Entitlements granted by active subscriptions on this plan.
items:
$ref: '#/components/schemas/Entitlement'
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for
transactions associated with a subscription using this billing plan.
grace_period_override:
type: integer
description: >-
Number of days after the billing date when, if payment is not
received, the Subscription is stopped and the customer is
disentitled; overrides the global CSP default setting, if both are
set.
minimum_commitment:
type: integer
description: >-
Number of billing cycles the customer is contractually obligated to
complete before cancelling. The only impact this has is upon the
cancelling a Subscription.
cancel_fees:
$ref: '#/components/schemas/BillingPlanCancelFee'
times_to_run:
type: string
description: >-
The number of times the sequence of Billing Periods should be
repeated. Valid input includes positive integers (Default is null).
entitlements_valid_for:
type: string
description: >-
The length of time for which Entitlements are valid after the last
Billing date (Default is null).
repeat_every:
type: string
description: >-
If a Billing Period set repeats, this value defines the length of
time after the first billing that the set should repeat.
season_set:
description: The SeasonSet to which the Billing Plan applies. (May be null.)
allOf:
- $ref: '#/components/schemas/SeasonSet_1'
days_before_season_to_bill:
type: integer
description: >-
Optional setting when using a season set to control the integer
number of days before a season starts to bill.
days_entitled_before_season:
type: integer
description: >-
Optional setting when using a season set to control the integer
number of days customer is entitled before a season starts
days_entitled_after_season:
type: integer
description: >-
Optional setting when using a season set to control the integer
number of days after a season ends a customer remains entitled.
entitled_off_season:
type: boolean
description: >-
Optional setting when using a season set to continue entitling
customer between seasons.
used_on_subscriptions:
type: boolean
description: Signifies if Billing Plan has been used on an Active Subscription
400ValError:
required:
- code
type: object
properties:
code:
type: string
message:
type: string
ID_1:
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.
VID_1:
maxLength: 128
type: string
description: >-
A Globally Unique Identifier (GUID) for this object. This value is
generated by Vindicia.
BillingPlanPeriod:
type: object
properties:
object:
type: string
description: Value is “BillingPlanPeriod”
enum:
- BillingPlanPeriod
type:
type: string
description: Unit of time a period describes. Values can be Day,Week,Month,Year
enum:
- Day
- Week
- Month
- Year
quantity:
type: integer
cycles:
type: integer
prices:
type: array
description: >-
A price for each defined currency for each period. Optional -
Billing Plans do not require pricing (can be priced at the
item/product level).
items:
$ref: '#/components/schemas/BillingPlanPrice'
METADATA_1:
type: object
description: >-
Metadata are sets of key-value pairs and are useful for storing
additional, structured information on an object. This object is used to
store a list of keys, which you create and associate with text string
values. You use these key-value pairs to store custom data for your own
internal tracking purposes, or to store CashBox specific data for
defined CashBox purposes.
The metadata field supports key-value pairs with the following
limitations:
Keys can be up to 256 characters
Keys can be any string that is needed, except only CashBox can prefix
keys with vin:
Values can be up to 1024 characters
In some cases metadata from one object will be inherited automatically
from one object to another that is spawned from it. e.g. metadata on a
Subscription and SubscriptionItem will be inherited by all Transactions
and TransactionItems that result from them.
Entitlement:
type: object
properties:
object:
type: string
description: Value is “Entitlement”
enum:
- Entitlement
id:
type: string
description: A CSP-specified unique identifier.
description:
type: string
description: The CSP-specified description of the entitled service.
account:
$ref: '#/components/schemas/Account_1'
subscription:
$ref: '#/components/schemas/Subscription_1'
billing_plan:
$ref: '#/components/schemas/BillingPlan_1'
subscription_item:
$ref: '#/components/schemas/SubscriptionItem_1'
product:
$ref: '#/components/schemas/Product_1'
starts:
type: string
description: The date/time at which entitlement did or will begin.
format: datetime
ends:
type: string
description: The date/time at which entitlement did or will end.
format: datetime
active:
type: boolean
description: Indicates whether this Entitlement is currently active.
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).
BillingPlanCancelFee:
type: object
properties:
object:
type: string
description: Value is "BillingPlanCancelFee"
amount:
type: string
description: The amount of the fee charged to the customer.
format: decimal
currency:
type: string
description: ISO 4217 Currency Code of price.
description: List of early cancel fees for various currencies.
SeasonSet_1:
type: object
properties:
object:
type: string
description: Value is "SeasonSet"
enum:
- SeasonSet
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The date and time the plan was created.
format: datetime
seasons:
type: array
description: An array of Seasons that make up the SeasonSet.
items:
$ref: '#/components/schemas/Season_1'
metadata:
$ref: '#/components/schemas/METADATA_1'
description: The SeasonSet object defines an array of seasons, with an identifier.
BillingPlanPrice:
type: object
properties:
object:
type: string
description: Value is “BillingPlanPrice”
amount:
type: number
description: price
currency:
type: string
description: >-
The [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code
of price.
price_list_name:
type: string
description: >-
Name of price list containing this price. This is free-form string
of 255 characters or less
token_amount:
description: The number of tokens required to purchase (if token-priced).
allOf:
- $ref: '#/components/schemas/TokenAmount'
Account_1:
required:
- id
- name
- object
type: object
properties:
object:
type: string
description: Value is “Account”
enum:
- Account
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
external_id:
type: string
description: >-
An additional merchant-specified unique identifier for when you have
two external (non-CashBox) systems using two different
identification schemes for the same customer. It can be used in
place of vid or i
created:
type: string
description: The date/time the Account was created.
format: datetime
parent:
description: The parent (Account) id or vid of this Account
allOf:
- $ref: '#/components/schemas/Account_1'
default_currency:
type: string
description: >-
The currency used on subscriptions and transactions belonging to
this Account when not explicitly specified. An [ISO
4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code.
email:
type: string
description: The email address associated with this Account.
email_type:
type: string
description: The email format type preferred by this customer.
enum:
- html
- multipart
- plaintext
language:
type: string
description: The language (code) preferred for communications.
notify_before_billing:
type: boolean
description: >-
Whether or not to send this customer pre-billing notification
(emails).
company:
type: string
description: The company name of the customer if a business Account.
name:
type: string
description: The name of the person primarily associated with this Account.
shipping_address:
$ref: '#/components/schemas/Address_1'
payment_methods:
$ref: '#/components/schemas/Account_1_payment_methods'
metadata:
$ref: '#/components/schemas/METADATA_1'
tax_exemptions:
type: array
description: Tax Exemptions registered for this Account.
items:
$ref: '#/components/schemas/TaxExemption'
tokens:
type: array
description: The token balances for this Account.
items:
$ref: '#/components/schemas/TokenAmount_1'
credit:
type: array
description: The account-level credit balances for this Account.
items:
$ref: '#/components/schemas/Credit'
entitlements:
type: array
description: The account-level entitlements for this Account.
items:
$ref: '#/components/schemas/Entitlement'
tax_use_code:
type: string
description: Special Tax Handling rules defined with CSP’s tax service.
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 CashBox 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.
Subscription_1:
required:
- account
- id
- items
- object
- status
type: object
properties:
object:
type: string
description: Value is “Subscription”.
enum:
- Subscription
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The date/time at which the subscription was requested.
account:
$ref: '#/components/schemas/Account_1'
billing_plan:
$ref: '#/components/schemas/BillingPlan_1'
payment_method:
$ref: '#/components/schemas/PaymentMethod_1'
currency:
type: string
description: >-
An [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code.
A subscription’s charges must be in a single currency.description
string An optional customer-facing identifier or descriptive name
for the subscription
status:
type: string
description: >-
The status of the subscription from a service and entitlement
perspective.
enum:
- Pending Activation
- Active
- Pending Cancel
- Cancelled
- Expired
- Processing
- Deleted
- Dryrun
- Unknown
- Upgraded
- Legacy Suspended
- Bogus AutoBill Status
- Paused
- Pending Pause
billing_state:
type: string
description: The financial state of the subscription.
enum:
- Free/Trial
- Billing Completed
- Failed To Collect
- Free Period
- Bogus BillingState
- Paused
- Good Standing
- Grace Period
- In Retry
- Legacy Unknown BillingState
- Overdue
- Pending Acceptance
- Terminated
- Unbilled
- Unknown
- Unusable PaymentMethod
- Pending Resume
- Pending Pause
starts:
type: string
description: The date/time the subscription starts service.
format: datetime
ends:
type: string
description: The date/time the subscription ends service.
format: datetime
entitled_through:
type: string
description: >-
The date/time to which the subscription will entitle service if no
further payments are made – a “paid thru” date based on billing
schedule and grace period.
format: datetime
items:
$ref: '#/components/schemas/Subscription_1_items'
source_ip:
type: string
description: Optional source IP Address at sign-up.
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for
transactions from this subscription.
billing_day:
type: integer
description: >-
The day of the month on which the subscription is (typically)
billed. Often called an “anniversary date.”
minimum_commitment:
type: integer
description: >-
Number of billing cycles customer is obligated to maintain the
subscription. Cancelling before this time requires CSP to “force”
cancellation.
affiliate:
type: string
description: >-
Affiliate or channel identifier, if any, under which the
subscription was submitted.
sub_affiliate:
type: string
description: A more granular or subordinate affiliate identifier.
notify_on_transition:
type: boolean
description: >-
Indicates whether to send an expiration or trial-end email
notification using the days-in-advance configuration in the Billing
Plan.
most_recent_billing:
$ref: '#/components/schemas/Transaction_1'
most_recent_refunds:
type: array
description: >-
A list of any refunds associated with the Transaction in
most_recent_billing.
items:
$ref: '#/components/schemas/Refund_1'
next_billing:
$ref: '#/components/schemas/Transaction_1'
metadata:
description: >-
A set of key/value pairs that you can attach to an object. Useful
for storing additional information. Subscription metadata will be
inherited by resulting transactions.
allOf:
- $ref: '#/components/schemas/METADATA_1'
credit:
$ref: '#/components/schemas/Credit'
statement_format:
type: string
description: >-
Instructions for if/how to include the invoice statement for this
subscription. Values can be Attachment, DoNotSend,Inline
enum:
- Attachment
- DoNotSend
- Inline
invoice_terms:
type: integer
description: >-
Net Terms (in days); after this many days from a billing, the
invoice will be considered delinquent.
statement_offset:
type: integer
description: Days before scheduled billing to deliver the statement.
statement_template:
type: string
description: Template to use for statement generation.
billing_plan_campaign_code:
type: string
description: >-
The Campaign code redeemed on this AutoBill against the price of the
Billing Plan. To apply a Campaign, use this field to pass in a valid
Coupon or Promotion code. Note This data member will not be
returned. Only supported for Single Discount.
billing_plan_campaign_id:
type: string
description: >-
The unique identifier for a Campaign applied to this AutoBill’s
BillingPlan. This is a read-only field returned by Vindicia for
informational purposes. Values sent in with a SOAP call will be
ignored. Read only. Only supported for Single Discount.
unkonwn_starts:
type: boolean
description: Used to create a Subscription Pending Activation.
balance:
type: number
mandate:
$ref: '#/components/schemas/Mandate_1'
cancel_reason:
$ref: '#/components/schemas/CancelReason_1'
policy:
description: The policy object governing Subscription behavior.
allOf:
- $ref: '#/components/schemas/SubscriptionPolicy'
billing_plan_discount_tickets:
type: array
description: Only supported for Stackable Discounts.
items:
$ref: '#/components/schemas/DiscountTicket_1'
SubscriptionItem_1:
required:
- id
- object
- product
type: object
properties:
object:
type: string
description: Value is “SubscriptionItem”
enum:
- SubscriptionItem
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
index:
type: integer
description: Sequential index of all items on the subscription.
product:
$ref: '#/components/schemas/Product_1'
amount:
type: number
description: The unit price of the item.
currency:
type: string
description: >-
The [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code
of this item.
rate_plan:
$ref: '#/components/schemas/RatePlan_1'
metadata:
$ref: '#/components/schemas/METADATA_1'
quantity:
type: number
description: >-
The unit quantity for the item; for license-based products this is
the license/seat quantity.
campaign_code:
type: string
description: Campaign code to be redeemed. Only supported for Single Discount.
token:
$ref: '#/components/schemas/Token_1'
cycles:
type: integer
description: >-
The number of billing cycles for which this item should bill (0 =
life of the Subscription)
cycles_remaining:
type: integer
description: >-
If a billing cycle limit is defined, this is the number of billing
cycles left to bill.
created:
type: string
description: The datetime this item was added to the subscription.
format: datetime
ends:
type: string
description: >-
The datetime this item was removed from the subscription (end of
service).
format: datetime
starts:
type: string
description: >-
The datetime this item was effective/started on the subscription
(start of service).
format: datetime
discount_tickets:
type: array
description: Only supported for Stackable Discounts.
items:
$ref: '#/components/schemas/DiscountTicket_1'
replaces:
$ref: '#/components/schemas/SubscriptionItem_1'
replaced_by:
$ref: '#/components/schemas/SubscriptionItem_1'
Product_1:
required:
- descriptions
- id
- object
- status
type: object
properties:
object:
type: string
description: Value is “Product”
enum:
- Product
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The date/time the object was created.
format: datetime
descriptions:
$ref: '#/components/schemas/Product_descriptions'
status:
type: string
description: >-
CSPs may define whether they want to declare a product as available
to offer.
enum:
- Active
- Suspended
tax_classification:
type: string
description: The tax classification or code for this product.
br_tax_category:
type: string
enum:
- Goods
- Services
default_billing_plan:
$ref: '#/components/schemas/BillingPlan_1'
default_rate_plan:
$ref: '#/components/schemas/RatePlan_1'
end_of_life:
type: string
description: >-
The date/time after which this product should be treated as
out-of-service.
format: datetime
metadata:
$ref: '#/components/schemas/METADATA_1'
entitlements:
$ref: '#/components/schemas/Product_1_entitlements'
inherited_entitlements:
type: array
description: >-
If a Product has other products bundled with it, the Entitlements
for the Products in the bundle will be returned
items:
$ref: '#/components/schemas/Entitlement'
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for
transactions associated with a subscription using this product.
credit_granted:
$ref: '#/components/schemas/Credit'
prices:
$ref: '#/components/schemas/Product_1_prices'
bundled_products:
type: array
description: >-
Other Products considered “bundled” under this one; purchase of this
product’s SKU under a single price, grants the entitlements
associated with it and with all bundled products (as of the time of
creation).
items:
$ref: '#/components/schemas/Product_1'
description: >-
The Product object represents a unique CSP 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.
Season_1:
type: object
properties:
object:
type: string
description: Value is “Season”
enum:
- Season
description:
type: string
description: Free-form description of the season, <= 2048 characters.
starts:
type: string
description: The date/time at which the Season begins.
format: datetime
ends:
type: string
description: The date/Time at which the Season ends.
format: datetime
description: >-
Season objects represent a CSP-defined calendar-based “season”
indicating when a particular service offering is provided. Often
indicates a sporting or entertainment industry season. In CashBox, most
simply stored as a date range with a description; and grouped into
Season Sets as needed (to allow for sequential season-based entitlement
and billing, from one season to the next where the dates for a given
season change each year).
TokenAmount:
type: object
properties:
object:
type: string
enum:
- TokenAmount
token:
$ref: '#/components/schemas/Token'
amount:
type: integer
description: The balance of tokens in the grant.
source:
type: string
description: >-
The TokenAmount object represents the token-based credit detail
associated with a particular grant of token credits.
Address_1:
type: object
properties:
object:
type: string
description: Value is “Address”
enum:
- Address
vid:
$ref: '#/components/schemas/VID_1'
name:
type: string
description: The name of the person or contact associated with this address.
line1:
type: string
description: Address Line 1
line2:
type: string
description: Address Line 2
line3:
type: string
description: Address Line 3
city:
type: string
county:
type: string
district:
type: string
description: State, Province, or District
postal_code:
type: string
country:
type: string
phone:
type: string
fax:
type: string
latitude:
type: number
longitude:
type: number
description: The Address object represents a physical or mailing address.
Account_1_payment_methods:
type: object
properties:
object:
type: string
description: Must be "List"
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/PaymentMethod_1'
description: The payment methods on file for this Account.
TaxExemption:
type: object
properties:
object:
type: string
description: Value is “TaxExemption”
enum:
- TaxExemption
region:
type: string
description: Exempt geography or jurisdiction
exemption_id:
type: string
description: Exemption ID or certificate number filed with tax authority.
active:
type: boolean
description: Required.
description: >-
A certificate or other recorded tax exemption on file for a customer
(account) or specific subscription or transaction.
TokenAmount_1:
type: object
properties:
object:
type: string
enum:
- TokenAmount
token:
$ref: '#/components/schemas/Token_1'
amount:
type: integer
description: The balance of tokens in the grant.
source:
type: string
description: >-
The TokenAmount object represents the token-based credit detail
associated with a particular grant of token credits.
Credit:
type: object
properties:
object:
type: string
description: Value is “Credit”
enum:
- Credit
token_amounts:
type: array
description: Tokens granted
items:
$ref: '#/components/schemas/TokenAmount'
currency_amounts:
type: array
description: Currency credits granted
items:
$ref: '#/components/schemas/CurrencyAmount'
description: >-
The Credit object represents a service credit granted to an account or
subscription, taking the form of either currency, token, or time
amounts.
PaymentMethod_1:
type: object
properties:
object:
type: string
description: Value is "PaymentMethod".
enum:
- PaymentMethod
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The date/time the object was created.
format: datetime
type:
type: string
enum:
- Amazon
- ApplePay
- Boleto
- CarrierBilling
- CreditCard
- DirectDebit
- ECP
- GooglePay
- ExternalBilling
- HostedPage
- MerchantAcceptedPayment
- MilitaryStar
- PayPal
- Skrill
- Token
- Venmo
credit_card:
$ref: '#/components/schemas/CreditCard'
ecp:
$ref: '#/components/schemas/Ecp'
direct_debit:
$ref: '#/components/schemas/DirectDebit'
paypal:
$ref: '#/components/schemas/Paypal'
amazon:
$ref: '#/components/schemas/Amazon'
skrill:
$ref: '#/components/schemas/Skrill'
boleto:
$ref: '#/components/schemas/Boleto'
hosted_page:
$ref: '#/components/schemas/HostedPage'
token:
$ref: '#/components/schemas/Token_1'
merchant_accepted_payment:
$ref: '#/components/schemas/MerchantAcceptedPayment_1'
carrier_billing:
$ref: '#/components/schemas/CarrierBilling_1'
external_billing:
$ref: '#/components/schemas/ExternalBilling_1'
apple_pay:
$ref: '#/components/schemas/ApplePay'
google_pay:
$ref: '#/components/schemas/GooglePay'
military_star:
$ref: '#/components/schemas/MilitaryStar'
venmo:
$ref: '#/components/schemas/Venmo'
metadata:
$ref: '#/components/schemas/METADATA_1'
account_holder:
type: string
description: Name of the account holder.
billing_address:
$ref: '#/components/schemas/Address_1'
customer_specified_type:
type: string
description: Optional CSP- or customer-specified type description.
customer_description:
type: string
description: Optional CSP- or customer-specified card (method) description.
currency:
type: string
description: The [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code.
primary:
type: boolean
description: Primary/default payment method for the account.
active:
type: boolean
description: Active and available for use.
validation_status:
$ref: '#/components/schemas/TransactionStatus_1'
external_token:
type: string
description: >-
Token value identifying a tokenized payment method used. Relevant
for different payment methods such as tokenized credit cards or
Venmo.
policy:
type: object
description: The policy object governing Payment Method behavior.
'policy: enable_3ds':
type: boolean
description: >-
Enable the 3DS payment standard for strong customer authentication.
A merchant configuration serves as a higher level indication whether
3DS is used by the merchant. When available for use, you can enable
the 3DS flow per subscription, transaction, or payment method.
'policy: min_chargeback_probability':
type: integer
description: >-
If Chargeback Probability from risk scoring is greater than this,
the transaction will fail. Default is 100.
'policy: ignore_cvn_policy':
type: boolean
description: >-
Indicates whether to evaluate any custom or default CVN (card
security code) policy.
'policy: ignore_avs_policy':
type: boolean
description: >-
Indicates whether to evaluate any custom or default AVS (card
Address Verification Service) policy.
'policy: validate':
type: boolean
description: >-
Enable to validate the PaymentMethod object first before creating or
updating. If validation fails, the PaymentMethod is not updated.
'policy: source_ip':
type: string
description: >-
The customer IP address from which the customer specified details
for this payment method. It must be specified if you want Subscribe
to evaluate risk score for this payment method.
linked_subscription:
type: boolean
description: >
Indicates whether the payment method is used in a subscription. if
true, the payment method is used by a subscription.
Note: The Subscribe Merchant Portal 2.0 does not allow you to remove
a Payment Method from an account if there are subscriptions using
that Payment Method.
Subscription_1_items:
type: object
properties:
object:
type: string
description: Must be "List"
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/SubscriptionItem_1'
description: The product-based line items for the subscription.
Transaction_1:
type: object
properties:
object:
type: string
description: Value is “Transaction”
enum:
- Transaction
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The time this transaction was initiated.
format: datetime
amount:
type: number
description: >-
The net amount of the charge presented by this transaction, as a
decimal. Must be positive (zero allowed).
original_amount:
type: number
description: >-
Used with a partial payment; this read-only field reflects the
original amount of the transaction, as a decimal.
currency:
type: string
description: >-
The [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code
of this transaction
division_number:
type: string
description: >-
The CSP’s division, reporting or processing group as defined with
their payment processor.
previous_id:
type: string
description: The identifier of a previous version of this transaction.
account:
$ref: '#/components/schemas/Account_1'
source_payment_method:
$ref: '#/components/schemas/PaymentMethod_1'
dest_payment_method:
$ref: '#/components/schemas/PaymentMethod_1'
ecp_transaction_type:
type: string
description: For ECP/ACH-specific types.
enum:
- All
- Inbound
- InboundOutbound
- NA
- Outbound
- Transfer
status_log:
type: array
description: >-
A log of various TransactionStatus entries associated with this
transaction.
items:
$ref: '#/components/schemas/TransactionStatus_1'
payment_processor:
type: string
description: The payment processor used for processing this transaction.
payment_processor_transaction_id:
type: string
description: The identifier assigned to the Transaction by the Payment Processor.
shipping_address:
$ref: '#/components/schemas/Address_1'
metadata:
description: >-
A set of key/value pairs that you can attach to an object. Useful
for storing additional information. For transactions resulting from
a subscription, the metadata is also inherited from the
subscription.
allOf:
- $ref: '#/components/schemas/METADATA_1'
items:
type: array
description: >-
The array of Transaction Items belonging to this transaction. Items
correspond to the charges, discounts, credits, and taxes.
items:
$ref: '#/components/schemas/TransactionItem_1'
affiliate:
type: string
description: >-
CSP’s ID for the channel or affiliate associated with this
transaction, if any. This is a free-form string of 128 characters or
less.
sub_affiliate:
type: string
description: >-
Affiliate ID for a more granular channel component (see
CSP_affiliate_id).
user_agent:
type: string
description: >-
Information on the source of the transaction, such as the Customer’s
user-agent string, as presented by the browser.
preferred_notification_language:
type: string
description: >-
ISO language code string. Transaction value will override any
language setting on the account.
source_mac_address:
type: string
description: >-
MAC address of the customer (primarily intended for ISP usage), may
be left blank if unavailable or inappropriate.
source_ip:
type: string
description: End-customer’s source IP associated with this transaction.
billing_descriptor:
type: string
description: >-
Optional “soft descriptor” to send to the payment processor for this
transaction.
sales_tax_address:
$ref: '#/components/schemas/Address_1'
verification_code:
type: string
description: >-
External verification response (e.g. Verified by Visa, MasterCard
SecureCode).
subscription_sequence:
type: integer
description: >-
The subscription’s billing cycle for which this transaction collects
funds. As a zero-based index, this indicates the renewal number.
billing_plan_sequence:
type: integer
description: >-
The billing cycle for which this transaction collects funds - as
counted as a zero-based index from the last billing plan change for
the associated subscription.
mandate:
$ref: '#/components/schemas/Mandate_1'
original_billing_date:
type: string
description: >-
The original scheduled billing date associated with the billing for
which this transaction collects funds. For an initial attempt, this
is the same as the transaction date; for a retry transaction this is
the original attempt date.
format: datetime
billing_attempt:
type: integer
description: >-
The zero-based index counting the number of transaction attempts
this particular transaction represents in collecting for given
subscription billing cycle.
subscription:
$ref: '#/components/schemas/Subscription_1'
score:
type: integer
description: The chargeback and fraud risk score generated by Vindicia.
score_calculated:
type: string
description: The datetime the score was calculated.
format: datetime
score_calculated_orig:
type: string
description: The datetime the score was originally calculated.
format: datetime
score_codes:
type: array
description: The reason codes justifying the risk score.
items:
$ref: '#/components/schemas/ScoreCode_1'
distance_ip_ba:
type: number
description: The distance from the IP Address to the Billing Address.
avs_code:
type: string
description: AVS Code
cvn_code:
type: string
description: CVN Code.
cvn_checked:
type: boolean
description: Shows if the CVN was checked for this transaction.
policy:
$ref: '#/components/schemas/TransactionPolicy'
to_be_captured:
type: boolean
description: Indicator of whether the transaction is currently pending capture.
payment_provider_response:
type: string
description: >
The response from the payment provider and the applicable action to
take. Common responses are:
* **Successful: Approved**: The Payment Provider has accepted the
transaction.
* **Soft Failure: Decline**: A payment capture attempt has failed
but may indicate that an additional attempt may succeed, such as
when the customer has insufficient funds. The classification of the
type of fail is performed according to the error code returned by
the payment provider and follows industry standards and
recommendations.
* **Hard Failure: Reject**: A payment capture attempt has failed and
indicates that additional attempts will subsequently fail, such as
when the account has been terminated. The classification of the type
of fail is performed according to the error code returned by the
payment provider. Hard fails are not resubmitted for capture.
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.
Refund_1:
type: object
properties:
object:
type: string
description: Value is “Refund”
enum:
- Refund
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The date/time at which the refund was requested.
format: datetime
transaction:
$ref: '#/components/schemas/Transaction_1'
refund_items:
type: array
description: >-
For item-level refunds, specifies the transaction items to refund
with details.
items:
$ref: '#/components/schemas/RefundItem_1'
refund_distribution_strategy:
type: string
description: >-
Defines strategy for distributing refund amount across the original
TransactionItems. Default is None.
enum:
- None
- SpecifiedItems
- RemainingBalance
amount:
type: number
description: >-
Amount of the refund. Must be positive (non-zero) and less than or
equal to the as-yet-un-refunded balance of the specified
transaction. Ignored if refundItems are specified.
amount_includes_tax:
type: boolean
description: whether the amount is tax-inclusive or -exclusive
currency:
type: string
description: >-
The [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code
of this transaction; defaults to USD.
metadata:
$ref: '#/components/schemas/METADATA_1'
reference_string:
type: string
description: Read-only. Information provided by payment processor.
note:
type: string
description: Free-form CSP-specified notes about refund.
token_action:
type: string
description: Action to take with any Tokens paid on transaction. Default None.
enum:
- CancelNegativeBalance
- CancelZeroBalance
- None
credit:
$ref: '#/components/schemas/Credit'
status:
type: string
description: Processing status of refund.
enum:
- Complete
- Failed
- Processing
- Reported
refunded_by:
type: string
description: Refund initiated by
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).
Mandate_1:
type: object
properties:
object:
type: string
description: Value is “Mandate”
enum:
- Mandate
created:
type: string
description: The date/time at which the mandate was recorded into Vindicia.
format: datetime
identifier:
type: string
description: Externally provided unique identifier for the Mandate (agreement).
status:
type: string
description: Current Mandate status.
enum:
- Active
- Cancelled
- Expired
- Failed
- Pending
description: >-
The mandates object represents the end-custom approval for a one-time or
recurring billing using their provided bank account details. A common
requirement for UK and SEPA direct debit payment methods.
CancelReason_1:
type: object
properties:
object:
type: string
description: Value is “CancelReason”
enum:
- CancelReason
reason_code:
type: string
description: >-
The reason code assigned for the cancellation. Can be 15 characters
or fewer.
description:
type: string
description: >-
A description of the reason for the cancellation. Can be up to 255
characters.
SubscriptionPolicy:
type: object
properties:
object:
type: string
description: Value is "SubscriptionPolicy"
enum:
- SubscriptionPolicy
immediate_auth_failure_policy:
type: string
description: >-
How to respond to Authorization failure while processing first
Transaction for an AutoBill. Defaults to doNotSaveAutoBill
enum:
- doNotSaveAutoBill
- putAutoBillInRetryCycle
- putAutoBillInRetryCycleIfPaymentMethodIsValid
validate_for_future_payment:
type: boolean
description: >-
Validate the payment method for future payments if initial
Transaction is not being created/Authorised. AutoBill will not be
saved if validation is requested and fails
min_chargeback_probability:
type: integer
description: >-
Chargeback Probability from risk scoring is greater than this, the
transaction auth will fail. Default is 100 (all transactions
succeed).
ignore_avs_policy:
type: boolean
description: Set to true, to not evaluate any custom or default avs policy
ignore_cvn_policy:
type: boolean
description: Set to true, to not evaluate any custom or default cvn policy
campaign_code:
type: string
description: >-
Optional coupon or promotion code, used to obtain a discount on this
AutoBill. Only supported for Single Discount.
reason_code:
type: string
description: Optional reason code for cancelling the AutoBill
full_auth_delayed_capture:
type: boolean
description: >-
If true and the Subscription has a future start date or a free trial
period, the Subscription will get created with an auth for the full
amount of the first paid for period that will not be captured until
that payment period starts
enable_3ds:
type: boolean
description: >-
Disable 3DS authentication flow for this transaction if false; if
true or undefined, the 3DS authentication flow will be determined by
the use3ds merchant option flag
discount_tickets_to_distribute:
type: array
description: >-
Array of DiscountTickets that are to be applied to eligible
SubscriptionItems (or BillingPlan). To apply a campaign, add a
DiscountTicket containing a valid coupon or promotion code to this
array. Only supported for Stackable Discounts.
items:
$ref: '#/components/schemas/DiscountTicket_1'
description: The policy object governing how a Subscription is to be created.
DiscountTicket_1:
required:
- campaign_code
- object
type: object
properties:
object:
type: string
description: Value is "DiscountTicket"
id:
type: string
description: >-
Optional Merchant-supplied identifier for this a DiscountTicket.
Only supported for Stackable Discounts.
vid:
description: >-
A Globally Unique Identifier (GUID) for this object. Assigned by
CashBox. Only supported for Stackable Discounts.
allOf:
- $ref: '#/components/schemas/VID_1'
campaign_code:
type: string
description: >-
Redemption string (CampaignCode.id) which will be redeemed to create
DiscountTicket. Only supported for Stackable Discounts.
state:
type: string
description: >-
Read-only field indicating DiscountTicket state. Only supported for
Stackable Discounts.
enum:
- PreDisco2
- Unredeemed
- RedemptionFailed
- Redeemed
- Active
- Inactive
added_date:
type: string
description: >-
Read-only field indicating date that DiscountTicket was added. Only
supported for Stackable Discounts.
format: dateTime
removed_date:
type: string
description: >-
Read-only field indicating date that DiscountTicket was removed.
Only supported for Stackable Discounts.
format: dateTime
end_date:
type: string
description: >-
Read-only field indicating date that DiscountTicket Inactive date.
Only supported for Stackable Discounts.
format: dateTime
start_billing_sequence:
type: integer
description: >-
Subscription sequence when DiscountTicket is to start. Only
supported for Stackable Discounts.
end_billing_sequence:
type: integer
description: >-
Read-only attribute indicating Subscription sequence when
DiscountTicket will cease to be active. Only supported for Stackable
Discounts.
previous_discount_ticket_id:
type: string
description: >-
Id of the DiscountTicket that this DiscountTicket will follow. Only
supported for Stackable Discounts.
previous_discount_ticket_vid:
type: string
description: >-
VID of the DiscountTicket that this DiscountTicket will follow. Only
supported for Stackable Discounts.
campaign_id:
type: string
description: >-
Read-only field containing the unique identifier for the Campaign
associated with this DiscountTicket. Only supported for Stackable
Discounts.
metadata:
description: Only supported for Stackable Discounts.
allOf:
- $ref: '#/components/schemas/METADATA_1'
RatePlan_1:
type: object
properties:
object:
type: string
description: Value is "RatePlan"
enum:
- RatePlan
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
created:
type: string
description: The date/time the object was created.
format: date-time
description:
type: string
description: Optional description of the rated service offering.
multiply_rated_units_by:
type: string
description: >-
Tier pricing rule. EachRespective charges units “in” that tier at
its price; HighestApplicable is volume pricing, charging at the peak
unit level’s tier for all units. Values can be
EachRespectiveTier,HighestApplicableTier.
enum:
- EachRespectiveTier
- HighestApplicableTier
rated_unit:
description: Defined rating unit of measure.
allOf:
- $ref: '#/components/schemas/RatedUnit'
tier:
type: array
description: Successive pricing tiers based on unit “from/to” limits
items:
$ref: '#/components/schemas/RatePlanTier'
rounding_decimals:
type: integer
description: >-
Number of digits for rounding; Excel’s ROUND function- 0 = nearest
integer, 2 = 2 decimal places, -2 means = nearest hundred, etc.
format: int32
included_units:
type: integer
description: >-
Number of units included for free; tier 1 starts after included
units have been recorded.
format: date-time
minimum_fee:
type: array
description: Minimum charge per billing period (one price per currency)
items:
$ref: '#/components/schemas/RatePlanPrice'
maximum_fee:
type: array
description: Maximum charge per billing period (one price per currency)
items:
$ref: '#/components/schemas/RatePlanPrice'
rate_plan_model:
type: string
description: >-
Determines pre-paid (licenses or seats billed in advance) or
post-paid (usage recorded throughout the period and billed at period
end. Values can be LicenseBased,UsageBased
enum:
- LicenseBased
- UsageBased
status:
type: string
description: >-
Merchants may define whether they want to declare a plan as
available to offer. Values can be Active,Suspended.
enum:
- Active
- Suspended
has_event_recorded:
type: boolean
description: >-
Read-only field that tells whether this RatePlan has had any events
recorded on it or not.
metadata:
type: string
description: >-
A set of key/value pairs that you can attach to an object. Useful
for storing additional information.
description: >-
Rate Plans represents a pre-defined rating schedule - tier-based pricing
for rated products (e.g. usage). Both pre-paid (aka License-based) and
post-paid (metered, aka 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.
Token_1:
type: object
properties:
object:
type: string
description: Value is “Token”
enum:
- Token
id:
$ref: '#/components/schemas/ID_1'
vid:
$ref: '#/components/schemas/VID_1'
description:
type: string
description: Text describing the token type
description: >-
The token object provides a way to offer virtual currencies or track the
balance of a consumable service item.
Product_descriptions:
type: object
properties:
object:
type: string
description: Must be "List"
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/ProductDescription'
description: Language-specific product/service descriptions
Product_1_entitlements:
type: object
properties:
object:
type: string
description: Must be "List"
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/Entitlement'
description: >-
Entitlements granted by active subscriptions using this product on one
or more subscription items.
Product_1_prices:
type: object
properties:
object:
type: string
description: Must be "List"
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/ProductPrice_1'
description: >-
Default (i.e. “List”) prices for the product; one price per currency
code. Prices can be overridden at purchase or with modification.
Token:
type: object
properties:
object:
type: string
description: Value is “Token”
enum:
- Token
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
description:
type: string
description: Text describing the token type
description: >-
The token object provides a way to offer virtual currencies or track the
balance of a consumable service item.
CurrencyAmount:
type: object
properties:
object:
type: string
description: Value is “CurrencyAmount”
enum:
- CurrencyAmount
vid:
$ref: '#/components/schemas/VID'
currency:
type: string
description: An [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) Currency Code.
amount:
type: number
description: The currency amount of the credit.
metadata:
$ref: '#/components/schemas/METADATA'
sort_value:
type: integer
description: Order of precedence value.
description:
type: string
description: Text provided upon credit grant.
reason:
type: string
description: Text provided upon credit grant.
granted_by_cashbox:
type: boolean
granted:
type: string
description: The date and time the credit was originally granted.
format: datetime
account:
$ref: '#/components/schemas/AccountRef'
subscription:
$ref: '#/components/schemas/SubscriptionRef'
description: >-
The CurrencyAmount object represents the currency credit detail
associated with a particular grant of currency credits.
CreditCard:
type: object
properties:
object:
type: string
description: Value is "CreditCard"
vid:
$ref: '#/components/schemas/VID_1'
account:
type: string
description: >-
The Primary Account Number (PAN) aka Credit Card Number
(encrypted/hidden when returned) For non-Subscribe methods (e.g.,
Transaction::score), this field must be left blank. The precise form
used here will vary with the exact payment method.
bin:
type: string
description: >-
The first 6 digits of the PAN (Bank Identifier Number). If the
account field is provided, this may be left blank and it will be
filled in by Vindicia.
type:
type: string
description: Issuing card network information.
enum:
- AX
- CU
- DC
- DD
- DI
- JC
- MC
- MD
- SW
- VI
last_digits:
type: string
description: The last 4 digits of the PAN
account_length:
type: integer
description: The number of digits in the PAN
hash_type:
type: string
description: >-
The algorithm used for hashing the account number. If this value is
not provided we assume SHA1. Values can be sha1, md5
enum:
- sha1
- md5
account_hash:
type: string
description: >-
A hash of the full PAN. Any non-numeric characters should be removed
prior to hashing. If the account number is provided, this may be
left blank and the hash will be calculated by Vindicia. The exact
length and format of this string may depend upon the hash algorithm
chosen.
expiration_date:
type: string
description: >-
Expiration date of the credit card. Should be formatted as YYYYMM.
For example, July, 2028 should be sent as 202807.
extended_card_attributes:
$ref: '#/components/schemas/ExtendedCardAttributes'
extended_verification:
$ref: '#/components/schemas/ExtendedVerification'
extended_verification_response:
$ref: '#/components/schemas/ExtendedVerificationResponse'
cvn:
type: string
description: >-
CVV (Card Verification Value) or CVN (Card Verification Number)
printed on the card.
last_au_request_date:
type: string
description: Timestamp of the most recent Account Updater request.
format: datetime
last_update_date:
type: string
description: Timestamp of the most recent credit card update.
format: datetime
au_response_code:
type: string
description: >-
Response code from the payment provider for the most recent Account
Updater request.
au_response_message:
type: string
description: >-
Reply from the payment provider for the most recent Account Updater
request
description: This object defines an instance of a specific Credit Card.
Ecp:
type: object
properties:
object:
type: string
description: Value is "ECP"
account:
type: string
description: >-
The full bank account number for this payment. Be certain to enter
this number in full if you are using the associated payment method
for Subscribe Transactions. Note:- Subscribe does not validate ECP
accounts algorithmically, and partially masks the account number
when returning it in response to your call.
hash_type:
type: string
description: >-
The type of hash algorithm used if you specify the accountHash
field. Subscribe supports SHA1 hashing only. You need not specify
this field if the associated payment method is for a Transaction
processed through Subscribe. Can be sha1, md5
enum:
- sha1
- md5
account_hash:
type: string
description: >-
A hash of the full account number. Specify this string only if you
are not specifying the full account number when reporting a
Transaction for ChargeGuard.
routing_number:
type: string
description: >-
The bank routing number for an ACH or ECP account. Be certain to
enter the correct number if you are using the associated payment
method for Subscribe Transactions.
account_type:
type: string
description: >-
Required. The type of bank account that issues this electronic
check. Can be ConsumerChecking, ConsumerSavings, CorporateChecking,
CorporateSavings
enum:
- ConsumerChecking
- ConsumerSavings
- CorporateChecking
- CorporateSavings
last_digits:
type: string
description: >-
The truncated last part of the full account number, typically the
last four or five digits of that number. Specify this string only if
you are not specifying the full account number or its hash in the
accountHash field for security when reporting transactions to
Vindicia for ChargeGuard. You need not specify this field if the
associated payment method is for a one-time or recurring transaction
processed through Subscribe.
account_length:
type: string
description: >-
The length (number of digits) of the full account number. Specify
this string only if you are not specifying the full account number
when reporting a Transaction for ChargeGuard.
allowed_transaction_type:
type: string
description: >-
The enumerated Transaction types allowed for ECP- or ACH-based
Transactions that use this PaymentMethod object. Can be All,
Inbound, InboundOutbound, NA, Outbound, Transfer
enum:
- All
- Inbound
- InboundOutbound
- NA
- Outbound
- Transfer
description: This object defines ACH (aka ECP) details.
DirectDebit:
type: object
properties:
object:
type: string
description: Value is “DirectDebit”
account:
type: string
description: >-
The number of the customer’s bank account from which to deduct
payment. To use the associated PaymentMethod object for one-time or
recurring transactions, you must specify the full account number.
last_digits:
type: string
description: >-
The last part of the account number for display purposes, generally
the last four digits. If the account field is provided, this may be
left blank and it will be filled in by Vindicia.
account_length:
type: integer
description: >-
Length of the total account number. If the full account number is
submitted, this field may be left blank; Vindicia will calculate it.
hash_type:
type: string
description: Can be sha1, md5
enum:
- sha1
- md5
account_hash:
type: string
description: >-
A hash of the full account number. Any non-numeric characters should
be removed prior to hashing. If the account number is provided, this
may be left blank and the hash will be calculated by Vindicia. The
exact length and format of this string may depend upon the hash
algorithm chosen.
country_code:
type: string
description: >-
The ISO-3166-1 two-letter code for the country in which the related
bank account is located. This code must match the country code
specified in the PaymentMethod object’s billing address.
bank_sort_code:
type: string
description: >-
The European bank sort code that identifies the bank that houses the
customer’s bank account whose number is specified in the account
field. This code is similar to the bank routing number in the United
States. Required You if this is for a Transaction processed through
Subscribe unless the countryCode attribute is set to NL or BE.
rib_code:
type: string
description: The RIB code for an DirectDebit account (France only)
branch_code:
type: string
description: The branch code for an Direct Debit account
description: This object defines Direct Debit details (vary by country/system)
Paypal:
type: object
properties:
object:
type: string
description: Value is "PayPal"
paypal_email:
type: string
description: PayPal Email Address of User
payer_id:
type: string
description: A unique PayPal subscriber account identification PayerID
return_url:
type: string
description: >-
The URL to which you would like customers to be redirected after
they have successfully completed payment transactions on the PayPal
site. This is often your confirmation page, on which the customer
confirms the order and payment or the billing agreement. Example:-
http://myshoppingcart.merchant.com
cancel_url:
type: string
description: >-
The URL to which you would like to redirect customers after a
cancelled or unsuccessful transaction on the PayPal site. Example:-
http://tryagain.merchant.com
request_reference_id:
type: boolean
description: >-
When processing the initial Transaction for a Subscription, ask
PayPal for a Reference ID that can be used in the future for
recurring billing. This works only if you have been previously
approved for Reference Transactions by PayPal.
reference_id:
type: string
description: >-
PayPal field REFERENCEID, which is the Billing Agreement ID or
Reference Transaction ID associated with a PayPal Billing Agreement.
If you enter a value for this data member, set requestReferenceId to
false.
description: This object defines PayPal Express Checkout account details.
Amazon:
type: object
properties:
object:
type: string
description: Value is "Amazon"
billing_agreement_id:
type: string
description: >-
The Amazon billing agreement identifier. This value is returned by
the OffAmazonPayments getAmazonBillingAgreementId API call and
should be passed to Vindicia here.
buyer_name:
type: string
description: The name Amazon associates with the billing agreement identifier.
buyer_email:
type: string
description: The email Amazon associates with the billing agreement identifier.
physical_address:
$ref: '#/components/schemas/Address_1'
billing_address:
$ref: '#/components/schemas/Address_1'
address_verification_code:
type: string
description: >-
The address verification code Amazon received when validating the
buyer’s payment method.
description: This object defines Amazon Payments account details.
Skrill:
type: object
properties:
object:
type: string
description: Value is "Skrill"
billing_agreement_id:
type: string
description: The Skrill 1-Tap billing agreement identifier (rec_payment_id).
pay_from_email:
type: string
description: The pay_from_email associated with the Skrill account.
payment_type:
type: string
description: The Skrill payment_type code.
return_url:
type: string
description: >-
The URL to which you would like to redirect customers after a
Skrill-based Transaction is completed.
cancel_url:
type: string
description: >-
The URL to which you would like to redirect customers if they do not
approve payment via Skrill.
description: This object defines Skrill digital wallet details.
Boleto:
type: object
properties:
object:
type: string
description: Value is "Boleto"
fiscal_number:
type: string
description: >-
The fiscal number that appears on the customer’s Boleto Bancário
payment slip. This number, formally called Casadastro de Pessoas, is
formatted in a specific pattern (modulo 11).
description: >-
This object defines Boleto Bancario details. Note:- fiscalNumber is
associated with a customer, not a payment method, and is analogous to a
U.S. social security number. Treat fiscalNumber as Personally
Identifiable Information (PII).
HostedPage:
type: object
properties:
object:
type: string
description: Value is "HostedPage"
payment_provider:
$ref: '#/components/schemas/PaymentProvider_1'
country_code:
type: string
description: The ISO 3166 ( alpha-2 ) country code for customer’s location,
return_url:
type: string
description: >-
The URL to which you would like customers to be redirected after
they have successfully completed the Hosted Page transaction. This
is often your confirmation page.
language:
type: string
description: Required. The ISO 639-1 language matrix code for the payment pages.
processor_payment_method_id:
type: string
description: The payment method to use for the Transaction.
billing_agreement_id:
type: string
description: >-
If supported by the processor, the token used to rebill this payment
method in the future.
description: This object defines Externally Hosted Payment Page details.
MerchantAcceptedPayment_1:
type: object
properties:
object:
type: string
description: Value is "MerchantAcceptedPayment"
amount:
type: string
description: >-
The amount paid by a customer. This value must be 0 for
PaymentMethods attached to Subscriptions. Note:- Merchant Accepted
Payment Methods may be attached to Subscriptions to indicate that
the customer should be invoiced (rather than automatically charged).
format: decimal
currency:
type: string
description: >-
The ISO 4217 currency code for the payment. Must match the currency
for charges on the Invoice/Subscription.
token:
$ref: '#/components/schemas/Token_1'
created:
type: string
description: The time that payment occurred.
format: datetime
payment_type:
type: string
description: The type of payment accepted by the merchant.
payment_id:
type: string
description: The ID of the payment accepted by the merchant.
account:
type: string
description: The full account number.
last_digits:
type: string
description: >-
The last part of the account number for display purposes, generally
the last four digits.
account_length:
type: integer
description: >-
Length of the total account number. If the full account number is
submitted, this field may be left blank.
hash_type:
type: string
description: >-
The algorithm used to hash the account number. If this value is not
provided, Subscribe will use assume SHA1. Can be:- md5 or sha1
enum:
- md5
- sha1
account_hash:
type: string
description: >-
A hash of the full account number. Any non-numeric characters should
be removed prior to hashing. If the account number is provided, this
may be left blank and the hash will be calculated by Subscribe.
note:
type: string
description: An optional memo regarding the payment made.
description: This object defines Pay By Invoice details.
CarrierBilling_1:
type: object
properties:
object:
type: string
description: Value is "CarrierBilling"
phone_number:
$ref: '#/components/schemas/PhoneNumber_1'
encoded_phone_number:
type: string
description: >-
Read Only. The payment provider-encoded phone number used in the
Transaction.
carrier:
type: string
description: >-
The identifier for the carrier, either read from the phone or
entered by the customer.
payment_provider:
$ref: '#/components/schemas/PaymentProvider_1'
currency:
type: string
description: >-
ISO 4217 Currency Code for either the static_price_inc_salestax, or
the dynamic_target_price. (For dynamic pricing, the customer
currency will be determined by the customer region/countryCode.)
country_code:
type: string
description: ISO 3166-1 alpha-2 Country Code for the customer’s location.
price_criteria:
$ref: '#/components/schemas/PriceCriteria_1'
description: This object defines Telco carrier billing details.
ExternalBilling_1:
type: object
properties:
object:
type: string
enum:
- ExternalBilling
vid:
$ref: '#/components/schemas/VID_1'
bill_receiver:
type: string
description: >-
The payment provider. In this case the payment provider is another
billing system implemented in the integration.
payment_channel:
type: string
description: >-
The customer paymentChannelId in the billing system. The best
practice is that this is the same as the CSPPaymentMethodId in the
PaymentMethod Object.
financial_account:
type: string
description: The customer financial account ID in the billing system.
ApplePay:
type: object
properties:
object:
type: string
description: Value is "ApplePay"
payment_instrument_name:
type: string
description: The paymentInstrumentName field from PKPayment.
payment_network:
type: string
description: The paymentNetwork from PKPayment.
transaction_identifier:
type: string
description: The transactionIdentifier field from PKPayment.
payment_data:
type: string
description: The paymentData field from PKPayment
expiration_date:
type: string
description: >-
Returns the expiration date of the credit card used for ApplePay.
Will be formatted as YYYYMM. For example, July, 2028 will be
returned as 202807.
format: datetime
description: This object defines Apple Pay details.
GooglePay:
type: object
properties:
object:
type: string
description: Value is "GooglePay"
payment_token:
type: string
description: >-
The encrypted paymentToken you receive after calling
GooglePaymentDataRequest.
eci_indicator:
type: string
description: ''
gateway_merchant:
type: string
description: ''
message_identifier:
type: string
description: ''
expiration_date:
type: string
description: ''
format: datetime
description: This object defines Google Pay details.
MilitaryStar:
type: object
properties:
object:
type: string
description: Value is "MilitaryStar"
vid:
type: string
description: >-
A Globally Unique Identifier (GUID) for this object. This field is
created by Subscribe.
account:
type: string
description: The MilitaryStar account number.
account_length:
type: integer
description: >-
Length of the total account number. If the full account number is
submitted, this field may be left blank; Vindicia will calculate it.
account_last_digits:
type: string
description: ''
account_hash:
type: string
description: >-
A hash of the full account number. Any non-numeric characters should
be removed prior to hashing. If the account number is provided, this
may be left blank and the hash will be calculated by Vindicia. The
exact length and format of this string may depend upon the hash
algorithm chosen. Currently this value is not returned (i.e. is
null) when you fetch this object from Vindicia e.g. via fetched
transactions
cid:
type: string
description: The Customer Identification Number, of the account holder.
cid_length:
type: integer
description: >-
Length of the cid. If the cid is submitted, this field may be left
blank; Vindicia will calculate it.
cid_last_digits:
type: string
description: >-
The last part of the cid for display purposes, generally the last
four digits. If the cid field is provided, this may be left blank
and it will be filled in by Vindicia.
cid_hash:
type: string
description: >-
A hash of the full cid. Any non-numeric characters should be removed
prior to hashing. If the account number is provided, this may be
left blank and the hash will be calculated by Vindicia. The exact
length and format of this string may depend upon the hash algorithm
chosen. Currently this value is not returned (i.e. is null) when you
fetch this object from Vindicia e.g. via fetched transactions
hash_type:
type: string
description: Can be:- md5 or sha1
enum:
- md5
- sha1
description: This object defines Military Star details.
Venmo:
type: object
properties:
object:
type: string
description: Value is "Venmo"
payment_method_nonce:
type: string
description: >-
A secure, one-time-use reference for payment information. This is a
limited-time identifier that is later in the process replaced by the
payment method's external_token.
customer_id:
type: string
description: A unique merchant account identification
default:
type: boolean
description: >-
True/false. Defines whether this is the default payment method for
the customer in the Braintree vault.
vaulted:
type: boolean
description: True/false. Defines whether the payment method has been vaulted.
created_at:
type: string
description: >-
A read-only attribute that displays the date and time that venmo
payment method was created in the Subscribe system.
format: datetime
image_url:
type: string
description: >-
Optional.This atribute can show a path to the payment provider's
provided image.
source_description:
type: string
description: >-
Optional. A venmo identifier that provides a short description of
the payment method, including the Venmo username.
username:
type: string
description: Optional. The customer's venmo username
venmo_user_id:
type: string
description: Optional. The venmo user's id for the customer.
description: This object defines Venmo details
TransactionStatus_1:
type: object
properties:
object:
type: string
description: Value is “TransactionStatus”
enum:
- TransactionStatus
status:
type: string
description: Status of the Transaction.
enum:
- New
- AuthorizationPending
- AuthorizedPending
- Authorized
- AuthorizedForValidation
- Cancelled
- Captured
- Settled
- Refunded
- Pending
created:
type: string
description: The effective datetime of this status
format: datetime
payment_method_type:
type: string
description: Type of Payment Method (clarifies status).
enum:
- CreditCard
- PayPal
- ECP
- DirectDebit
- Token
- HostedPage
- Boleto
- CSPAcceptedPayment
- CarrierBilling
- Amazon
- Skrill
- ApplePay
vin_avs:
type: string
description: AVS result.
enum:
- FullMatch
- PartialMatch
- NoMatch
- IssuerError
- NoOpinion
- NotSupported
funding_source_balance:
type: number
credit_card_status:
$ref: '#/components/schemas/CreditCardStatus'
TransactionItem_1:
type: object
properties:
object:
type: string
description: Value is “TransactionItem”
enum:
- TransactionItem
sku:
type: string
description: >-
The SKU or unique identifier of the product purchased with this item
(for one-time transactions this is an ad-hoc value.
index_number:
type: integer
description: Sequential index of all items on the transaction.
item_type:
type: string
name:
type: string
description: CSP-provided name or inherited description of the product. purchased
subscription_item:
$ref: '#/components/schemas/SubscriptionItem_1'
price:
type: number
description: unit price of this item
metadata:
$ref: '#/components/schemas/METADATA_1'
quantity:
type: number
description: >-
The unit quantity for the item; for license-based products this is
the license/seat quantity.
tax_classification:
type: string
description: The tax code or classification applicable to this item.
tokens:
type: array
description: >-
Tokens granted to the account on this transaction for purchasing
this item
items:
$ref: '#/components/schemas/TokenAmount_1'
campaign_code:
type: string
description: >-
Campaign code redeemed on this TransactionItem. Only supported for
Single Discount.
campaign_id:
type: string
description: >-
The unique identifier for a campaign applied to this item. Only
supported for Single Discount.
campaign_description:
type: string
description: >-
Detailed description of the campaign for the discount on this item,
if there is one. Only supported for Single Discount.
service_period_starts:
type: string
description: The start date for the period the charge on this item covers.
format: datetime
service_period_ends:
type: string
description: The end date for the period the charge on this item covers.
format: datetime
tax_type:
type: string
description: Fixed Tax definition (read only).
tax:
type: array
description: >-
array to list the individual tax items associated with the
corresponding transactionItem.
items:
$ref: '#/components/schemas/TaxItem_1'
related_transactions:
type: array
description: >-
List of CSPTransactionIds for all Transactions related to this item.
e.g. For a credit resulting from the removal of an SubscriptionItem,
this will contain the list of all Transactions that originally
billed for the item within the time frame covered by the credit.
items:
type: string
item_refunds:
type: array
description: Detail on item-level refunds applied to this item.
items:
$ref: '#/components/schemas/TransactionItemRefundSummary_1'
discount:
type: number
description: The total discount amount applied to this item.
subtotal:
type: number
description: The pre-tax (post-discount) subtotal.
total:
type: number
description: The grand total of this item
discount_tickets:
type: array
description: >-
Input list of DiscountTicket to apply to this TransactionItem. Only
supported for Stackable Discounts.
items:
$ref: '#/components/schemas/DiscountTicket_1'
item_discounts:
type: array
description: Only supported for Stackable Discounts.
items:
$ref: '#/components/schemas/TransactionItemDiscount'
tax_total:
type: number
description: The total tax on this item. Only supported for Stackable Discounts.
ScoreCode_1:
type: object
properties:
object:
type: string
description: Value is “ScoreCode”
enum:
- ScoreCode
id:
type: string
description: A Vindicia-specified unique ID.
description:
type: string
description: String description of the rule, e.g. “PRIOR_CB_IN_VERTICAL”
TransactionPolicy:
type: object
properties:
object:
type: string
description: Value is "TransactionPolicy"
enum:
- TransactionPolicy
min_chargeback_probability:
type: integer
description: >-
Chargeback Probability from risk scoring is greater than this, the
transaction auth will fail. Default is 100 (all transactions
succeed).
send_email_notification:
type: boolean
description: >-
Flag indicating whether an email notification should be sent upon
capture of this transaction
campaign_code:
type: string
description: >-
Optional coupon or promotion code, used to obtain a discount on this
Transaction. Only supported for Single Discount.
enable_3ds:
type: boolean
description: >-
Disable 3DS authentication flow for this transaction if false; if
true or undefined, the 3DS authentication flow will be determined by
the use3ds merchant option flag
ignore_avs_policy:
type: boolean
description: Set to true, to not evaluate any custom or default avs policy
ignore_cvn_policy:
type: boolean
description: Set to true, to not evaluate any custom or default cvn policy
discount_tickets_to_distribute:
type: array
description: >-
Array of DiscountTickets that are to be applied to eligible
TransactionItems. To apply a campaign, add a DiscountTicket
containing a valid coupon or promotion code to this array. Only
supported for Stackable Discounts.
items:
$ref: '#/components/schemas/DiscountTicket_1'
description: The policy object governing how a Transaction is to be processed.
RefundItem_1:
type: object
properties:
transaction_item_index_number:
type: number
description: >-
Sequence number assigned upon creation to a TransactionItem by
Vindicia. Either the transactionItemIndexNumber, or the sku, must be
specified for each RefundItem.
sku:
type: string
description: >-
SKU on the original transaction line item (sku need not be passed in
if the transactionItemIndexNumber is passed in). If the sku is
passed in, and can be used to uniquely identify the transaction
item, it will be used, otherwise an error will be returned.
description:
type: string
description: >-
Output only. A description of the TransactionItem, which will be
filled in by Vindicia from line item description on the original
Transaction.
amount:
type: number
description: >-
Amount of the requested refund for this item, in the currency of the
overall transaction. This amount must not exceed the original
TransactionItem amount, minus any discounts and minus the sum of all
prior refunds against this item. This field may be left blank if the
taxOnly field is set to true.
tax_only:
type: boolean
description: >-
If this is true, the amount parameter is ignored and the refund
amount will be the total of the as-yet unrefunded taxes for this
item.
taxes:
type: array
description: >-
Read-only array to list the taxes from the original TransactionItem
that are being refunded.
items:
$ref: '#/components/schemas/TaxItem_1'
RatedUnit:
type: object
properties:
name_singular:
type: string
description: Singular name of units.
name_plural:
type: string
description: Plural name of units.
RatePlanTier:
type: object
properties:
name:
type: string
rate_price:
type: array
description: >-
Required. An array of RatePlanPrice objects, which define the Price
(or prices) for this Tier (one price for each currency used).
items:
$ref: '#/components/schemas/RatePlanPrice'
charge_customer:
type: string
description: >-
Can be- FlatFee which defines a stepped pricing structure, in which
the customer is charged the ratePrice per Tier or PerUnit which
defines a graduated pricing structure, in which the customer is
charged the number of units accessed, multiplied by the ratePrice
per Tier.
enum:
- Flatfee
- PerUnit
begins_at_level:
type: integer
description: >-
The number of Units at which this Tier’s pricing structure takes
effect. The number of Units defined for each Tier runs from the
minimum value of the Tier, to one Unit less than the minimum value
of the next higher Tier. Typically the first tier would have
beginsAtLevel = 1. The final, highest tier is unbounded (infinite).
RatePlanPrice:
type: object
properties:
amount:
type: integer
description: Amount
currency:
type: string
description: ISO 4217 Currency Code.
ProductDescription:
type: object
properties:
object:
type: string
description: Value is “ProductDescription”
enum:
- ProductDescription
language:
type: string
description: >-
The 2 character ISO language code in which the product description
is written.
description:
maxLength: 256
type: string
description: >-
A description of this product written in language. A free-form
string of less than 256 characters.
ProductPrice_1:
type: object
properties:
object:
type: string
description: Value is “ProductPrice”
enum:
- ProductPrice
amount:
type: number
description: Value of the currency amount.
currency:
type: string
description: >-
ISO 4217 currency code to be used for this ProductPrice Amount.
Defaults to USD. Note that this is Mutually Exclusive of token
token:
$ref: '#/components/schemas/Token_1'
ID:
maxLength: 128
type: string
description: A unique identifier.
VID:
maxLength: 128
type: string
description: >-
A Globally Unique Identifier (GUID) for this object. This value is
generated by MarketONE.
METADATA:
type: object
additionalProperties:
type: string
properties:
key:
type: string
value:
type: string
description: >-
A set of key/value pairs that you can attach to an object. Useful for
storing additional information.
AccountRef:
type: object
properties:
object:
type: string
enum:
- Account
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
SubscriptionRef:
type: object
properties:
object:
type: string
enum:
- Subscription
id:
$ref: '#/components/schemas/ID'
vid:
$ref: '#/components/schemas/VID'
ExtendedCardAttributes:
type: object
properties:
object:
type: string
description: Value is "ExtendedCardAttributes"
browser_accept_header:
type: string
description: The contents of the customer's browser's HTTP Accept header.
browser_user_agent_header:
type: string
description: The contents of the customer browse HTTP User-Agent header.
browser_javascript_enabled:
type: string
description: Indicates if the browser supports javascript.
browser_language:
type: string
description: The language of the browser.
browser_remote_address:
type: string
description: The remote address of the merchant's customer.
browser_screen_resolution:
type: string
description: The screen resolution of the browser.
browser_screen_color_depth:
type: string
description: The screen color depth of the browser.
browser_timezone:
type: string
description: The time zone of the browser.
method_notification_url:
type: string
description: >-
The URL from which the merchant expects to receive the 3DS service
notification of device acknowledgement completion.
return_url:
type: string
description: >-
The URL to which the merchant wants the customers redirected after
the verification is completed.
nameValues:
type: object
description: >-
Additional fields required for SCA should be included in this array.
A name-value pair describing attributes not otherwise supported in
the object.
description: Additional credit card details returned from Payment Provider
ExtendedVerification:
type: object
properties:
object:
type: string
description: Value is "ExtendedVerification"
commercial_card:
type: integer
description: >-
Boolean indicator - True = Card is flagged as business/commercial.
Applicable Processors: CPT, Litle.
consumer_card:
type: integer
description: >-
Boolean indicator - True = Card is flagged as personal/consumer.
Applicable Processor: Litle.
credit_card:
type: integer
description: >-
Boolean indicator - True = Card is a credit or charge card.
Applicable Processors: Litle, MeS, Chase.
debit_card:
type: integer
description: >-
Boolean indicator - True = Card is a debit card. Applicable
Processors: Litle, MeS, Chase.
signature_debit_card:
type: integer
description: >-
Boolean indicator - True = Debit card uses “Signature” scheme.
Applicable Processor: CPT.
pinless_debit_card:
type: integer
description: >-
Boolean indicator - True = Debit card uses “Pinless” scheme.
Applicable Processor: CPT.
gift_card:
type: integer
description: >-
Boolean indicator - True = Card is a gift card. Applicable
Processors: Litle, MeS.
prepaid_card:
type: integer
description: >-
Boolean indicator - True = Card is a pre-paid card. Applicable
Processors: CPT, Litle, MeS.
payroll_card:
type: integer
description: >-
Boolean indicator - True = Card is a payroll/benefits card.
Applicable Processors: CPT, Litle.
healthcare_card:
type: integer
description: >-
Boolean indicator - True = Card is a benefits card. Applicable
Processors: CPT, Litle, MeS.
virtual_account_number:
type: integer
description: >-
Boolean indicator - True = Card is a virtual account. Applicable
Processor: Litle.
reloadable:
type: integer
description: >-
Boolean indicator - True = Prepaid card is re-loadable. Applicable
Processor: Litle.
country_of_issuance:
type: string
description: >-
Country Code for issuing bank. Possible values: USA, etc. Applicable
Processors: CPT, Litle.
durbin_regulated:
type: integer
description: 'Applicable Processor: CPT.'
affluent:
type: integer
description: >-
Boolean indicator - True = Account Holder flagged as “affluent”.
Applicable Processors: CPT, Litle.
mass_affluent:
type: integer
description: >-
Boolean indicator - True = Account Holder flagged as “mass
affluent”. Applicable Processor: Litle.
card_description:
type: string
description: >-
The returned description for the card. Applicable Processors: Litle,
MeS.
description: Input Details for ExtendedVerification of a credit card payment method.
ExtendedVerificationResponse:
type: object
properties:
object:
type: string
description: Value is "ExtendedVerificationResponse"
enum:
- ExtendedVerificationResponse
redirect_url:
type: string
description: >-
The URL merchant should redirect a customer to complete a
transaction.
post_values:
type: object
description: >-
Optional array of name/value pairs the merchant should POST to the
redirectUrl.
method_notification_url:
type: string
description: >-
The URL that will receive the notification of completion by 3DS
service.
method_url:
type: string
description: >-
The URL that should be used by the merchant to allow the 3ds service
to obtain browser and device information.
method_data:
type: string
description: >-
Base64 encoded JSON with the notification URL and the transaction
XID.
auth3ds_resp_code:
type: string
description: >-
Indicates the status response of the authentication from the 3DS
provider.
auth3ds_error_code:
type: string
description: >-
Indicates the error code of the authentication from the 3DS
provider.
PaymentProvider_1:
type: object
properties:
object:
type: string
description: Value is "PaymentProvider"
name:
type: string
description: Provider Name
dispute_address:
type: string
description: Contact address for written disputes.
dispute_email:
type: string
description: Contact email for electronic disputes.
dispute_uri:
type: string
description: Contact URL for online disputes.
auth_expiration_days:
type: integer
description: Default expiration timing (days) for un-captured authorizations.
auth_currency_override:
type: string
description: Currency override for Authorizations
metadata:
type: object
description: >-
A set of key/value pairs that you can attach to an object. Useful
for storing additional information.
description: >-
The payment providers object represents processor or payment channel
used to transact a particular charge.
PhoneNumber_1:
type: object
properties:
object:
type: string
description: Value is "PhoneNumber"
phone_type:
type: string
description: >-
Type or Use designation for the phone number. Value can be CS, Fax,
Home, Main, Mobile, Pager, Unspecified, Work
enum:
- CS
- Fax
- Home
- Main
- Mobile
- Pager
- Unspecified
- Work
country_code:
type: string
description: Country Code segment of a phone number.
area_code:
type: string
description: Area Code segment of a phone number.
local_number:
type: string
description: Local segment of a phone number (excluding extension).
extension:
type: string
description: Phone number extension.
raw_input:
type: string
description: Raw, unfiltered data input by customer.
description: >-
The payment providers object represents processor or payment channel
used to transact a particular charge.
PriceCriteria_1:
type: object
properties:
object:
type: string
description: Value is "PriceCriteria"
payment_provider:
$ref: '#/components/schemas/PaymentProvider_1'
currency:
type: string
description: >-
ISO 4217 Currency Code for for either the static_price_inc_salestax,
or the dynamic_target_price Overrides CarrierBilling.currency.
currency_code:
type: string
description: >-
ISO 3166-1 alpha-2 countryCode for customer location. Overrides
CarrierBilling.countryCode.
price_point_deviation_policy:
type: string
description: >-
The price deviation policy for dynamic price selection. Value can be
HiOnly, HiPreferred, LowOnly, LowPreferred, NearestNoPreference
enum:
- HiOnly
- HiPreferred
- LowOnly
- LowPreferred
- NearestNoPreference
dynamic_price_mode:
type: string
description: >-
Specifies which price point element is matched by the dynamic
pricing algorithm. Values can be PayoutGross, PayoutNet, Price
enum:
- PayoutGross
- PayoutNet
- Price
merchant_service_identifier:
type: string
description: Service identifier for Payment Provider/Merchant.
sub_merchant_identifier:
type: string
description: Optional identifier of sub-merchant associated with Transaction.
description:
type: string
description: ''
fwd_url:
type: string
description: >-
Overrides both the successful transaction forward-to URL and the
failed transaction forward-to URL.
static_selection_row_ref:
type: integer
description: Row number identifier in the static product/service price matrix
static_price_inc_sales_tax:
type: string
description: >-
Price including tax (the actual amount the consumer will pay). Used
with Transactions with static ‘exact match’ pricing.
format: decimal
dynamic_deviation:
type: integer
description: >-
The percent deviation (+/- 1000) from the target value that is
acceptable as a price point selection.
dynamic_match:
type: integer
description: >-
The percent deviation (+/- 1000) from the target value that is
classified as an exact match.
dynamic_target_price:
type: string
description: Target price in the specified currency for dynamic pricing.
format: decimal
description: Price Criteria details used with telco carrier billing payment methods.
CreditCardStatus:
type: object
properties:
object:
type: string
description: Value is “TransactionStatusCreditCard”
enum:
- CreditCardStatus
extended_verification:
$ref: '#/components/schemas/ExtendedVerificationResponse'
TaxItem_1:
type: object
properties:
object:
type: string
description: Value is “TaxItem”
jurisdiction:
type: string
description: Tax jurisdiction
name:
type: string
description: Tax description
amount:
type: number
description: Currency amount of assessed tax
external_tax_name:
type: string
external_tax_category:
type: string
external_jurisdiction_name:
type: string
tax_rate:
type: number
description: And individual tax assessed for a specified jurisdiction.
TransactionItemRefundSummary_1:
type: object
properties:
created:
type: string
format: datetime
amount:
type: string
format: decimal
tax:
type: number
tax_only:
type: boolean
refund:
$ref: '#/components/schemas/Refund_1'
TransactionItemDiscount:
type: object
properties:
object:
type: string
description: Value is “TransactionItemDiscount”
sku:
type: string
description: >-
The merchant's tracking key for this item which is derived from the
relevant Campaign. Only supported for Stackable Discounts.
name:
type: string
description: >-
A description of the discount which is based on the Campaign
itemDisplayText. Only supported for Stackable Discounts.
amount:
type: number
description: >-
Discount amount applied to the TransactionItem. Only supported for
Stackable Discounts.
discount_ticket:
description: Only supported for Stackable Discounts.
allOf:
- $ref: '#/components/schemas/DiscountTicket_1'
cycle:
type: integer
description: >-
For discounts with a fixed number of cycles, this indicates which
cycle this discount represents. Only supported for Stackable
Discounts.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.