SubAccountGiveCredits
Schema used to transfer credits to and from a user's sub-accounts.
Please note that it is not possible to transfer any free credits gained on initially joining 2sms between sub-accounts.
For this reason all balances returned by this method (and methods 0510
and 0550) do not include any free credits.
The 'UserID' and 'Password' elements identify the account.
The 'ServiceName' element must be set to 'SubAccountGiveCredits'.
The 'SoftwareVersion' element is for internal 2SMS use only and should not be set.
The 'ServiceDetail' element contains a single 'SubAccountList' child element. This in turn contains one or more
'SubAccount' elements, each of which has the following children:
- A 'Username' element that details the sub-account with which to transfer credits.
- A 'CurrentBalance' element with the number of anytime credits to be transferred into the sub-account.
- An 'OffPeakBalance' element with the number of off-peak credits to be transferred into the sub-account.
The use of 'ServiceDetail' child elements outside the 'SubAccountList' element is deprecated.
The 'ServiceDetail' also has a 'method' attribute which can be set to 'giveCredits' (the default) or 'setBalance':
-
The 'giveCredits' option means that the number of credits specified will be transferred into the sub-accounts.
-
The 'setBalance' option means that the credit levels of the sub-accounts will be brought up to the specified level.
If they are already at or above this level they will remain unchanged.
The 'accountSegCode' attribute is for internal 2SMS use only and should not be set.
Please note the following:
-
Only whole numbers of credits can be transferred. Attempting to transfer a non integer amount results in an error.
-
If an account is configured for managed sub-accounts it is possible to transfer credits both to and from sub-accounts.
A positive number of credits causes transfer from the user's account to the sub-account.
A negative number of credits causes transfer from the sub-account to the user's account.
-
If an account is configured for commission based sub-accounts it is only possible to transfer credits to sub-accounts.
-
It is not possible to transfer credits between accounts in different 2sms markets (e.g. between an account registered in
the US and an account registered in the UK). Method code 0510 can provide information
on whether sub-accounts are in the same 2sms market.
-
Transfers which result in a negative balance in either the master account or a sub-account are not permitted.
In such cases the entire request will fail and no credits will be transferred between any accounts.
-
Credit transfers are performed in the order of the elements in 'SubAccountList'. This means that the order
of the transactions can affect whether the transfer is permitted: a request is rejected if the master account
balance would be temporarily reduced below zero. One way to avoid this is to list all transactions which
transfer credit to the master account before those which transfer credit from the master account.
This method returns a successful '00/OK' response if the balance transfers were completed.
The 'Result' element confirms that the requested transfers occurred.
The 'Detail' element contains an 'AccountBalance' and a 'SubAccountList' child element.
The 'AccountBalance' element contains the following child elements:
-
The 'CurrentBalance' element contains the updated transferable anytime balance of the master account.
Note that this total excludes any initial free credits that are not transferable to sub-accounts.
- The 'OffPeakBalance' element contains the new off-peak balance of the master account.
The 'SubAccountList' element contains one or more 'SubAccountBalance' elements, each of which contain
information on one of the sub-accounts with which credits were transferred. The information is held in the
following child elements:
- The 'Username' identifies a specific sub-account.
-
The 'CurrentBalance' element contains the updated transferable anytime balance of the specified sub-account.
Note that this total excludes any initial free credits that are not transferable to sub-accounts.
- The 'OffPeakBalance' element contains the new off-peak balance of the specified sub-account.
The 'SubAccountBalance' element is provided for support of legacy code and will only appear in the response when
using a deprecated request format.