BssAccountInformation¶

This type represents billing specific information about an account, either a Customer, Reseller, or Provider in the platform.

In this document:

Schema
Properties
Relationship
Custom Operations
Structures
Examples

Schema ¶

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "BssAccountInformation",
  "id": "http://parallels.com/pa/bss-account-info/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "relations": {
    "paAccount": {
      "type": "http://parallels.com/aps/types/pa/account/1.2"
    },
    "customerClass": {
      "type": "http://www.odin.com/billing/CustomerClass/1.0"
    },
    "ownCustomerClasses": {
      "type": "http://www.odin.com/billing/CustomerClass/1.0",
      "collection": true
    }
  },
  "properties": {
    "accountId": {
      "type": "integer",
      "required": true
    },
    "accountCurrencyCode": {
      "type": "string",
      "readonly": true
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "CANCELLED",
        "VERIFICATION_REQUIRED",
        "NOT_INITIALIZED",
        "CANCELLED_NOT_INITIALIZED",
        "CREDIT_HOLD",
        "ADMINISTRATIVE_HOLD",
        "CREDIT_ADMINISTRATIVE_HOLD",
        "TRANSFERRED_OUT",
        "ERASED"
      ],
      "enumTitles": [
        "Active",
        "Cancelled",
        "Verification required",
        "Not initialized",
        "Cancelled (not initialized)",
        "Credit Hold",
        "Administrative Hold",
        "Credit + Administrative Hold",
        "Transferred Out",
        "Erased"
      ]
    },
    "externalARManagement": {
      "type": "boolean",
      "default": "false"
    },
    "taxRegId": {
      "type": "string"
    },
    "taxRegIdStatus": {
      "type": "string",
      "title": "Tax Reg ID status",
      "enum": [
        "NOT_VERIFIED",
        "VERIFIED"
      ],
      "enumTitles": [
        "Not Verified",
        "Verified"
      ]
    },
    "taxZoneId": {
      "type": "string"
    },
    "taxStatus": {
      "type": "string",
      "required": true,
      "title": "Tax Status of client",
      "enum": [
        "PROVIDER",
        "PERSONAL",
        "COMPANY"
      ],
      "enumTitles": [
        "Provider",
        "Personal",
        "Company"
      ]
    },
    "salesId": {
      "type": "string"
    },
    "branchId": {
      "type": "string"
    },
    "attributes": {
      "type": "array",
      "items": {
        "type": "Attribute"
      }
    },
    "creditTerm": {
      "type": "BssCreditTerm"
    },
    "fullyRegistered": {
      "type": "boolean"
    },
    "birthday": {
      "type": "string",
      "format": "date"
    },
    "passport": {
      "type": "string"
    },
    "companyNameLatin": {
      "type": "string"
    },
    "systemId": {
      "type": "integer"
    },
    "localeId": {
      "type": "string",
      "required": true
    }
  },
  "operations": {
    "getAccountBalanceDetails": {
      "path": "/balance-details",
      "verb": "GET",
      "response": {
        "type": "BssAccountBalanceDetails"
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "setTopUpOptions": {
      "path": "/set-top-up-options",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "params": {
          "kind": "body",
          "type": "BssAutoPaymentDetails"
        }
      }
    },
    "putOnCreditHold": {
      "path": "/putOnCreditHold",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false,
        "referrer": false
      },
      "parameters": {
        "params": {
          "kind": "body",
          "type": "PutOnCreditHoldParams)"
        }
      }
    },
    "releaseFromCreditHold": {
      "path": "/releaseFromCreditHold",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "owner": false,
        "referrer": false
      },
      "parameters": {
        "params": {
          "kind": "body",
          "type": "ReleaseFromCreditHoldParams)"
        }
      }
    },
    "getTaxRegId": {
      "path": "/taxRegId",
      "verb": "GET",
      "response": {
        "type": "string"
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "public": false,
        "privilege": "http://www.parallels.com/pa/pa-core-services#sensitive_account_info-view"
      }
    }
  },
  "structures": {
    "Attribute": {
      "type": "object",
      "properties": {
        "attributeID": {
          "type": "string",
          "required": true
        },
        "value": {
          "type": "string"
        }
      }
    },
    "BssCreditTerm": {
      "type": "object",
      "properties": {
        "duePeriod": {
          "type": "integer"
        },
        "holdPeriod": {
          "type": "integer"
        },
        "daysToDelay": {
          "type": "integer"
        }
      }
    },
    "BssPaymentMethod": {
      "type": "object",
      "properties": {
        "internalId": {
          "type": "integer"
        },
        "title": {
          "type": "string"
        },
        "type": {
          "type": "integer"
        },
        "paymentSystem": {
          "type": "string"
        },
        "ownerAccountId": {
          "type": "integer"
        },
        "bankAccountStatus": {
          "type": "BankAccountStatus"
        },
        "ownerName": {
          "type": "string"
        },
        "status": {
          "type": "Status"
        },
        "suspended": {
          "type": "boolean"
        },
        "perCustomer": {
          "type": "boolean"
        },
        "consentRequired": {
          "type": "boolean"
        },
        "consentDeletionDate": {
          "type": "string"
        },
        "consentAgreementUrl": {
          "type": "string"
        }
      }
    },
    "BankAccountStatus": {
      "type": "object"
    },
    "Status": {
      "type": "object"
    },
    "BssAutoPaymentDetails": {
      "type": "object",
      "properties": {
        "topupThreshhold": {
          "type": "number"
        },
        "autoTopupAmount": {
          "type": "number"
        },
        "autoTopupPerOrder": {
          "type": "boolean"
        },
        "autoTopupEnabled": {
          "type": "boolean"
        },
        "payToolID": {
          "type": "integer"
        },
        "vPayToolType": {
          "type": "integer"
        },
        "status": {
          "type": "integer"
        }
      }
    },
    "BssAccountBalanceDetails": {
      "type": "object",
      "properties": {
        "accountId": {
          "type": "integer"
        },
        "availableBalance": {
          "type": "number"
        },
        "availableBalanceStr": {
          "type": "string"
        },
        "currentPeriod": {
          "type": "string"
        },
        "currentBalance": {
          "type": "number"
        },
        "currentBalanceStr": {
          "type": "string"
        },
        "notInvoicedPurchases": {
          "type": "number"
        },
        "notInvoicedPurchasesStr": {
          "type": "string"
        },
        "paymentsByProvider": {
          "type": "number"
        },
        "paymentsByProviderStr": {
          "type": "string"
        },
        "availableCreditLimit": {
          "type": "number"
        },
        "availableCreditLimitStr": {
          "type": "string"
        },
        "outstandingInvoicesAmountEARM": {
          "type": "number"
        },
        "outstandingInvoicesAmountEARMStr": {
          "type": "string"
        },
        "externalCreditLimitEARM": {
          "type": "number"
        },
        "externalCreditLimitEARMStr": {
          "type": "string"
        },
        "externalAvailableProvisioningBalanceEARM": {
          "type": "number"
        },
        "externalAvailableProvisioningBalanceEARMStr": {
          "type": "string"
        },
        "paymentMethod": {
          "type": "BssPaymentMethod"
        },
        "autoPaymentDetails": {
          "type": "BssAutoPaymentDetails"
        },
        "externalARManagement": {
          "type": "boolean"
        }
      }
    }
  }
}

