Home‎ > ‎Developer's Guide‎ > ‎REST Web Service API‎ > ‎

4.4 Payments API

4.4.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).

Returns this object graph: Payment, ProcessorResult and I nvoicePayment



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>

4.4.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>



4.4.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_v1/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, tokenPaymentMethod, 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. 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


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>

Comments