In this topic:

Billing Accounts

This example shows you how to use the Gotransverse Billing API to create a billing account, update a billing account, and add a recurring payment method to a billing account.

Example Updated: February 2018

Terminology

Billing Account: An entity in Gotransverse that allows you to manage personal and billing information about your customers. Actions such as orders, adjustments, and payments are performed through the billing account.

Billing Account Category: A business entity that a billing account is assigned to during the billing account creation process. Billing account categories are a way of organizing billing accounts into groups. You can categorize in a number of ways, including by geographic location or by type of billing account. You can use account categories to set payment terms or to restrict access to billing accounts. Account categories are required for all billing accounts in Gotransverse.

Bill Cycle: The period of time during which service and usage charges are calculated and allowances are measured to create invoices. A bill cycle is assigned during the billing account creation process. Bill cycles are recurring and typically set to repeat on a defined basis. For example, you might send invoices to customers on the first day of the month for services provided the previous month. The length of a bill cycle can vary and can be daily, weekly, semi-monthly, every-other week, monthly, quarterly, or annual.

Creating a Billing Account

In order to create a billing account, you will need to first query for the following values, which will later be passed into a POST request.

  • bill-cycles: Determines available bill cycles. You must assign a bill cycle to the billing account during the creation process.
  • billing-account-categories: Determines available billing account categories. You must assign a billing account category to the billing account during the creation process.

Query for Bill Cycles

In this example request, a query for bill cycles returns one daily bill cycle. A typical environment may have more than one available bill cycle.

Request
GET https://example-tract-api.com/billing/2/bill-cycles

Response

[
  {
    "bill_cycle_type": "daily", 
    "status": "ACTIVE", 
    "id": "80",         
    "name": "Daily",
    "start_date": "2018-11-02T00:00:00-05:00",
    "end_date": "2017-11-03T00:00:00-05:00",
    "auto_bill": false,
    "currency_code": "USD"
  }
]

Query for Billing Account Categories

In this example request, a query for billing account categories returns one account category. A typical environment may have more than one available billing account category.

Request
GET https://example-tract-api.com/billing/2/billing-account-categories

Response

[
  {
    "description": "Inc. Customers", 
    "status": "ACTIVE", 
    "id": "52",         
    "name": "Inc.",
    "payment_term": {
      "name": "Net 30",
      "id": "25"
    },
    "auto_pay_offset": 0
  }
]

Create Billing Account

Depending on the information captured when the billing account is created in an external system, you can send in more than the payload below. You can send payment method and sales order information at the same time to minimize the amount of API requests needed to establish the account in Gotransverse.

For the example request below, we are using values for billing_account_category_id, bill_cycle_id, and bill_cycle_type found in the previous two GET requests. Required JSON objects for the request include responsible_party, bill_cycle, billing_account_category, and bill_type. Bill type specifies the type of invoice that will be generated for the billing account.

Request
POST https://example-tract-api.com/billing/2/billing-accounts

Body

  {
    "external_account_num": "902322323",
    "start_date": "2017-02-01T06:00:00.000Z",
    "responsible_party": {
      "party_type": "organization",
      "organization_name": "canic",
      "addresses": [{
        "address_type": "email",
        "purpose": "PRIMARY",
        "email": "jane.example@gotransverse.com"
      },
      {
        "address_type": "postal",
        "purpose": "BILLING",
        "country": "USA",
        "city": "AUSTIN",
        "region_or_state": "TX",
        "postal_code": "78701",
        "line1": "620 CONGRESS AVE SUITE 200"
      }]
    },
    "bill_cycle": {
      "id": "80",
      "bill_cycle_type": "daily"
    },
    "bill_type": "EMAIL",
    "billing_account_category": {
      "id": "52"
    }
  }

The response contains all information pertaining to the billing account, including values created by the default configuration of attributes such as payment term.

Response