Properties ¶

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
accountId	Integer	Required		Account ID in the platform
accountCurrencyCode	String	Not Required Read Only		Account currency
status	Enum	Not Required		Identifies an account status AccountStatus Account Status: `ACTIVE` - Active `CANCELLED` - Cancelled `VERIFICATION_REQUIRED` - Verification required `NOT_INITIALIZED` - Not initialized `CANCELLED_NOT_INITIALIZED` - Cancelled (not initialized) `CREDIT_HOLD` - Credit Hold `ADMINISTRATIVE_HOLD` - Administrative Hold `CREDIT_ADMINISTRATIVE_HOLD` - Credit+Administrative Hold `TRANSFERRED_OUT` - Transferred Out `ERASED` - Erased
externalARManagement	Boolean	Not Required	false	Indicates that account balance are managed by external system
taxRegId	String	Not Required		Stores the tax registration ID of the account. On Get request returns “***”.
taxRegIdStatus	Enum	Not Required		Indicates customer tax registration status ID Tax reg id status on bss account: not verified - 0, verified - 1
taxZoneId	String	Not Required		Indicates customer tax zone ID
taxStatus	Enum	Required		Indicates customer tax status Tax status on bss account: provider - 0, personal - 1, company - 2
salesId	String	Not Required		Indicates customer sales ID
branchId	String	Not Required		Indicates customer branch ID
attributes	Array of Attribute	Not Required		Indicates customer attributes
creditTerm	BssCreditTerm	Not Required		Indicates customer credit terms
fullyRegistered	Boolean	Not Required		Indicates that customer is fully registered
birthday	String	Not Required		Indicates customer birthday
passport	String	Not Required		Indicates customer passport
companyNameLatin	String	Not Required		Indcates customer company name
systemId	Integer	Not Required		Indicates customer system ID
localeId	String	Required		Indicates customer locale

