allocate()

void allocate(string usn, AllocationRequests allocationRequests)

This method allocates transactions within an account. A single transaction can be allocated to multiple transactions with different amount values.

Parameters

usn: Format: string; Purpose: Specifies the USN of the account to allocate transactions.
allocationRequests: Format: AllocationRequests XML; Purpose: Defines an AllocationRequests XML document that specifies allocation requests.

Example: Request an allocation

This example shows a request to allocate an amount of $59.90 from transaction 21432521 to transaction 21432513.

An AllocationRequests XML document can have the from transaction allocated to multiple transactions, by including multiple <AllocateTo> elements. An AllocationRequests XML document contains the following fields:

<TransactionNumber>: Specifies the transaction number where amounts are allocated from.
<AutoAllocate>: Specifies to use auto-allocation instead of providing <AllocateTo> elements. If the transaction numbers where the amount are allocated from are specified, they will be automatically allocated to the most appropriate transaction number. If no transaction numbers are specified, auto-allocation for all debits and credits available for the account is processed.
<TransactionNumber>: Specifies the transaction number where the amount is allocated to.
<AllocateAmount>: Specifies the allocation amount.

<AllocationRequests xmlns="http://xml.inomial.com/smile/2.xsd">
  <AllocationRequest>
    <TransactionNumber>21432521</TransactionNumber>
    <AllocateTo>
      <TransactionNumber>21432513</TransactionNumber>
      <AllocateAmount>59.90</AllocateAmount>
    </AllocateTo>
  </AllocationRequest>
</AllocationRequests>

Example: Request an auto-allocation

This example shows a request to auto-allocate all unallocated transactions within an account.

<AllocationRequest xmlns="http://xml.inomial.com/smile/2.xsd">
  <AutoAllocate>true</AutoAllocate>
</AllocationRequest>

Example: Request to auto-allocate a transaction to available credits/debits

This examples shows a request to automatically allocate transaction 21432521 to available credits and debits.

<AllocationRequests xmlns="http://xml.inomial.com/smile/2.xsd">
  <AllocationRequest>
    <TransactionNumber>21432521</TransactionNumber>
    <AutoAllocate>true</AutoAllocate>
  </AllocationRequest>
</AllocationRequests>

Example: Request to allocate payments to multiple invoices

This example shows a request to allocate separate amounts from transaction 21432521 to invoices 21432513 ($20), 21432539 ($10), and 21432547 ($29.90).

Note: Credit transactions can allocated to debit transactions and debit transactions to credit transactions in a request. The <AllocateTo> transaction must be the opposite type of the allocate from transaction.

<AllocationRequests xmlns="http://xml.inomial.com/smile/2.xsd">
  <AllocationRequest>
    <TransactionNumber>21432521</TransactionNumber>
    <AllocateTo>
      <TransactionNumber>21432513</TransactionNumber>
      <AllocateAmount>20</AllocateAmount>
    </AllocateTo>
    <AllocateTo>
      <TransactionNumber>21432539</TransactionNumber>
      <AllocateAmount>10</AllocateAmount>
    </AllocateTo>
    <AllocateTo>
      <TransactionNumber>21432547</TransactionNumber>
      <AllocateAmount>29.90</AllocateAmount>
    </AllocateTo>
  </AllocationRequest>
</AllocationRequests>

Results

This method does not return any output.

Smile emits the TransactionAllocated message when the allocate task is complete.

Faults

NoSuchItemException

This fault is returned when:

the allocate from transaction number does not exist
the account does not exist
the allocate to transaction number does not exist

InvalidRequestException

This fault is returned when:

the allocate from transaction number is not provided
the allocate from transaction number does not belong to the account
the allocate to transaction number does not belong to the account
the allocate to transaction number has a pending payment
the allocate amount exceeds the unallocated amount of the allocate to transaction
the allocate amount exceeds the unallocated amount of the allocate from transaction
allocating a non positive amount
when attempting to allocate an invoice reversal to a non-invoice
attempting to allocate a receipt reversal to a non-receipt
attempting to allocate a surcharge reversal to a non-surcharge
attempting to allocate a bond reversal to a non-bond
partially reversing an invoice, receipt or surcharge

Java client syntax

java -cp build/smilewsv2-client.jar [options] com.inomial.smile.client.v2.examples.Allocate usn filename

usn: Purpose: Specifies the USN of the account to allocate transactions.
filename: Purpose: Defines the filename of the AllocationRequests XML document.

Note: For more information about the Java client and the options it accepts, see Java client syntax.