{
  "id": "1387",
  "account_num": "2006",
  "external_account_num": "902322324",
  "bill_type": "EMAIL",
  "bill_cycle": {
    "bill_cycle_type": "daily",
    "status": "ACTIVE",
    "id": "80",
    "name": "Daily",
    "start_date": "2017-11-03T00:00:00-05:00",
    "end_date": "2017-11-04T00:00:00-05:00",
    "auto_bill": false,
    "currency_code": "USD"
  },
  "responsible_party": {
    "party_type": "organization",
    "id": "1460",
    "addresses": [
      {
        "address_type": "email",
        "purpose": "PRIMARY",
        "email": "jane.example@gotransverse.com",
        "id": "1544"
      },
      {
        "address_type": "postal",
        "purpose": "BILLING",
        "country": "USA",
        "city": "AUSTIN",
        "line1": "620 CONGRESS AVE SUITE 200",
        "id": "1545",
        "region_or_state": "TX",
        "postal_code": "78701"
      }
    ],
    "organization_name": "goTransverse",
    "tax_id_validated": false
  },
  "recurring_payments": [],
  "billing_account_category": {
    "description": " Inc. Customers",
    "status": "ACTIVE",
    "id": "52",
    "name": " Inc.",
    "payment_term": {
      "name": "Net 30",
      "id": "25"
    },
    "auto_pay_offset": 0
  },
  "auto_payment_authorized": false,
  "status": "ACTIVE",
  "pending_charges_total": 0,
  "balance": 0,
  "start_date": "2018-06-01T01:00:00-05:00",
  "custom_field_values": [],
  "contacts": [],
  "tax_exempt": false,
  "currency_code": "USD",
  "next_invoice_date": "2018-01-01T00:00:00-06:00"
  }

Updating a Billing Account

In order to update billing account information, we must first query for the responsible party ID and party type associated with the billing account in Gotransverse. There are multiple query parameters that we can use to find billing accounts in Gotransverse. In this example, we are using an external account number of 902322324, which can map to a customer number in an external system. After finding the responsible party ID and party type, we can update the name of the organization or person and the addresses associated with the billing account.

Query for Billing Account Using External Account Number

Request
GET https://example-tract-api.com/billing/2/billing-accounts?external_account_num=902322324

Response

[
    {
        "id": "1382",
        "account_num": "2001",
        "external_account_num": "902322324",
        "bill_type": "EMAIL",
        "bill_cycle": {
            "bill_cycle_type": "daily",
            "status": "ACTIVE",
            "id": "80",
            "name": "Daily",
            "start_date": "2017-11-02T00:00:00-05:00",
            "end_date": "2017-11-03T00:00:00-05:00",
            "auto_bill": false,
            "currency_code": "USD"
        },
        "responsible_party": {
            "party_type": "organization",
            "id": "1455",
            "addresses": [
                {
                    "address_type": "email",
                    "purpose": "PRIMARY",
                    "email": "jane.example@gotransverse.com",
                    "id": "1529"
                },
                {
                    "address_type": "postal",
                    "purpose": "BILLING",
                    "country": "USA",
                    "city": "AUSTIN",
                    "line1": "620 CONGRESS AVE SUITE 200",
                    "id": "1530",
                    "region_or_state": "TX",
                    "postal_code": "78701"
                }
            ],
            "organization_name": "Visa",
            "tax_id_validated": false
        },
        "recurring_payments": [
            {
                "id": "2",
                "payment_method": {
                    "payment_method_type": "credit-card",
                    "nickname": "Credit Card Ending 1111",
                    "id": "6",
                    "custom_field_values": [],
                    "card_type": "VISA",
                    "first_name": "Recurring",
                    "last_name": "Payment",
                    "identifier_number": "Last 4: 1111",
                    "expiration_date": "12/2020"
                },
                "billing_account": {
                    "id": "1382",
                    "account_num": "2001",
                    "external_account_num": "902322324"
                },
                "valid_from": "2017-11-02T09:56:00-05:00",
                "auto_payment": true
            }
        ],
        "billing_account_category": {
            "description": " Inc. Customers",
            "status": "ACTIVE",
            "id": "52",
            "name": " Inc.",
            "payment_term": {
                "name": "Net 30",
                "id": "25"
            },
            "auto_pay_offset": 0
        },
        "auto_payment_authorized": true,
        "status": "ACTIVE",
        "pending_charges_total": 1250,
        "balance": -550,
        "start_date": "2017-04-01T01:00:00-05:00",
        "custom_field_values": [],
        "contacts": [],
        "tax_exempt": false,
        "currency_code": "USD",
        "next_invoice_date": "2017-01-01T00:00:00-06:00",
        "auto_pay_offset": 0
    }
]

Update Billing Account Name

For Party Type = Organization

Using a responsible party ID of 1455 obtained in the previous request, we use the organizations endpoint to update the organization name to River Aviation.

Request
PUT https://example-tract-api.com/billing/2/organizations/1455

Body

