This type represents billing specific information about an account, either a Customer, Reseller, or Provider in the platform.
In this document:
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
},
"operatingUnit": {
"type": "boolean",
"readonly": true
}
},
"operations": {
"getAccountBalanceDetails": {
"path": "/balance-details",
"verb": "GET",
"response": {
"type": "BssAccountBalanceDetails"
},
"errorResponse": {
"type": "object"
}
},
"getAvailableFunds": {
"path": "/available-funds",
"verb": "GET",
"response": {
"type": "BssAvailableFunds"
},
"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"
}
},
"initializeReseller": {
"path": "/initializeReseller",
"verb": "POST",
"errorResponse": {
"type": "object"
},
"parameters": {
"resellerParams": {
"kind": "body",
"type": "ResellerParams"
}
}
}
},
"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"
}
}
},
"BssAvailableFunds": {
"type": "object",
"properties": {
"availableFunds": {
"type": "number"
},
"availableFundsStr": {
"type": "string"
}
}
}
}
}
The APS type is used to manage a collection of APS resources. To get a list of resources from that collection, use the following API call:
GET /aps/2/collections/bss-accounts?<RQL-filter>
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 - ActiveCANCELLED - CancelledVERIFICATION_REQUIRED - Verification requiredNOT_INITIALIZED - Not initializedCANCELLED_NOT_INITIALIZED - Cancelled (not initialized)CREDIT_HOLD - Credit HoldADMINISTRATIVE_HOLD - Administrative HoldCREDIT_ADMINISTRATIVE_HOLD - Credit+Administrative HoldTRANSFERRED_OUT - Transferred OutERASED - 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 |
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 |
|
operatingUnit |
Boolean |
Not Required Read Only |
|
NAME |
TYPE |
REQUIRED |
DESCRIPTION |
---|---|---|---|
paAccount |
No |
Relation to PAAccount |
|
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. |
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
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 |
|
GET |
/available-funds |
Class with information about available funds |
Get account available funds amount |
|
POST |
/set-top-up-options |
Set default top-up payment method for reseller |
||
POST |
/putOnCreditHold |
Put the account on Credit Hold |
||
POST |
/releaseFromCreditHold |
Release the account from Credit Hold |
||
GET |
/taxRegId |
Account TaxRegId |
Custom operation to get account TaxRegId |
|
POST |
/initializeReseller |
Initialize a reseller |
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
HTTP Request
GET /aps/2/resources/{aps-id}/available-funds
Description
Get account available funds amount
Returns
Class with information about available funds
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 |
Returns
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
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
HTTP Request
GET /aps/2/resources/{aps-id}/taxRegId
Description
Custom operation to get account TaxRegId
Returns
Account TaxRegId
HTTP Request
POST /aps/2/resources/{aps-id}/initializeReseller
Description
Initialize a reseller
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
resellerParams |
ResellerParams |
ResellerParams |
Returns
The structure that defines the custom attribute.
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
attributeID |
String |
Required |
||
value |
String |
Not Required |
The attribute value. |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
duePeriod |
Integer |
Not Required |
||
holdPeriod |
Integer |
Not Required |
||
daysToDelay |
Integer |
Not Required |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
internalId |
Integer |
Not Required |
||
title |
String |
Not Required |
||
type |
Integer |
Not Required |
||
paymentSystem |
String |
Not Required |
||
ownerAccountId |
Integer |
Not Required |
||
bankAccountStatus |
Not Required |
|||
ownerName |
String |
Not Required |
||
status |
Not Required |
|||
suspended |
Boolean |
Not Required |
||
perCustomer |
Boolean |
Not Required |
||
consentRequired |
Boolean |
Not Required |
||
consentDeletionDate |
String |
Not Required |
||
consentAgreementUrl |
String |
Not Required |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
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 |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
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 |
Not Required |
|||
autoPaymentDetails |
Not Required |
|||
externalARManagement |
Boolean |
Not Required |
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
availableFunds |
Number |
Not Required |
||
availableFundsStr |
String |
Not Required |
In this section:
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.
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:
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.
Get the account’s funds available for payment:
GET /aps/2/resources/77afbaa8-2e1c-4227-8a9e-70498bf0f5d8/available-funds
The response displays whether there is a certain sum on payment and credit memo documents that can be used for payment, for example:
HTTP/1.1 200 OK
{
"availableFunds": 13.06,
"availableFundsStr": "$13.06"
}
The availableFunds
field can be greater or equal zero. If it is greater than zero, you can use the available funds
for payment in a sales order.
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."
}
Initialize a reseller by setting a currency code for it:
POST /aps/2/resources/3719e346-fe3d-4a69-b146-7b7362ae5e6e/initializeReseller
{ "currency": "USD" }