API Calls for Pre-paid Scenario

This developer guide shows the typical sequence of activities relevant for pre-paid subscription plans.

Sample Plan and Charges

For this example, consider a hypothetical web hosting company, called "DaddyHost", wishes to introduce a plan that has two charges:

• 1. A monthly recurring charge of $165. This charge is pre-paid and pro-rated (i.e., proportionately billed for mid-month signup).

  2. Usage charges apply for web pages; 100 web pages are included at no additional charge, beyond which an  Overage charge of $1.65/page is levied each month. Of course, Usage charges can only be post-paid.

Note: The configuration of the sample plan above is covered in detail under [Guides and How To] >> [Sample Pre-paid Plan].

DaddyHost wishes to collect pro-rated payment upfront when the customer signs up. In order to simplify their billing, they have chosen to bill all their customers on the 1st of every month (rather than opt for Anniversary billing). See the [Guides and How To] >> [Sample Pre-paid Plan] for details on these choices.

API Calls Invoked for New Customer Signup

The BluBilling REST API details are covered here. This guide will provide insights on the sequence of API calls that need to be invoked in order to meet DaddyHost's requirements.

DaddyHost would collect the following information from the prospective customer on their website:

• Customer information (name and contact information)

• The Plan selected by the Customer

• The Customer's payment information (either credit card or ACH/bank draft)

Then, DaddyHost would initiate the following calls from their website.

1. Create the Customer

DaddyHost also creates an account on their system, so they have their own identifier for the customer (JOHNDOE001). So DaddyHost makes the following request:

POST  /rest/customers?format=xml

<customer>

    <name>John Doe</name>  

    <status>Active</status>

    <extCustomerRef>JOHNDOE001</extCustomerRef> <!-- DaddyHost assigned Customer ID -->

    <locale>en_US</locale>

    <isBusinessAccount>true</isBusinessAccount>

    <currency id="USD"/>

    <billingContact>

        <username>jdoe001</username>

        <passwd>lhIU43FD</passwd>

        <accountLocked>true</accountLocked> <!-- Prevents the customer from logging into BluBilling -->

        <firstName>John</firstName>

        <lastName>Doe</lastName>

        <emailPrimary>johndoe@jdoe.com</emailPrimary>

        <workPhone>555 555 5555</workPhone>

        <address>

            <street1>43 Main Av</street1>

            <city>Chicago</city>

            <state>IL</state>

            <zip>12345</zip>

            <country>United States</country>

            <countryCode>usa</countryCode>

        </address>

    </billingContact>

</customer>

The response echoed back from BluBilling (abridged for brevity) contains the values sent along with defaults populated and identifiers assigned as seen below.

<customer id="366">  <!-- BluBilling assigned Customer ID -->

    <name>John Doe</name>  

    <extCustomerRef>JOHNDOE001</extCustomerRef>

        ...

        ...

</customer>

So, going forward we could either use the BluBilling assigned customer Id (366) or refrence the customer using the DaddyHost assigned identifier (JOHNDOE001).

2. Create the Order

The SubscriptionOrder represents the association between the above customer and a particular Plan. So we want to create an Order and generate an Invoice as well so that we know the exact amount to pay.

POST rest/orders?format=xml&extCustomerRef=JOHNDOE001&generateInvoice=true

<subscriptionOrder>

    <orderStatus>Active</orderStatus>

    <startDate>2011-09-20</startDate> <!-- The start date can be in the future if a free trial period is offered -->

    <isAutoRenew>false</isAutoRenew>

    <contractCode>WHITE-LBL-A</contractCode> <!-- the Plan associated with this order -->

    <orderLineItems>

        <orderLineItem>

        <position>1</position>

        <quantity>1.0</quantity> <!-- the quantity is required -->

        <priceCode>MNTHLY</priceCode>  <!-- each charge associated with plan -->

        </orderLineItem>

    </orderLineItems>

</subscriptionOrder>

Since we have the "generateInvoice=true" querystring parameter, an invoice will be immediately generated for this customer and returned in the response:  

