processPayment()

PaymentResponse processPayment(string usn, PaymentRequest paymentRequest, AllocationRequest allocationRequest)

This method processes a payment, for example, contacting bank with details, and queues the debits to be allocated to the payment, pending the payment's success. No credit will be created if the payment is rejected.

Parameters

usn

Format: string

Purpose: Specifies the USN of the account that the payment receipt is allocated to.

paymentRequest

Format: PaymentRequest XML

Purpose: Defines a PaymentRequest XML document that specifies the details of the payment.

Note: The payment amount is inclusive of surcharges. The API caller has to be aware of the surcharges, and provide the expected surcharge amount in IncludesSurchargeAmount. If surcharges are not present, or incorrect, an InvalidRequestException fault is returned.

allocationRequest

Format: AllocationRequest XML

Purpose: Defines an AllocationRequest XML document that specifies the details of where to allocate portions of the payment if it processes successfully.

Allocations may only be made to debits on the account provided, up to a total amount of payment, minus surcharge. May be null.

You can also use auto-allocation instead of providing transaction number(s). Auto-allocate functionality is only allowed for manual payments. <AutoAllocate> set to true automatically allocates a payment beginning with the oldest unpaid invoice on the account. <AutoAllocate> set to false will assign the payment amount to the account, but not allocate it to a specific invoice.

If <AllocateTo> elements are provided as well as <AutoAllocate> set to true then auto-allocation will occur and <AllocateTo> is ignored.

Example: Request a payment

This example shows a PaymentRequest document containing details for a Payway payment.

Note: The usn, paymentRequest and allocationRequest parameters are all required to call processPayment.

<PaymentRequest>
  <PaymentDetails>
    <PaymentType>payway</PaymentType>
    <AccountNumber>1234567890</AccountNumber>
    <PaymentAmount>2.00</PaymentAmount>
    <IncludesSurchargeAmount>1.10</IncludesSurchargeAmount>
    <BranchNumber></BranchNumber>
    <ExpiryDate>2012-12</ExpiryDate>
    <CVV>123</CVV>
    <Properties>
      <Object></Object>
    </Properties>
  </PaymentDetails>
</PaymentRequest>

Example: Request a payment for payment plan

This example shows a PaymentRequest document containing details for a Payway payment and specifying a payment plan number that a payment amount of $2 will be allocated to.

Note: The usn, paymentRequest and allocationRequest parameters are all required to call processPayment.

<PaymentRequest>
  <PaymentDetails>
    <PaymentType>payway</PaymentType>
    <AccountNumber>1234567890</AccountNumber>
    <PaymentAmount>2.00</PaymentAmount>
    <IncludesSurchargeAmount>1.10</IncludesSurchargeAmount>
    <BranchNumber></BranchNumber>
    <ExpiryDate>2012-12</ExpiryDate>
    <CVV>123</CVV>
    <Properties>
      <Object></Object>
    </Properties>
  </PaymentDetails>
  <PaymentPlan>1010</PaymentPlan>
</PaymentRequest>

Example: Request a payment allocation

This example shows an AllocationRequest document to allocate an amount of $0.90 against transaction 21707609.

Note: The usn, paymentRequest and allocationRequest parameters are all required to call processPayment.

<AllocationRequest>
  <AllocateTo>
    <TransactionNumber>21707609</TransactionNumber>
    <AllocateAmount>0.90</AllocateAmount>
  </AllocateTo>
</AllocationRequest>

Example: Request an auto-allocated payment

This example shows an AllocationRequest document with the <AutoAllocate> element set to true. Smile will allocate the payment to any debits on the account, starting with the oldest unpaid invoice, automatically.

Note: The usn, paymentRequest and allocationRequest parameters are all required to call processPayment.

<AllocationRequest>
  <AutoAllocate>true</AutoAllocate>
</AllocationRequest>

Results

This method returns a PaymentResponse XML document that contains information about the status of the payment request.

Smile emits the TransactionClosed message when the payment is accepted. Smile emits the TransactionAllocated message when the payment is allocated.

Example: A returned PaymentResponse XML document