{
  "party_type": "organization",
  "organization_name": "River Aviation"
}

Response

{
    "party_type": "organization",
    "id": "1455",
    "addresses": [
        {
            "address_type": "email",
            "purpose": "PRIMARY",
            "email": "jane.example@gotransverse.com",
            "id": "1529"
        },
        {
            "address_type": "postal",
            "purpose": "BILLING",
            "country": "USA",
            "city": "AUSTIN",
            "line1": "620 CONGRESS AVE SUITE 200",
            "id": "1530",
            "region_or_state": "TX",
            "postal_code": "78701"
        }
    ],
    "organization_name": " River Aviation",
    "tax_id_validated": false
}

For Party Type = Person

Using a responsible party ID of 2466 obtained in a GET request for the billing account, we use the people endpoint to update the person who is the responsible party on the billing account.

Request
PUT https://example-tract-api.com/billing/2/people/2466

Body

{
    "party_type": "person",
    "first_name": "Jane",
    "last_name": "Example"
}

Response

{
    "party_type": "person",
    "id": "2386998",
    "addresses": [
        {
            "address_type": "email",
            "id": "6257789",
            "purpose": "PRIMARY",
            "email": "jexample@gotransverse.com"
        },
        {
            "address_type": "postal",
            "id": "6257788",
            "purpose": "BILLING",
            "country": "USA",
            "city": "Austin",
            "line1": "620 Congress Avenue",
            "region_or_state": "TX",
            "postal_code": "78701"
        }
    ],
    "first_name": "Jane",
    "last_name": "Example"
}

Update Billing Account Address

For Party Type = Organziation

To update address information for a responsible party that's an organization, we use the endpoint below. Addresses are not replaced in Gotransverse. Instead, they are expired with a new one created. We therefore use a POST method instead of PUT method. The following example uses an organization ID of 1445. You can obtain the organization ID in a query for the billing account.

Request
POST https://example-tract-api.com/billing/2/organizations/1455/addresses

Body

{
  "address_type": "postal",
  "purpose": "BILLING",
  "country": "USA",
  "city": "Austin",
  "region_or_state": "TX",
  "postal_code": "78705",
  "line1": "3401 Red River St",
  "line2": "Suite 456"
}

Response

{
    "address_type": "postal",
    "purpose": "BILLING",
    "country": "USA",
    "city": "Austin",
    "line1": "3401 Red River St",
    "line2": "Suite 456",
    "id": "1532",
    "region_or_state": "TX",
    "postal_code": "78705"
}

For Party Type = Person

To update address information for a responsible party that's a person, we use the endpoint below. Addresses are not replaced in Gotransverse. Instead, they are expired with a new one created. We therefore use a POST method instead of PUT method. The following example uses person ID of 2386. You can obtain the person ID through a query for the billing account.

Request
POST https://example-tract-api.com/billing/2/people/2386/addresses

Body

{
    "address_type": "postal",
    "purpose": "BILLING",
    "country": "USA",
    "city": "Austin",
    "line1": "Evening Shadow Drive",
    "region_or_state": "TX",
    "postal_code": "78750"
}

Response

{
    "address_type": "postal",
    "id": "6257788",
    "purpose": "BILLING",
    "country": "USA",
    "city": "Austin",
    "line1": "Evening Shadow Drive",
    "region_or_state": "TX",
    "postal_code": "78750"
}

Update Billing Account Primary Email Address

For Party Type = Organization

We use the organizations endpoint to update the primary email address on a billing account. This example uses an organization ID of 1455. You can obtain the organization ID through a query for the billing account.

Request
POST https://example-tract-api.com/billing/2/organizations/1455/addresses

Body

{
  "address_type": "email",
  "purpose": "PRIMARY",
  "email": "luka.example@gotransverse.com"
}

Response

{
    "address_type": "email",
    "purpose": "PRIMARY",
    "email": "luka.example@gotransverse.com",
    "id": "1182"
}

For Party Type = Person

We use the people endpoint to update the primary email address on a billing account. This example uses an person ID of 2386. You can obtain the person ID through a query for the billing account.

Request
POST https://example-tract-api.com/billing/2/people/2386/addresses

Body

{
   "address_type": "email",
   "purpose": "PRIMARY",
   "email": "bsmith@gotransverse.com"
}

Response

{
   "address_type": "email",
   "id": "6257789",
   "purpose": "PRIMARY",
   "email": "b.smith@gotransverse.com",
}