Relationship ¶

NAME	TYPE	REQUIRED	DESCRIPTION
paAccount	PAAccount	No	Relation to PAAccount
customerClass	CustomerClass	No	Account customer class
ownCustomerClasses	Collection of CustomerClass	No	Collection of customer classes created by the account. The account can change customer class of own accounts (resellers or customers) only to customer class from this collection.

Custom Operations ¶

OPERATION	VERB	PATH	RETURNS	Description
getAccountBalanceDetails	GET	/balance-details	Class with information about balances and top-up	Get account balance information for reseller: balances and default top-up payment method from BM. Uses BM.GetAvailableBalance method
setTopUpOptions	POST	/set-top-up-options		Set default top-up payment method for reseller
putOnCreditHold	POST	/putOnCreditHold		Put the account on Credit Hold
releaseFromCreditHold	POST	/releaseFromCreditHold		Release the account from Credit Hold
getTaxRegId	GET	/taxRegId	Account TaxRegId	Custom operation to get account TaxRegId

getAccountBalanceDetails¶

HTTP Request

GET /aps/2/resources/{aps-id}/balance-details

Description

Get account balance information for reseller: balances and default top-up payment method from BM. Uses BM.GetAvailableBalance method

Returns

Class with information about balances and top-up

setTopUpOptions¶

HTTP Request

POST /aps/2/resources/{aps-id}/set-top-up-options

Description

Set default top-up payment method for reseller

Parameters

PARAMETER	TYPE	DESCRIPTION
params	BssAutoPaymentDetails

Returns

putOnCreditHold¶

HTTP Request

POST /aps/2/resources/{aps-id}/putOnCreditHold

Description

Put the account on Credit Hold

Parameters

PARAMETER	TYPE	DESCRIPTION
params	PutOnCreditHoldParams)	Parameter PutOnCreditHoldParams

Returns

releaseFromCreditHold¶

HTTP Request

POST /aps/2/resources/{aps-id}/releaseFromCreditHold

Description

Release the account from Credit Hold

Parameters

PARAMETER	TYPE	DESCRIPTION
params	ReleaseFromCreditHoldParams)	Parameter ReleaseFromCreditHoldParams

Returns

getTaxRegId¶

HTTP Request

GET /aps/2/resources/{aps-id}/taxRegId

Description

Custom operation to get account TaxRegId

Returns

Account TaxRegId

Structures ¶

Attribute¶

The structure that defines the custom attribute.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
attributeID	String	Required
value	String	Not Required		The attribute value.

BssCreditTerm¶

NAME	TYPE	ATTRIBUTES
duePeriod	Integer	Not Required
holdPeriod	Integer	Not Required
daysToDelay	Integer	Not Required

BssPaymentMethod¶

NAME	TYPE	ATTRIBUTES
internalId	Integer	Not Required
title	String	Not Required
type	Integer	Not Required
paymentSystem	String	Not Required
ownerAccountId	Integer	Not Required
bankAccountStatus	BankAccountStatus	Not Required
ownerName	String	Not Required
status	Status	Not Required
suspended	Boolean	Not Required
perCustomer	Boolean	Not Required
consentRequired	Boolean	Not Required
consentDeletionDate	String	Not Required
consentAgreementUrl	String	Not Required