This example shows a returned PaymentResponse XML document. The document contains information about the payment and payment allocation and timestamped confirmation of payment receipt and surcharge.

<PaymentResponse xmlns:="http://xml.inomial.com/smile/2.xsd" xmlns:="http://ws.inomial.com/smile.2">
  <Payment>
    <PaymentNumber>61383006</PaymentNumber>
    <PaymentType>
      <PaymentTypeId>16</PaymentTypeId>
      <Name>Westpac PayWay</Name>
      <PaymentTypeCode>payway</PaymentTypeCode>
    </PaymentType>
    <Account>1000000008</Account>
    <Amount formatted="$2.00" currency="AUD">2.00</Amount>
    <Surcharge>
      <Amount formatted="$1.10" currency="AUD">1.10</Amount>
      <TaxAmount formatted="$0.10" currency="AUD">0.10</TaxAmount>
    </Surcharge>
    <Status>Accepted</Status>
  </Payment>
  <Allocation>
    <AllocateTo>
      <TransactionNumber>61383105</TransactionNumber>
      <AllocateAmount formatted="$1.10" currency="AUD">1.10</AllocateAmount>
    </AllocateTo>
    <AllocateTo>
      <TransactionNumber>21707609</TransactionNumber>
      <AllocateAmount formatted="$0.90" currency="AUD">0.90</AllocateAmount>
    </AllocateTo>
  </Allocation>
  <Receipt>
    <version>2.0</version>
    <transactionType>Receipt</transactionType>
    <company>1</company>
    <usn>1000000008</usn>
    <transactionNumber>61383006</transactionNumber>
    <currency>AUD</currency>
    <amount>-2.00</amount>
    <accountType>1</accountType>
    <gstAmount>0.00</gstAmount>
    <entryTimestamp>2012-12-17T09:51:17.868+11:00</entryTimestamp>
    <formattedAmount currency="AUD" formatted="$(2.00)">-2.00</formattedAmount>
    <formattedGstAmount currency="AUD" formatted="$0.00">0.00</formattedGstAmount>
    <unallocatedAmount>0.00</unallocatedAmount>
    <enteredByUsn>2142423066</enteredByUsn>
    <logTimestamp>2012-12-17T09:51:17.870+11:00</logTimestamp>
    <glCode>083</glCode>
    <formattedUnallocatedAmount currency="AUD" formatted="$0.00">0.00</formattedUnallocatedAmount>     
  </Receipt>
  <Surcharge>
    <version>2.0</version>
    <transactionType>Surcharge</transactionType>
    <company>1</company>
    <usn>1000000008</usn>
    <transactionNumber>61383105</transactionNumber>
    <currency>AUD</currency>
    <amount>1.10</amount>
    <accountType>1</accountType>
    <gstAmount>0.10</gstAmount>
    <entryTimestamp>2012-12-17T09:51:17.868+11:00</entryTimestamp>
    <salesReportCategory>surchrg</salesReportCategory>
    <formattedAmount currency="AUD" formatted="$1.10">1.10</formattedAmount>
    <formattedGstAmount currency="AUD" formatted="$0.10">0.10</formattedGstAmount>      
    <unallocatedAmount>0.00</unallocatedAmount>
    <enteredByUsn>2142423066</enteredByUsn>
    <logTimestamp>2012-12-17T09:51:18.367+11:00</logTimestamp>
    <glCode>200</glCode>
    <formattedUnallocatedAmount currency="AUD" formatted="$0.00">0.00</formattedUnallocatedAmount>     
  </Surcharge>
</PaymentResponse>

Faults

InvalidRequestException

This fault is returned when PaymentRequest or AllocationRequest are invalid.

NoSuchItemException

This fault is returned when the USN, PaymentRequest or AllocationRequest refer to an object that cannot be found.

Java client syntax

java -cp build/smilewsv2-client.jar [options] com.inomial.smile.client.v2.examples.ProcessPayment usn paymentRequest allocationRequest

usn: Purpose: Specifies the USN of the account.
paymentRequest: Purpose: Defines the path to the XML document containing the payment request.
allocationRequest: Purpose: Defines the path to the XML document containing the allocation request.

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