6. Payments API

The related collection of entities associated with the "Payment":

• Payment - the main entity that represents one of these financial transactions, depending on the "paymentType" field:

  • • Payment (PaymentType=Payment) - this record indicates a payment by the customer against one or more outstanding invoices.

    • Refund (PaymentType=Payment) - this record indicates a transfer of funds back to the customer, usually linked with a previous payment.

    • House Credit (PaymentType=Credit) - Credit given to Customer without electronic or manual transfer of funds ( a negative amount indicates debit or increase in balance owed by customer whereas a positive number indicates a decrease in balance)

• ProcessorResult - if the payment was processed electronically by BluSynergy systems, then this entity contains the transaction identifiers and approval codes from the payment processor and may be used for reconciliation and audit purposes. If the Payment has been processed electronically, but external to BluSynergy, then do not send the ProcessorResult object with the Payment.

• InvoicePayment - this collection of associated objects indicate which payment(s) have been applied to which invoices and represent an many-to-many mapping between Invoice and Payment. For example if we have these 2 invoices that have been paid by a single payment #123 for $300:

            Invoice 1001, $100

            Invoice 1002, $200

Then, in addition to the Payment object, we need 2 nested InvoicePayment entities with the following data:

            Payment Number=123, Invoice Number = 1001, Amount Applied = $100, Balance = $200

            Payment Number=123, Invoice Number = 1002, Amount Applied = $200, Balance = $0

Payment Fields

PaymentInvoice Fields

6.1. Retrieve Payment:

GetPayment - Returns a subset of data seen in the Payment Detail Screen:

• 1. Parameters: Allow parameter to filter by PaymentType (Credit/Refund/Payment). Optional.

  2. Returns these domain objects: Payment (Transaction Detail panel), ProcessorResult (Authorization Record panel) and InvoicePayment (Linked Invoices panel).
     
     

GET /rest/payment/[id]?format=xml

GET /rest/credit/[id]? format=xml

GET /rest/refund/[id]?format=xml

Sample Output:

<payment id="7">

  <isSystemPayment>true</isSystemPayment>

  <customer id="5" />

  <paymentMethodType>Token</paymentMethodType>

  <currency id="USD" />

  <amount>194.25</amount>

  <balance>0.00</balance>

  <effectiveDate>2010-08-06</effectiveDate>

  <status>Paid</status>

  <paymentType>Payment</paymentType>

  <lastUpdated>2010-08-06</lastUpdated>

  <isProcessedByBillingRun>false</isProcessedByBillingRun>

  <processorResult id="10">

    <errorMessage />

    <transactionId>390.72665051790136</transactionId>

    <batchIndicator />

    <isSuccess>true</isSuccess>

    <customer id="5" />

    <statusCode />

    <amount>194.25</amount>

    <avsCode />

    <isError>false</isError>

    <currencyCode>USD</currencyCode>

    <otherMsg3 />

    <processorRequestType>authorize_api_call</processorRequestType>

    <otherMsg2 />

    <otherMsg1 />

    <responseTimeMilliSec>2</responseTimeMilliSec>

    <lastUpdated>2010-08-08</lastUpdated>

    <approvalCode>XYZ776.0854564137724</approvalCode>

    <statusMessage>authorized o</statusMessage>

    <cvvCode />

    <errorCode>0</errorCode>

    <dateCreated>2010-08-06</dateCreated>

    <secondaryAmount />

    <paymentProcessor id="6" />

  </processorResult>

  <paymentMethodContext>Visa - *****1111</paymentMethodContext>

  <dateCreated>2010-08-06</dateCreated>

  <paymentProcessor id="6">

    <name>Test Processor</name>

  </paymentProcessor>

  <invoicePayments>

    <invoicePayment id="1">

      <payment id="7" />

      <amountApplied>194.25</amountApplied>

      <invoice id="1" />

      <lastUpdated>2010-08-06</lastUpdated>

      <dateCreated>2010-08-06</dateCreated>

      <balanceRemaining>0.00</balanceRemaining>

      <customer id="5" />

    </invoicePayment>

  </invoicePayments>

  <notes />

  <paymentMethod id="3" />

</payment>

6.2. Retrieve Payment List:

Returns a paged list of Payments/Credits/Refunds. The transactions are sorted in descending order by effectiveDate Defaults used if the query string parameters are missing:

   offset=0

   max=50

   status = ignored if not provided

   amount = ignored if not provided

   customerId = ignored if not provided (i.e, returns a list of all customers)

GET /rest/payments?format=xml&offset=[n]&max=[m]&status=[status] &amount=[value]&customerId=[id]

GET /rest/credits?format=xml&offset=[n]&max=[m]&status= [status]&amount=[value]&customerId=[id]

GET /rest/refunds?format=xml&offset=[n]&max=[m] &status=[status]&amount=[value]&customerId=[id]

Sample Output:

<list>

  <payment id="7">

  ...

  <payment id="8">

</list>

6.3. Create a new Payment:

In general,Payments, Refunds and Credits are represented internally as a "Payment" entity, and differentiated by a "paymentType" property which could be either "Payment", "Refund" or "Credit".

Note that the "amount" property will be negative for Refunds.

