Invoice Collect Options

Many POST/PATCH API calls in Stax Bill have an optional field in the JSON body called invoiceCollectOptions. This object allows you to provide special instructions for how to collect for the invoice which may be generated as a result of the API call. These special instructions are limited to just the first invoice, and only if that invoice is immediately generated as a result of the action. For example, the invoice collect options would not affect the first invoice when activating a subscription that does not charge upon activation. It would also not have an effect if autopost is turned off, or if temporarilyDisableAutoPost is explicitly set to true. One of the important advantages of the invoice collect options is the ability to roll back the transaction if the payment fails. Here are the situations where you can provide invoice collect options:

Activating a subscription
Finalizing a purchase(s)
Doing a mass activation/finalization of a customer’s subscriptions/purchases
Adding a new tracked quantity to a customer’s subscription.
Posting a customer’s ready draft charges

In addition to rolling back the transaction upon failed payment, you can also provide the method of payment (credit card or ACH) for Stax Bill to try with your account’s configured payment gateway(s). However, if you choose to directly provide a new payment method inside the invoiceCollectOptions object, then that exposes your company to PCI compliance.

🚧
PCI Compliance
If your company is already PCI compliant, providing credit card information in the invoiceCollectOptions allows for more advanced payment method entry scenarios.
Do not include card information inside the invoiceCollectOptions object if your company is not PCI compliant and does not intend to adhere to these requirements.
If you are looking for an alternate way to provide (credit card) payment information, consider using transparent redirect or AJAX transparent redirect. This will get the payment information to Fusebill and you will receive a Fusebill generated payment method ID. This ID could can be used in lieu of the raw card data in the invoiceCollectOptions object.

Subscription activation using the default payment method

If you have a customer with Stax Bill ID 12345 interested in subscribing to a plan frequency with ID 67890, the first step is to create the subscription with a POST call

POST https://secure.fusebill.com/v1/subscriptions
{
    "CustomerID": 12345,
    "planFrequencyID": 67890,
    "reference": "MyCompany'sInternalID",
    "couponCodes": [
        "youthDiscount1"
    ]
}

Copy the id from the response. This is the Stax Bill generated subscription ID that uniquely identifies this subscription, which is in the ‘Draft’ status.

Suppose you want to use the customer’s default payment method, and you want to roll back the transaction if their default payment method fails to pay for the invoice (assuming the subscription is configured to generate charges upon activation and invoice autopost is on).

The call to use is POST v1/customers/purchase/{{customerID}}. The list specificSubscriptionIds should contain only the id of the draft subscription. The list specificPurchaseIds should be empty. Inside the invoiceCollectOptions, the paymentMethod enum should be set to the value “UseDefaultPaymentMethod”, and rollbackOnFailedPayment should be set to true.

Here is the call, assuming the subscription ID is 1000:

POST https://secure.fusebill.com/v1/customers/purchase/12345
{
    "invoiceCollectOptions": {
        "paymentMethod": "UseDefaultPaymentMethod",
        "rollbackOnFailedPayment": true
    },
    "specificSubscriptionIds": [
        1000
    ],
    "specificPurchaseIds": []
}

Note that it was necessary to provide specificPurchaseIds as an empty list because not providing specificPurchaseIds is interpreted as meaning “attempt to finalize all draft purchases on the customer”.

Assuming the customer’s default payment method succeeded, the subscription will be active, and the invoice will be in status ‘paid’.

If something went wrong with the payment method, the following error will return since rollbackOnFailedPayment was explicitly set to true:

{
    "ErrorId": 0,
    "HttpStatusCode": 400,
    "Errors": [
        {
            "Key": "Api Error",
            "Value": "Rolling back: invoice failed to be paid in full."
        }
    ]
}

If the customer is examined, it will have a draft subscription with ID 1000.

The workflow for handling the failure is entirely custom. It could be handled by prompting a user for a different payment method, or it could be handled by deleting the subscription.

Deleting the subscription requires one call to the DELETE endpoint:

DELETE https://secure.fusebill.com/v1/subscriptions/Delete/1000

