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 Payment Id 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)
  • createStartTime and createEndTime are optional params and can be used to retrieve a list of records created between the specified date range. Note that if createStartTime is specified and createEndTime is not specified, then createEndTime defaults to the current date/time
  • updateStartTime and updateEndTime are optional params and can be used to retrieve a list of records updated between the specified date range. Note that if updateStartTime is specified and updateEndTime is not specified, then updateEndTime defaults to the current date/time




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

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

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

Sample Output:
<list>
  <payment id="8">
  ...
  <payment id="7">
</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>
  <totalSurcharge>34.00</totalSurcharge> <!-- Only if Surcharge applicable to Payment amount -->
  <currencyCode>USD</currencyCode>
  <generateInvoice>false</generateInvoice>
  <effectiveDate>2010-12-31</effectiveDate>
  <invoiceText/>
  <purchaseDescription/>
  <internalNotes/>
  <invoices>
    <invoice id="34" />
  </invoices>
  <paymentMethodDTO type="CreditCard"> <!-- if payment method is 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>
  <paymentMethodDTO type="ACH"> <!-- if payment method is ACH-->
    <achPaymentMethod>
      <autopayPreference>1</autopayPreference> <!-- Set this to 1, 2, or 3 to save this as        the preferred auto-pay for this customer -->
      <abaRoutingNumber>...</abaRoutingNumber>
      <accountNumber>...</accountNumber>
      <institutionName>...</institutionName>
      <accountName>...</accountName>
      <accountType>...</accountType>
      ...
    </achPaymentMethod>
  </paymentMethodDTO>
<paymentMethodDTO type="Cash"> <!-- if payment method is CashOnDelivery-->
    <cashPaymentMethod>
      <notes>Paid in Cash</notes>
    </cashPaymentMethod>
  </paymentMethodDTO>
<paymentMethodDTO type="Check"> <!-- if payment method is check-->
    <checkPaymentMethod>
      
      <checkNumber>...</checkNumber>
      <accountNumber>...</accountNumber>
      <institutionName>...</institutionName>
      <checkDate>...</checkDate>
      <notes>...</notes>
      ...
    </checkPaymentMethod>
  </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>

To get all autoPay methods of a customer, Use this link. 

4.4.4 Cancel Payment

Use below API to cancel a payment. Cancel is not applicable on refunded or Voided payments.
DELETE       /rest/payment/[paymentId]
Comments