<subscriptionOrder id="381">

    <orderNumber>1036</orderNumber>

    <contractCode>WHITE-LBL-A</contractCode>

    <customer id="366" />

       ...

     <!-- other order fields -->

    <invoices>

        <invoice id="2396">

            <invoiceDate>2011-09-06</invoiceDate>

            <outstandingBalance>60.50</outstandingBalance> <!-- Amount to pay -->

            <status>Outstanding</status>

            <invoiceNumber>1019</invoiceNumber> <!-- End user only sees the invoiceNumber, not the id -->

            <billingStartDate>2011-09-01</billingStartDate>

            <billingEndDate>2011-09-30</billingEndDate>

            <invoiceLineItems>

                ...

                <!-- Invoice line Item details -->

            </invoiceLineItems>

        </invoice>

    </invoices>

</subscriptionOrder>

At this point, an Order has been placed, and since it is a pre-paid order with the generateInvoice flag set, it has already been invoiced for the correct amount. Note that in the above case the amount has been adjusted so that the charge is pro-rated to account for the mid-month start date.

Note: In simple cases it may be possible for the calling application to pre-determine the amount, but in complex cases (e.g., taxes, discounts, pro-rating, tiered pricing, etc.), it would be best to let BluBilling generate an invoice so that the precise amount can be calculated per the configured business rules.

3. Remit the Payment

Once the invoice has been generated, the correct amount may be presented to the user for payment. A request for processing payment using a credit card is show below.

POST  rest/payments?format=xml&extCustomerRef=JOHNDOE001

Request XML:

<processPayment>

    <amount>9.99</amount>

    <currencyCode>USD</currencyCode>

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

    <invoices>

        <invoice id="2396" />

    </invoices>

    <paymentMethodDTO type="CreditCard">

        <creditCardPaymentMethod>

            <!-- Set to 1, 2, or 3 to save as customer's preferred auto-pay method -->

            <autopayPreference>1</autopayPreference>

            <cardNumber>4111111111111111</cardNumber>

            <expiry>2014-01-31</expiry>

            <cardType>Visa</cardType>

        </creditCardPaymentMethod>

    </paymentMethodDTO>

</processPayment>

And the Response:

<payment id="213">

    <isSystemPayment>true</isSystemPayment>

    <customer id="366" />

    <paymentMethodType>CreditCard</paymentMethodType>

    <currency id="USD" />

    <amount>60.50</amount> <!-- validate amount -->

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

    <status>Paid</status>   <!-- Use this element to validate that payment is successful -->

    <paymentType>Payment</paymentType>

    <isProcessedByBillingRun>false</isProcessedByBillingRun>

    <processorResult id="192">

        <customer id="366" />

        <transactionId>2162704713</transactionId>

        <isSuccess>true</isSuccess>

        <isError>false</isError>

        <statusCode>1</statusCode>

        <amount>60.50</amount>

        <!-- Address verification result: Y = Match (AVS ok); N = No Match (AVS fail); X = Unsupported -->

        <avsCode>Y</avsCode>

                    <!-- CVV result: Y = Match (CVV ok); N = No Match (CVV fail); X = Unsupported-->

        <cvvCode>X</cvvCode>

        <currencyCode>USD</currencyCode>

        <payment id="213" />

        <processorRequestType>AUTH_CAPTURE</processorRequestType>

        <responseTimeMilliSec>3741</responseTimeMilliSec>

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

        <approvalCode>0S33CM</approvalCode> <!-- Correlate with payment processor statements-->

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

        <errorCode />

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

        <secondaryAmount>0.00</secondaryAmount>

        <batchIndicator />

        <errorMessage />

        <paymentProcessor id="6" />

    </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="2396" />

            <customer id="366" />

        </invoicePayment>

    </invoicePayments>

</payment>

If the payment attempt is successful, then nothing more needs to be done. BluSynergy's BluBilling system will generate invoices periodically and perform the bill-presentment. If the <autopayPreferance> element had been set in the request XML, then the customer's credit card or bank account will be automatically billed for the monthly amount.

If the payment does not go though, DaddyHost's policy is to allow the customer upto three retry attempts before cancelling the order and invoice. See the "API calls for change management" section on how to cancel the invoice and order.

Note: Once an Invoice has been generated, the Order cannot be deleted. The recommended practice is to Cancel the Invoice and Suspend the Order.