It is important to delete the subscription when it is in ‘Draft’ status, because once a subscription is active (and has created financial records), it can no longer be deleted, it can only be cancelled.

Finalizing draft purchase(s) using available funds

This workflow is very similar to the subscription activation flow. Assuming you’ve got a customer with Stax Bill ID 12345 interested in purchasing a priced catalog product with ID 67890, the first step is to create the purchase with a POST call:

POST https://secure.fusebill.com/v1/Purchases
{
    "productId": 67890,
    "quantity": 2.0,
    "customerId": 12345,
    "name": "T-Shirt"
}

Copy the id form the response. This is the Stax Bill generated ID of the purchase, which is in ‘Draft’ status.

Suppose you want to use the customer’s payment method with ID 2000, and you again want to roll back the transaction upon failure. Suppose the customer has $50 in available funds as displayed on their dashboard, and the desire is to use that $50 to pay for part of the purchase. After the $50 is used, the payment method with ID 2000 is to be used to pay the rest of the invoice.

The call to do this is POST v1/purchases/purchase. In the JSON body, the customerId should be 12345, and purchaseIds should be a list containing the purchase ID. Inside the invoiceCollectOptions the paymentMethod enum should be set to the value “UseExistingPaymentMethod”, rollbackOnFailedPayment should be set to true, paymentMethodId should be 2000, and useAnyAvailableFundsFirst should be set to true.

Here is the call, assuming the purchase ID is 1000:

POST https://secure.fusebill.com/v1/purchases/purchase
{
  "customerId": 12345,
  "purchaseIds": [
    1000
  ],
  "invoiceCollectOptions": {
    "paymentMethod": "UseExistingpaymentMethod",
    "paymentMethodId": 2000,
    "useAnyAvailableFundsFirst": true,
    "rollbackOnFailedPayment": true
  }
}

The workflow for handling a failure is entirely custom. It could be handled by prompting a user for a different payment method, or it could be handled by deleting the purchase.

Deleting the purchase requires one call to the DELETE endpoint:

DELETE https://secure.fusebill.com/v1/Purchases/1000

Suppose instead the customer wants to make multiple purchases at once. An alternative approach is to combine all the above into one call using a different endpoint:

POST https://secure.fusebill.com/v1/Purchases/BulkCreate
{
  "customerId": 12345,
  "autoPurchase": true,
  "purchases": [
    {
      "name": "purchase1",
      "quantity": 1,
      "productId": 67890
    },
    {
      "name": "purchase2",
      "quantity": 3,
      "productId": 67891
    }
  ],
  "invoiceCollectOptions": {
    "paymentMethod": "UseExistingpaymentMethod",
    "paymentMethodId": 2000,
    "useAnyAvailableFundsFirst": true,
    "rollbackOnFailedPayment": true
  }
}

This call attempts to create two draft purchases: one for product 67890, and one for 67891. Since the optional property autoPurchase is true, those products are automatically purchased, which causes an invoice to post. From here the invoiceCollectOptions take over. Since useAnyAvailableFundsFirst is true, the balance on deposit for the customer ($50) is used.

Suppose the payment method with ID 2000 fails to pay the remainder of the invoice. Since rollbackOnFailedPayment is true, the entire transaction reverses. This means there is no invoice, the $50 remains on deposit, and the two purchases are gone (hard deleted). The state of the customer returns to what it was when the call was made.

Post draft charges, providing a payment method

In Fusebill, a draft (ready) invoice is an invoice composed of only charges that are ready to be posted. They occur when autopost is off at the time a subscription or purchase outputs a charge(s). There is a method in the Fusebill API to post all the ready charges belonging to a customer. For example:

POST https://secure.fusebill.com/v1/draftInvoices/PostReadyCharges?customerId=12345

would post an invoice with all the charges belonging to the customer with Stax Bill ID 12345 which have postable equal to true.

This endpoint also uses the invoiceCollectOptions object. Thus far we’ve only used a few of the options for paymentMethod. Below is the full list of acceptable enum values for that list.

📘
paymentMethod values:

UseDefaultPaymentMethod

UseExistingPaymentMethod

UseExistingPaymentMethodAndMakeDefault

