External Billing Integration

One of the ways Partner Ecosystem Management can support an integration with a Reseller’s (Service Provider’s) external billing system is through the subscription management component (Commerce Engine). As a part of this setup, the integration is enabled in the subscription management component’s payment gateway. In the payment gateway, Partner Ecosystem Management has payment options for customers (such as credit card and PayPal), including an external billing option for Partner Ecosystem Management. When selected, this Partner Ecosystem Management external billing option initiates charge and refund file processing. Charge and refund files contain information Partner Ecosystem Management passes on to external billing systems for any charges and refunds generated by the subscription management component. Resellers (Service Providers) can then access and process the charge and refund files, applying the relevant amounts to customers’s bills. Charge files contain transactions for all customers and all charges during a particular period. The charges can be related to any of the following: a one-time payment, a recurring/renewal payment, or an upgrade/downgrade payment linked to a subscription service. Refund files contain details for any canceled or downgraded subscription items. Resellers are responsible for processing all charge and refund files and applying the relevant charge amounts and information to the customers’ bills.

Accessing and Processing Charge and Refund Files

To access the charge and refund files, Resellers must register with Client Technical Support and then use SFTP to get the files. The process of accessing and processing charge and refund files is as follows:

Partner Ecosystem Management generates the charge and refund files in the designated SFTP location.
The Reseller (Service Provider) accesses the charge and refund files (FIN and JSON files) via SFTP.
The Reseller processes the charges. If the Reseller can’t process the charges, the Reseller must send the error files (both the JSON and FIN files) to Partner Ecosystem Management within 24 hours. If the error files aren’t sent, the charges will be treated as successfully processed. The error files only contain the charges that failed to process. Errors are categorized into two categories: soft and hard. For soft errors (for example: a credit card without a balance), Partner Ecosystem Management will retry the transactions. These transactions will be included in the newly generated charge and/or refund files from Partner Ecosystem Management. Hard error transactions will be canceled after the grace period. Note: The Reseller has the ability to define the soft and hard error codes. The Reseller can also configure the grace period for hard errors.

Charge File Format and Structure

Charge files are in JSON format: VNDC_CHARGES_<yyyymmddhhmmss>.JSON. Each charge file includes an array of transaction item objects:

Main Object
Account
PaymentMethod
- ExternalBillingPaymentMethod Sub-object
Transaction_Item
TaxItem

Partner Ecosystem Management generates a FIN file with each charge JSON file in the following format: VNDC_CHARGES_<yyyymmddhhmmss>.FIN. Each FIN file includes a checksum. After establishing an SFTP connection, charge files can be found within this file structure: /download/charges/<YYYYMMDD>. Within the charges folder, there are separate folders for each day containing the charge files. Charge files are generated on an hourly basis, containing any relevant updates to new subscriptions and one-time charges. When the file is generated at midnight, it also updates renewal transaction data. Charge files are accessible for 7 days. The array of objects in the charge file are as follows: Main Object

Field Name	Type	Required or Optional	Description
id	String	Required	A Reseller (Service Provider)-specified unique identifier. Optionally, this object can be identified by its vid. For transactions created automatically, this field is assigned by Partner Ecosystem Management.
vid	String	Required	A Globally Unique Identifier (GUID) for this object. This field is created by Partner Ecosystem Management. This field will be used by the Reseller (Service Provider) to identify the transaction in their business support system (BSS).
created	Date/time	Required	The time the transaction was created.
amount	Decimal	Required	The net amount of the charge presented by this transaction, as a decimal. Must be positive (zero allowed).
currency	String	Required	ISO 4217 Currency Code of this transaction.
account	Account	Required	The account object related to this transaction. This object will contain the Reseller’s (Service Provider’s) Customer ID or BAN.
source_payment_method	PaymentMethod	Required	The payment method of the transaction.
metadata	Map	Optional	This can contain a pair of values. For transactions resulting from a subscription, the metadata is also inherited from the subscription.
subscription_id	String	Optional	For charges generated by subscriptions, the subscription’s Reseller (Service Provider) identifier will be presented.
subscription_vid	String	Optional	For charges generated by subscriptions, the subscription_vid (generated by the system) will be presented.
billing_attempt	Integer	Required	The zero-based index counting the number of transaction attempts this particular transaction represents in collecting for a given subscription billing cycle.
items	Array of Transaction_Item	Required	The array of transaction Items belonging to this transaction. Items correspond to the charges, discounts, credits, and taxes.
Account