BankAccountStatus¶

Status¶

BssAutoPaymentDetails¶

NAME	TYPE	ATTRIBUTES
topupThreshhold	Number	Not Required
autoTopupAmount	Number	Not Required
autoTopupPerOrder	Boolean	Not Required
autoTopupEnabled	Boolean	Not Required
payToolID	Integer	Not Required
vPayToolType	Integer	Not Required
status	Integer	Not Required

BssAccountBalanceDetails¶

NAME	TYPE	ATTRIBUTES
accountId	Integer	Not Required
availableBalance	Number	Not Required
availableBalanceStr	String	Not Required
currentPeriod	String	Not Required
currentBalance	Number	Not Required
currentBalanceStr	String	Not Required
notInvoicedPurchases	Number	Not Required
notInvoicedPurchasesStr	String	Not Required
paymentsByProvider	Number	Not Required
paymentsByProviderStr	String	Not Required
availableCreditLimit	Number	Not Required
availableCreditLimitStr	String	Not Required
outstandingInvoicesAmountEARM	Number	Not Required
outstandingInvoicesAmountEARMStr	String	Not Required
externalCreditLimitEARM	Number	Not Required
externalCreditLimitEARMStr	String	Not Required
externalAvailableProvisioningBalanceEARM	Number	Not Required
externalAvailableProvisioningBalanceEARMStr	String	Not Required
paymentMethod	BssPaymentMethod	Not Required
autoPaymentDetails	BssAutoPaymentDetails	Not Required
externalARManagement	Boolean	Not Required

APS allows for getting the JSON representation of a required account and the linked BSS resource in one request or in separate requests, in either case using a Resource Query Language (RQL) filter. For example, if the account ID of a customer in the platform is 1000002, a request to get both APS resources, PAAccount and BssAccountInformation, will be:

GET /aps/2/collections/accounts?eq(id,1000002),select(bssAccountInfo)

If the external system needs the BssAccountInformation resources only, use the bss-accounts alias instead of accounts in the URL, and the other functions (select and eq) must be changed accordingly.

The response will look similar to the following (some data is missed out for brevity):

HTTP/1.1 200 OK

[{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/account/1.2",
      "id": "f654862a-4903-4151-b2b4-ed65c055d120",
      ...
   },
   "companyName": "John Smith",
   "id": 1000002,
   "locked": false,
   "personal": true,
   "type": "CLIENT",
   "addressPostal": { /* ... */ },
   "adminContact": { /* ... */ },
   "billingContact": { /* ... */ },
   "techContact": { /* ... */ },
   "bssAccountInfo": {
      "aps": {
         "type": "http://parallels.com/pa/bss-account-info/1.0",
         "id": "7cad381f-0daf-4557-a53f-b5ea64566622",
         "status": "aps:ready",
         /* ... */
      },
      "branchId": "",
      "accountCurrencyCode": "USD",
      "taxStatus": "PERSONAL",
      "accountId": 1000002,
      "taxZoneId": "Provider-Country",
      "salesId": "",
      "taxRegIdStatus": "NOT_VERIFIED",
      "creditTerm": {
         "duePeriod": 10,
         "holdPeriod": 30
      },
      "externalARManagement": false,
      "taxRegId": "*****",
      "fullyRegistered": true,
      "localeId": "en",
      "status": "ACTIVE"
   }
}]

Warning

The taxRegId property is invisible since this is a part of sensitive personal data that cannot be disclosed in accordance with the personal data protection rules. Neither can it be used to search for a BssAccountInformation resource.

Create Account with BSS Info¶

POST /aps/2/resources