UseProvidedPaymentMethodOnce

UseProvidedPaymentMethodAndMakeDefault

UseProvidedPaymentMethodAndSave

CreateAndApplyCredit

Three of the values specify to use a provided payment method. To use any of those three options, the creditCard or achCard object must be present. Again, providing raw card data exposes you to PCI Compliance risk.

For details about which fields constitute a credit card, consult the Create Credit Card Payment Method call.

For details about which fields constitute an ACH card, consult the Create ACH Card Payment Method call.

If you want to provide a credit card and make it the customer’s default, this is the call:

POST https://secure.fusebill.com/v1/draftInvoices/PostReadyCharges?customerId=12345
{
  "invoiceCollectOptions": {
    "paymentMethod": "UseProvidedPaymentMethodAndMakeDefault",
    "useAnyAvailableFundsFirst": false,
    "creditCard": {
      "cardNumber": 1234123412341234,
      "expirationMonth": 2,
      "expirationYear": 23,
      "cvv": 123,
      "firstName": "Karen",
      "lastName": "Wood",
      "address1": "10 Dodge St",
      "address2": "",
      "city": "Columbia",
      "stateId": 1,
      "countryId": 124,
      "source": "Manual",
      "postalZip": "V9V 9V9",
      "customerId": 12345
    },
    "achCard": null,
    "rollbackOnFailedPayment": false
  }
}

Notice that rollbackOnFailedPayment is set to false, meaning that the invoice will post regardless of whether the card can pay the amount (or even validate).

The following is the call to do the same, but with an ACH card and not saving the payment method for future use.

POST https://secure.fusebill.com/v1/draftInvoices/PostReadyCharges?customerId=12345
{
  "invoiceCollectOptions": {
    "paymentMethod": "UseProvidedPaymentMethodOnce",
    "useAnyAvailableFundsFirst": false,
    "creditCard": null,
    "achCard": {
      "accountNumber": 123457832156,
      "transitNumber": 12345,
      "bankAccountType": "CHQ",
      "firstName": "James",
      "lastName": "McHenry",
      "address1": "98 Roberts St",
      "address2": "",
      "city": "Chicago",
      "stateId": 1,
      "countryId": 124,
      "postalZip": "V9V 9V9",
      "customerId": 12345,
      "source": "Manual"
    },
    "rollbackOnFailedPayment": false
  }
}

Adding tracked quantities, with rollback and on credit

Since tracked quantities have reference values subject to uniqueness constraints, you may be interested in adding tracked quantities only if the customer can immediately pay for the item in full.

Suppose you want to add an item with serial number 176484555623562 to a subscription product with ID 5000 only if the customer can pay for it.

POST https://secure.fusebill.com/v1/SubscriptionProductItems
{
  "reference": "176484555623562",
  "name": "Hardware",
  "subscriptionProductID": 5000,
  "invoiceCollectOptions": {
        "paymentMethod": "UseDefaultPaymentMethod",
        "rollbackOnFailedPayment": true
    }
}

Just like with the other endpoints, the transaction is rolled back should the payment attempt fail. This means the serial number 176484555623562 would still be available for a tracked reference value, since no tracked item exists with that serial number.

Suppose instead you want to replace a customer’s damaged product with serial number 56451384651 and replace it with a new product with serial number 489615161638 at no charge. This can be done with the PATCH endpoint and the “CreateAndApplyCredit” option:

PATCH https://secure.fusebill.com/v1/SubscriptionProductItems
{
  "subscriptionId": 2000,
  "subscriptionProducts": [
    {
      "subscriptionProductId": 5000,
      "subscriptionProductItems": [
        {
          "name": "Replacement Hardware",
          "reference": 489615161638,
          "operation": "Insert"
        },
        {
          "operation": "Delete",
          "subscriptionProductItemId": 123456
        }
      ]
    }
  ],
  "invoiceCollectOptions": {
    "paymentMethod": " CreateAndApplyCredit "
  }
}

This means that if the addition of the new tracked quantity outputs a charge of $45.50, then it will be waived by a credit of $45.50 that is immediately applied against the invoice.