Field Name	Type	Required or Optional	Description
id	String	Optional	A Reseller (Service Provider)-specified unique identifier. If not specified, this object can be identified by its vid. Depending on the Reseller, this can be used by the front end when creating the customer.
vid	String	Required	A Globally Unique Identifier (GUID) for this object. Assigned by Partner Ecosystem Management.
created	Date/time	Required	The date/time the account was created.
name	String	Required	The name of the person primarily associated with this account.
externalid	String	Required	This can contain an additional billing system customer identifier.
parent_account_id	String	Optional	In the case of a parent account, this is the Reseller (Service Provider) specified id of the parent account.
parent_account_vid	String	Optional	In the case of a parent account, this is the vid (system generated) of the parent account.
PaymentMethod

Field Name	Type	Required or Optional	Description
id	String	Required	A Reseller (Service Provider)-specified unique identifier. Optionally, this object can be identified by its vid.
vid	String	Required	A Globally Unique Identifier (GUID) for this object. This field is created by Partner Ecosystem Management.
created	Date/time	Required	The date/time the object was created.
type	Enum	Required	The type will be ExternalBilling.
type	Enum	Required	The type will be ExternalBilling.
external_billing	ExternalBilling Payment Method Sub-Object	Required	A new object that will save the specific identifier required by Amdocs.
ExternalBillingPaymentMethod Sub-Object

Field Name	Type	Required or Optional	Description
bill_receiver	Enum	Required	The value will be set to CES.
payment_channel	String	Required	This is the same as the id field.
Transaction_Item

Field Name	Type	Required or Optional	Description
sku	String	Required	The SKU or unique identifier of the product purchased with this item (for one-time transactions, this is an ad hoc value).
index_number	Integer	Required	The sequential index of all items on the transaction.
item_type	Enum	Required	Possible values are Purchase and Credit.
name	String	Optional	The Reseller (Service Provider)-provided name or inherited description of the product purchased.
price	Decimal	Optional	The unit price of this item. In the case of billing plans, the price is not set and therefore you can ignore this record.
metadata	Map	Optional	A set of key/value pairs that you can attach to an object.
quantity	Decimal	Required	The number of plans.
tax_classification	String	Optional	The tax code or classification applicable to this item.
campaign_id	String	Optional	The unique identifier for a campaign applied to this item.
campaign_description	String	Optional	The detailed description of the campaign for the discount on this item, if there is one.
service_period_starts	Date/time	Optional	The start date for the period the charge on this item covers.
service_period_ends	Date/time	Optional	The end date for the period the charge on this item covers.
tax_type	String	Optional	The fixed tax definition (read only).
tax	Array of TaxItem	Optional	Array to list the individual tax items associated with the corresponding transactionItem.
discount	Decimal	Optional	The total discount amount applied to this item.
subtotal	Decimal	Optional	The pre-tax (post-discount) subtotal (price * quantity + discount.)
total	Decimal	Required	The grand total of this item (subtotal + tax).
TaxItem

Field Name	Type	Required or Optional	Description
jurisdiction	String	Optional	The tax jurisdiction.
name	String	Optional	The tax name.
amount	Decimal	Required	The tax amount.
externalTaxName	String	Optional	As received from the tax generator.
externalTaxCategory	String	Optional	As received from the tax generator.
externalJurisdictionName	String	Optional	As received from the tax generator.
tax_rate	Decimal	Optional	As received from the tax generator.
Charge File Example

