> ## 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.

# 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:

1. Partner Ecosystem Management generates the charge and refund files in the designated SFTP location.
2. The Reseller (Service Provider) accesses the charge and refund files (FIN and JSON files) via SFTP.
3. 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](r_Features)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.