[
   { "aps":{
         "type":"http://parallels.com/pa/bss-account-info/1.0",
         "id":"ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
      },
      "taxStatus": "COMPANY",
      "localeId": "en_US",
      "attributes": [
         {
            "attributeID": "external_id",
            "value": "1111-2222-3333"
         }
      ]
   },
   { "aps":{
         "type":"http://parallels.com/aps/types/pa/account/1.2"
      },
      "type":"CLIENT",
      "personal":false,
      "companyName":"1st APS inc",
      "bssAccountInfo":{
         "aps": {
            "id":"ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
         }
      },
      "parent":{
         "aps":{
            "id":"4935d68d-4d26-4930-acf7-3871557305a9"
         }
      },
      "addressPostal":{
         "countryName":"us",
         "locality":"APS",
         "postalCode":"12345",
         "region":"VA",
         "streetAddress":"11, APS"
      },
      "adminContact":{
         "email":"isv1@aps.test",
         "givenName":"Mike",
         "familyName":"Wilson",
         "telVoice":"1#888#1234567"
      },
      "billingContact":{
         "email":"isv1@aps.test",
         "givenName":"Mike",
         "familyName":"Wilson",
         "telVoice":"1#888#1234567"
      },
      "techContact":{
         "email":"isv1@aps.test",
         "givenName":"Mike",
         "familyName":"Wilson",
         "telVoice":"1#888#1234567"
      }
   }
]

In response, the APS controller must return the “200 OK” code along with the JSON representation of the created APS resources. The provider control panel must show the new customer in both parts, OSS and BSS:

Update BSS Info¶

For example, to update the company name, send:

PUT /aps/2/resources/6344049b-8763-417d-837b-490ba0896f41

{
  "aps": {
    "type": "http://parallels.com/aps/types/pa/account/1.2",
    "id": "6344049b-8763-417d-837b-490ba0896f41"
  },
  "companyName": "John Smith and brothers"
}

In response, the APS controller will send the full JSON representation of the updated account.

Custom Operations¶

Put the account on credit hold using the ALL_SUBSCRIPTIONS policy:

POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/putOnCreditHold

{
   "policy": "ALL_SUBSCRIPTIONS",
   "reason": "ACCOUNT_OVERDUE",
   "comment": "Account put on hold due to unpaid invoices, ID #1000123 and #1000125."
}

Check the current status of the account:

GET /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097

The response must show the CREDIT_HOLD status:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://parallels.com/pa/bss-account-info/1.0",
      "id": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58097",
      "status": "aps:ready",
      /* ... */
   },
   "accountCurrencyCode": "USD",
   "accountId": 1000001,
   "status": "CREDIT_HOLD"
}

Release the account from credit hold temporarily:

POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/releaseFromCreditHold

{
   "policy": "TEMPORARY",
   "activeUntil": "2017-09-07T13:44:01Z",
   "comment": "Account temporarily released from hold per approval ID #23231."
}

← BSSSubscription

CustomerClass →

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

BssAccountInformation¶

Schema ¶

Properties ¶

Relationship ¶

Custom Operations ¶

getAccountBalanceDetails¶

setTopUpOptions¶

putOnCreditHold¶

releaseFromCreditHold¶

getTaxRegId¶

Structures ¶

Attribute¶

BssCreditTerm¶

BssPaymentMethod¶

BankAccountStatus¶

Status¶

BssAutoPaymentDetails¶

BssAccountBalanceDetails¶

Examples ¶

Get Account and BSS Info¶

Create Account with BSS Info¶

Update BSS Info¶

Custom Operations¶

CloudBlue Commerce API (DRAFT)

Table Of Contents

Previous topic

Next topic

BssAccountInformation¶

Schema¶

Properties¶

Relationship¶

Custom Operations¶

getAccountBalanceDetails¶

setTopUpOptions¶

putOnCreditHold¶

releaseFromCreditHold¶

getTaxRegId¶

Structures¶

Attribute¶

BssCreditTerm¶

BssPaymentMethod¶

BankAccountStatus¶

Status¶

BssAutoPaymentDetails¶

BssAccountBalanceDetails¶

Examples¶

Get Account and BSS Info¶

Create Account with BSS Info¶

Update BSS Info¶

Custom Operations¶

Schema ¶

Properties ¶

Relationship ¶

Custom Operations ¶

Structures ¶

Examples ¶