[
  {
    "vid": "3434a7404d041306708a4dfb05413e912c16209d",
    "object": "Transaction",
    "account": {
      "created": "2019-09-30T09:24:29-07:00",
      "object": "Account",
      "vid": "8f352fa6b6ef82946b6ff8cd1c044e915de78068",
      "external_id": null,
      "name": "",
      "id": "900002212"
    },
    "created": "2019-09-30T09:24:29-07:00",
    "currency": "USD",
    "amount": 9.99,
    "source_payment_method": {
      "created": "2019-09-30T09:24:29-07:00",
      "object": "PaymentMethod",
      "vid": "3155499a7d8e947ee26c950c23dbb1b43149075f",
      "external_billing": {
        "object": "ExternalBilling",
        "financial_account": null,
        "payment_channel": "EXB_5a2a52ea-61a4-4403-a58b-1fd114955b83",
        "bill_receiver": "CES"
      },
      "type": "ExternalBilling",
      "id": "EXB_5a2a52ea-61a4-4403-a58b-1fd114955b83"
    },
    "metadata": [
      {
        "value": "month",
        "name": "vin:BillingPlanUnit"
      },
      {
        "value": "0",
        "name": "vin:RetryNumber"
      },
      {
        "value": "1",
        "name": "vin:BillingPlanLength"
      },
      {
        "value": "1",
        "name": "vin:recurring"
      },
      {
        "value": "0",
        "name": "vin:BillingCycle"
      },
      {
        "value": "9.99",
        "name": "vin:FutureAmount"
      }
    ],
    "id": "CSP00000046",
    "items": [
      {
        "campaign_description": null,
        "tax_type": "Exclu",
        "sku": "MONTHLY",
        "subtotal": null,
        "service_period_ends": "2019-10-29T00:00:00-07:00",
        "campaign_id": null,
        "metadata": [],
        "item_type": "Purchase",
        "index_number": 1,
        "name": "Monthly Subscription",
        "quantity": 1,
        "tax": [],
        "service_period_starts": "2019-09-30T00:00:00-07:00",
        "tax_classification": null,
        "discount": null,
        "total": 0,
        "price": null
      },
      {
        "campaign_description": null,
        "tax_type": "Exclu",
        "sku": "PRODCODE-1",
        "subtotal": 9.99,
        "service_period_ends": "2019-10-29T00:00:00-07:00",
        "campaign_id": null,
        "metadata": [],
        "item_type": "Purchase",
        "index_number": 2,
        "name": "FishHook subscription",
        "quantity": 1,
        "tax": [],
        "service_period_starts": "2019-09-30T00:00:00-07:00",
        "tax_classification": null,
        "discount": null,
        "total": 9.99,
        "price": 9.99
      },
      {
        "campaign_description": null,
        "tax_type": "Exclu",
        "sku": "Total Tax",
        "subtotal": 0,
        "service_period_ends": "2019-10-29T00:00:00-07:00",
        "campaign_id": null,
        "metadata": [],
        "item_type": "Purchase",
        "index_number": 3,
        "name": "Total Tax",
        "quantity": 1,
        "tax": [],
        "service_period_starts": "2019-09-30T00:00:00-07:00",
        "tax_classification": "TaxExempt",
        "discount": 0,
        "total": 0,
        "price": 0
      }
    ]
  }
]
 

Charge Error File Format and Structure

Error files are in JSON format: CES_VNDC_charge_error_<datetime>.JSON. Partner Ecosystem Management generates a FIN file with each error JSON file in the following format: CES_VNDC_CHARGE_ERROR_<yyyymmdd>T<hhmmss>.JSON.FIN. Each FIN file includes a checksum. After an error file is generated, the Reseller has 24 hours to upload the error file via SFTP to the relevant sub-folder in the upload path: /upload/<subfolder>/<YYYYMMDD> (for example: /upload/charge_errors/20210422/). If the Reseller hasn’t returned an error in 24 hours, the transaction is treated as successful and committed. Note: We recommend uploading error files by 18:00 UTC to make sure the transactions are included in the next daily charge file (generated at 00:00 UTC). Charge Error File Fields

Field Name	Type	Required or Optional	Description
id	String	Required	The Reseller (Service Provider)-specific unique identifier for this item. If the error is at the file level, the value must be 999.
vid	String	Required	The Partner Ecosystem Management global unique identifier for this item. If the error is at the file level, the value must be 999.
trx_index	String	Required	The transaction item index that failed. If the failure is at the transaction level, the trx_index must be 999.
error_code	String	Required	The error code. The error code the Reseller returns will be mapped to either hard or soft errors in Partner Ecosystem Management. Soft failures will be retried a configurable number of times after which they are considered hard failures.Note: The Reseller has the ability to define the soft and hard error codes.
file_name	String	Optional	If the error is at the file level, this field can be set with the failed file name.
Charge Error File Example

[
   {
      "id":"CSP00000046",
      "vid":"3434a7404d041306708a4dfb05413e912c16209d",
      "TRX_index":"2",
      "Error Code":"BL76"
   }
]

Parent topic:Partner Ecosystem Management Features

Home

Introduction

For Merchants

For Resellers

Partner Ecosystem Management

Commerce Engine

Storefront Experience

APIs

Accessing and Processing Charge and Refund Files

Charge File Format and Structure

Charge Error File Format and Structure

​Accessing and Processing Charge and Refund Files

​Charge File Format and Structure

​Charge Error File Format and Structure

Accessing and Processing Charge and Refund Files

Charge File Format and Structure

Charge Error File Format and Structure