Adding a Recurring Payment Method

Credit card payments are often handled by a multi-step authentication process using Gotransverse's Payments.js hosted payment javascript. For customers who maintain their own PCI compliance, Gotransverse can also accept credit card information through the API. The following example shows how to send credit card information directly to Gotransverse.

Add Payment Method to Billing Account

This POST request creates a recurring credit card payment for the billing account with an ID 1382. The credit card is added as a recurring payment method on the customer's billing account.

Request
POST https://example-tract-api.com/billing/2/billing-accounts/1382/recurring-payments

Body

{
    "payment_method": {
        "card_type": "VISA", 
        "custom_field_values": [], 
        "expiration_date": "12/2020", 
        "first_name": "Recurring", 
        "identifier_number": "4111111111111111", 
        "last_name": "Payment", 
        "payment_method_type": "credit-card", 
        "verification_number": "123"
    }
}

Response

{
    "id": "2",
    "payment_method": {
        "payment_method_type": "credit-card",
        "nickname": "Credit Card Ending 1111",
        "id": "6",
        "custom_field_values": [],
        "card_type": "VISA",
        "first_name": "Jane",
        "last_name": "Example",
        "identifier_number": "Last 4: 1111",
        "verification_number": "123",
        "expiration_date": "12/2020"
    },
    "billing_account": {
        "id": "1382",
        "account_num": "2001",
        "external_account_num": "902322324"
    },
    "valid_from": "2017-11-02T09:56:00-05:00",
    "auto_payment": true
}

Authorize Auto-Payment on Billing Account

To authorize auto-payment on a billing account, you must set a flag on the account itself. In this example, we configure billing account 1382 to use the payment method that was added by setting auto_payment_authorized to true.

Request
PUT https://example-tract-api.com/billing/2/billing-accounts/1382

Body

{
  "auto_payment_authorized": true
}

Response

{
    "id": "1382",
    "account_num": "2001",
    "external_account_num": "902322324",
    "bill_type": "EMAIL",
    "bill_cycle": {
        "bill_cycle_type": "daily",
        "status": "ACTIVE",
        "id": "80",
        "name": "Daily",
        "start_date": "2017-11-02T00:00:00-05:00",
        "end_date": "2017-11-03T00:00:00-05:00",
        "auto_bill": false,
        "currency_code": "USD"
    },
    "responsible_party": {
        "party_type": "organization",
        "id": "1455",
        "addresses": [
            {
                "address_type": "email",
                "purpose": "PRIMARY",
                "email": "luka.example@gotransverse.com",
                "id": "1529"
            },
            {
                "address_type": "postal",
                "purpose": "BILLING",
                "country": "USA",
                "city": "AUSTIN",
                "line1": "620 CONGRESS AVE SUITE 200",
                "id": "1530",
                "region_or_state": "TX",
                "postal_code": "78701"
            }
        ],
        "organization_name": "Visa",
        "tax_id_validated": false
    },
    "recurring_payments": [
        {
            "id": "2",
            "payment_method": {
                "payment_method_type": "credit-card",
                "nickname": "Credit Card Ending 1111",
                "id": "6",
                "custom_field_values": [],
                "card_type": "VISA",
                "first_name": "Recurring",
                "last_name": "Payment",
                "identifier_number": "Last 4: 1111",
                "expiration_date": "12/2020"
            },
            "billing_account": {
                "id": "1382",
                "account_num": "2001",
                "external_account_num": "902322324"
            },
            "valid_from": "2017-11-02T09:56:00-05:00",
            "auto_payment": true
        }
    ],
    "billing_account_category": {
        "description": " Inc. Customers",
        "status": "ACTIVE",
        "id": "52",
        "name": " Inc.",
        "payment_term": {
            "name": "Net 30",
            "id": "25"
        },
        "auto_pay_offset": 0
    },
    "auto_payment_authorized": true,
    "status": "ACTIVE",
    "pending_charges_total": 1250,
    "balance": 0,
    "start_date": "2017-04-01T01:00:00-05:00",
    "custom_field_values": [],
    "contacts": [],
    "tax_exempt": false,
    "currency_code": "USD",
    "next_invoice_date": "2017-01-01T00:00:00-06:00",
    "auto_pay_offset": 0
}

More Information about Billing Accounts

To learn more about billing accounts and billing account status, refer to the User Guide Accounts topic.

To see API reference information for billing accounts, refer to the BillingAccount section of the Billing API reference.

Top