There are two approaches to making a payment, either by passing in a PaymentMethod (such as a credit card, ACH, Check, etc.) or by using a pre-existing stored auto-pay PaymentMethod (added to the Customer previously via a POST /rest/customer/[id]/autopay)

The returned output from all these calls is a payment instance, i.e., same return as a /rest/payment/[id]?format=xml

POST /rest/payments?format=xml

POST /rest/refunds? format=xml

POST /rest/credits?format=xml

POST /rest/payments/autopay?format=xml

POST /rest/refunds/autopay?format=xml

POST /rest/payments?format=xml&extCustomerRef=[code]

In the following XML, note that:

• 1. action could be one of "processPayment", "processCredit" or "processRefund".

  2. The <paymentMethodDTO> is a generic data transfer object that holds the actual payment method used for remittance (as indicated by the "type" attribute). Inside the we could have one of creditCardPaymentMethod, achPaymentMethod, checkPaymentMethod, or cashPaymentMethod. The element must be set to the appropriate value.

  3. If the <generateInvoice> XML element value is set to "true", then the billing run for this customer is initiated, and on completion, the resulting unpaid invoices are target for this payment.

  4. The Invoice ID indicates which invoices the payment is to be applied against.

  5. As before, if you wish to reference the customer by your external reference value (rather than the BluBilling assigned numeric customer id), then use the "extCustomerRef=[code]" querystring parameter.
     

POST /rest/payments? format=xml                                                                       

<processPayment>

  <customer id="11"/>

  <amount>3430.95</amount>

  <currencyCode>USD</currencyCode>

  <generateInvoice>false</generateInvoice>

  <effectiveDate>2010-12-31</effectiveDate>

  <invoiceText/>

  <purchaseDescription/>

  <internalNotes/>

  <invoices>

    <invoice id="34" />

  </invoices>

  <paymentMethodDTO type="CreditCard">

    <creditCardPaymentMethod>

      <autopayPreference>1</autopayPreference> <!-- Set this to 1, 2, or 3 to save this as        the preferred auto-pay for this customer -->

      <cardNumber>...</cardNumber>

      <expiry>...</expiry>

      <cardType>Visa</cardType>

      ...

    </creditCardPaymentMethod>

  </paymentMethodDTO>

</processPayment>

A sample response is shown below. The <status> element will be "Paid" on success with the <amount> element representing the amount that was actually transacted.

<payment id="213">

  <isSystemPayment>true</isSystemPayment>

  <customer id="11" />

  <paymentMethodType>CreditCard</paymentMethodType>

  <currency id="USD" />

  <amount>3430.95</amount>

  <balance>0.00</balance>

  <effectiveDate>2011-09-06</effectiveDate>

  <status>Paid</status>

  <paymentType>Payment</paymentType>

  <lastUpdated>2011-09-07</lastUpdated>

  <isProcessedByBillingRun>false</isProcessedByBillingRun>

  <baseUser id="351">

    <username>jdoe</username>

    <firstName>Jane</firstName>

    <lastName>Doe</lastName>

  </baseUser>

  <processorResult id="192">

    <errorMessage />

    <transactionId>2162704713</transactionId>

    <batchIndicator />

    <isSuccess>true</isSuccess>

    <customer id="11" />

    <statusCode>1</statusCode>

    <amount>3430.95</amount>

    <avsCode>Y</avsCode>

    <isError>false</isError>

    <currencyCode>USD</currencyCode>

    <payment id="213" />

    <processorRequestType>AUTH_CAPTURE</processorRequestType>

    <responseTimeMilliSec>3741</responseTimeMilliSec>

    <lastUpdated>2011-09-07</lastUpdated>

    <approvalCode>0S33CM</approvalCode>

    <statusMessage>RRC_1_1 : This transaction has been approved.</statusMessage>

    <cvvCode>X</cvvCode>

    <errorCode />

    <dateCreated>2011-09-07</dateCreated>

    <secondaryAmount>0.00</secondaryAmount>

  </processorResult>

  <paymentMethodContext>Visa: 1111</paymentMethodContext>

  <dateCreated>2011-09-07</dateCreated>

  <paymentProcessor id="6">

    <name>Authorize.NET V1</name>

  </paymentProcessor>

  <invoicePayments>

    <invoicePayment id="171">

      <payment id="213" />

      <amountApplied>60.50</amountApplied>

      <invoice id="34" />

      <balanceRemaining>0.00</balanceRemaining>

      <customer id="11" />

    </invoicePayment>

  </invoicePayments>

</payment>

On the other hand, if a transaction with an autopay is required, then we'd use one of the calls below. The Invoice ID indicates which invoices the payment is to be applied against.

POST /rest/payments/autopay

POST /rest/payments/autopay&extCustomerRef=[code]

<processPaymentWithAutopay>

  <customer id="377" /> <!-- not required if extCustomerRef is supplied in querystring -->

  <currencyCode>USD</currencyCode>

  <amount>199.00</amount>

  <effectiveDate>2011-09-28</effectiveDate>

  <invoiceText></invoiceText> 

  <purchaseDescription></purchaseDescription>

  <internalNotes></internalNotes>

  <invoices>

    <invoice id='2492' />

  </invoices>

  <autopayPreference>1</autopayPreference> <!-- defaults to 1 if not supplied -->

</processPaymentWithAutopay>