HomeGuidesAPI ReferenceChangelog
Log In
Guides

Bundle guide

Branded, streamlined energy billing

Suggest Edits

What is Bundle?

Bundle is a set of API endpoints and Webhook Events that allows you to deliver a single branded billing experience to your users. Bundle empowers you to replace your user’s monthly utility statement with a custom-branded bill. You will create your branded bill using custom debit and credit Line Items. Arc receives your user’s utility statement directly and remits payment to the utility on their behalf.

The Bundle product line consists of two different products:

  • Utility Remittance - Utility Remittance is a lightweight bundled billing solution. Arc will receive your user’s utility statements and remit utility charges to the appropriate utility. You will own the rest of the billing experience. Utility Remittance might be right for you if your organization already has payment processing infrastructure in place.
  • Hosted Payments - With Hosted Payments, Arc collects your user’s payment methods using Stripe Checkout. You will then create invoices via the Arc API with custom credit and debit line items. Arc will charge your user for the entirety of the invoice while also ensuring the utility is paid on time for all utility charges. Hosted Payments might be right for you if your organization is looking for a more comprehensive bundled billing solution.

What do I need to do to get ready for Bundle?

  • Verify that your users’ Utilities are supported by Arc. Arc has built relationships with over 125 utilities. You can view a complete list of utilities where Bundle is supported here.
  • Connect and Plug. To use Bundle, you will need to utilize two of Arc’s foundational components: Connect and Plug. Connect links your users’ utility credentials to Arc. Plug is a set of API endpoints that allows you to gather your users’ utility statement and utility account data. For more information, see the Connect and Plug guides.
  • Prepare the content of your new branded bill. Determine which line items you want to appear on the custom bill. You are responsible for branding and delivering the bill to your users.
  • Set up user communication. Arc has no direct communication with your users. You will want to be in contact for a number of lifecycle events, such as when a Bundle enrollment is completed. These lifecycle events are detailed throughout this guide.
  • Onboard with Arc’s commercial team. Contact your Arc representative for more information.

How it Works - Utility Remittance

Utility Remittance Webhook Events

Relevant lifecycle events for Utility Remittance will trigger corresponding Webhook Events. Utilizing these Webhook Events will allow you to streamline your Utility Remittance integration.

📘

Webhook Events

While registering webhook endpoints for Bundle webhook event notification may require a bit more development, it is strongly recommended as you will be able to receive updates in real-time when statuses change and reduce the amount of API requests required to fetch important data. Of course, you can always poll the API if you prefer.

See How To Register A Webhook Endpoint and How To Verify Webhook Signatures in the Arc developer documentation.

Enrolling a User in Utility Remittance

📘

Utility Accounts and Credentials

For residential applications, the vast majority of customers have a single utility account associated with their utility credentials, but some have multiple utility accounts (e.g. a distinct meter in a separate building or a separately metered electric vehicle charger). For cases where there are multiple utility accounts associated with the utility credentials, all utility accounts must be enrolled.

📘

Override emails

During the onboarding process, Arc sets an override email on your customers utility accounts. This process ensures that your customer does not receive email communications about their bills directly from their utility. This is necessary to build a cohesive billing experience through Bundle. Note that sometimes the user’s email is used to login to their utility account. Since Arc changes this value, there can be confusion when your user tries to login to their utility directly. We recommend that you pass along the override email to your customer in case they want direct access to their utility. The override email can be found on the Bundle Enrollment and is included in the Utility Remittance Enrolled Webhook Event

  1. Link your user to Arc via Connect
  2. Obtain consent from your user. Once enrolled in Utility Remittance, your user will no longer receive a paper or email statement from their utility. You will need to provide terms of service and a consent form in your app. While Arcadia’s terms of service exist when using the Connect component to access utility account data, Arc does not explicitly provide them for Bundle users using your app.
  3. Collect your user’s payment details. With Utility Remittance, you will be responsible for charging your user for the line items on their custom bills. Arc will remit utility charges to the appropriate utility and reconcile these charges with you. The terms of reconciliation will be negotiated during the onboarding process.
  4. Enroll your user in Utility Remittance via the API.
    1. Arc routes the request to our enrollment team for review. Enrollment is an asynchronous process that can take up to one business day. After the initial request, the Bundle Enrollment will have either an ineligible or pending_enrollment status.
    2. All utility accounts associated with a utility credential must be enrolled. We do not support a subset of enrolled Utility Accounts at this time. If all of the Utility Accounts associated with the Utility Credential are eligible for Utility Remittance, the utility accounts will be enrolled.
    3. If any utility account is ineligible, none of the associated utility accounts will be enrolled. Reasons for ineligibility include:
      1. Past due balances
      2. Third party billing already in place
      3. Account for gas service only
      4. Unsupported two-factor authentication in place
      5. Incorrect credentials
      6. Account inactive
      7. Online account not set up
      8. Payment method missing
      9. Utility Payment plan in place
      10. San Diego Gas & Electric paperless gas account
    4. Arc will send a Webhook Event when the status of your Bundle Enrollment is determined. You can also check the current status of a Bundle Enrollment in the API here. The following list includes the Webhook Events that you can expect for a Bundle Enrollment:
      1. Utility Remittance Pending Enrollment
      2. Utility Remittance Enrolled
      3. Utility Remittance Ineligible
      4. Utility Remittance Pending Removal
      5. Utility Remittance Removed
  5. If a utility account is ineligible for Utility Remittance you will receive a Utility Remittance Ineligible Webhook Event with the Ineligibility Reason. If you are polling the Bundle Enrollment endpoint you will see the Ineligibility Reasons serialized on the Bundle Enrollment. The Ineligibility Reason will indicate if the reason can be resolved. You should independently resolve resolvable ineligibility reasons with your users. For example, you may need to work with your users to pay off past due balances or complete their online utility accounts. You can re-attempt enrollment into Utility Remittance at any time.

Managing a Bundled Bill with Utility Remittance

  1. Plug provides access to your user’s most recent utility statements. When a new utility statement is available you will be notified via a New Utility Statement Available Webhook Event. You may also poll the Plug API for this data.
  2. After determining that your user has received a new utility statement, make a request via the Bundle API to schedule remittance.
    1. You can specify a scheduled_at date on a Utility Remittance Item. If the date you specify falls on a weekend or a banking holiday, the Utility Remittance Item will be scheduled for the next business day after your specified date. If scheduled_at is omitted, the Utility Remittance Item will be scheduled for the next business day.
      1. We recommend that you place a hold on your user’s payment method before calling Arc to create the Utility Remittance Item. You can charge your user after the Utility Remittance Item has been remitted. You will be notified via the Utility Remittance Item Remitted Webhook Event or by polling the Utility Remittance Item endpoint in the API.
      2. You must create a Utility Remittance Item within 40 days of the utility statement’s issue date. If the Utility Remittance Item is not created, Arc will automatically unenroll your user from Bundle.

Removing Users from Utility Remittance

There are a few triggers that result in Arc automatically un-enrolling your user’s utility accounts from Utility Remittance.

  • A Utility Remittance Item has not been created within 40 days of a utility statement’s issue date. Note that the utility statement could be overdue at this point in time. We unenroll the user user to give them back control of payments to their utility.
  • Your user’s utility credentials are no longer valid and the user has not updated them via Connect. Automatic unenrollment will occur 12 days after Arc detects incorrect utility credentials. Recall that your Webhook Event handler will receive a Utility Credential Revoked Webhook Event when a utility credential becomes incorrect. See instructions for updating a utility credential with Connect.
  • The user has moved and the utility has issued a final utility statement.

You can request to remove a user’s utility account from Utility Remittance for any reason. Just like enrollment, unenrolling a user is an asynchronous process. Arc will send a Utility Remittance Pending Removal Webhook Event and Utility Remittance Removed Webhook Event as the status of the Bundle enrollment changes. As always, you can poll for these status updates in the API.

Sandboxed Functionality

Both enrollment and removal from Utility Remittance are asynchronous processes. Therefore, we have created a pathway for you to ‘simulate’ these events in real time when testing with sandboxed API Keys.

Enrollment

You can simulate both a successful and unsuccessful enrollment in Utility Remittance with the sandboxed endpoints. You can also simulate removing an active Bundle Enrollment.

Accept

  • Updates the status of all Bundle Enrollments associated with this Utility Credential from pending_enrollment to enrolled. Triggers the Utility Remittance Enrolled Webhook Event.

Reject

  • Updates the status of all Bundle Enrollments associated with this Utility Credential from pending_enrollment to ineligible. Triggers the Utility Remittance Ineligible Webhook Event.

Removal

  • Updates the status of all Bundle Enrollments associated with this Utility Credential from enrolled to removed. Triggers the Utility Remittance Removed Webhook Event.

How it Works - Hosted Payments

Hosted Payments Webhook Events

Relevant lifecycle events for Hosted Payments will trigger corresponding Webhook Events. Utilizing these Webhook Events will allow you to streamline your Hosted Payments integration.

📘

Webhook Events

While registering webhook endpoints for Bundle webhook event notification may require a bit more development, it is strongly recommended as you will be able to receive updates in real-time when statuses change and reduce the amount of API requests required to fetch important data. Of course, you can always poll the API if you prefer.

See How To Register A Webhook Endpoint and How To Verify Webhook Signatures in the Arc developer documentation.

Enrolling a User in Hosted Payments

📘

Utility Accounts and Credentials

For residential applications, the vast majority of customers have a single utility account associated with their utility credentials, but some have multiple utility accounts (e.g. a distinct meter in a separate building or a separately metered electric vehicle charger). For cases where there are multiple utility accounts associated with the utility credentials, all utility accounts must be enrolled.

  1. Link your user to Arc via Connect.
  2. Obtain consent from your user. Once enrolled in Hosted Payments, your user will no longer receive a paper or email statement from their utility. You will need to provide terms of service and a consent form in your app.
  3. Collect your user’s payment method via Stripe Checkout. You will be able to customize the payment method collection form through your Stripe Connect account. This account will be set up during the Bundle onboarding process. Contact your Arc representative for more information.
    1. Make a request to create a Stripe Checkout session.
      The URL provided in the response is the Stripe Checkout URL. You should redirect your user to this URL so Arc can collect the user’s payment method.
  4. Make a request to enroll your user in Hosted Payments via the API.
    1. Arc routes the enrollment request to our enrollment team for review. Enrollment is an asynchronous process that can take up to one business day. After the initial request, the Bundle Enrollment will have either an ineligible or pending_enrollment status.
    2. All utility accounts associated with a utility credential must be enrolled. We do not support a subset of enrolled utility accounts at this time. If all of the utility accounts associated with the utility credential are eligible for Hosted Payments, the utility accounts will be enrolled.
    3. If any utility account is ineligible, none of the associated utility accounts will be enrolled. Reasons for ineligibility include:
      1. Past due balances
      2. Third party billing already in place
      3. Account for gas service only
      4. Unsupported two-factor authentication in place
      5. Incorrect credentials
      6. Account inactive
      7. Online account not set up
      8. Payment method missing
      9. Utility payment plan in place
      10. San Diego Gas & Electric paperless gas account
    4. Arc will send a Webhook Event when the status of your Bundle Enrollment is determined. You can also check the current status of a Bundle Enrollment in the API here. The follow list includes the Webhook Events that you can expect for a Bundle Enrollment:
      1. Hosted Payments Pending Enrollment
      2. Hosted Payments Enrolled
      3. Hosted Payments Ineligible
      4. Hosted Payments Pending Removal
      5. Hosted Payments Removed
  5. If a Utility Account is ineligible for Hosted Payments you will receive a Hosted Payments Ineligible Webhook Event with the Ineligibility Reason. If you are polling the Bundle Enrollment endpoint you will see the Ineligibility Reasons serialized on the Bundle Enrollment. The Ineligibility Reason will indicate if the Ineligibility Reason can be resolved. You should independently resolve resolvable Ineligibility Reasons with your users. For example, you may need to work with your users to pay off past due balances or complete their online Utility accounts. You can re-attempt enrollment into Hosted Payments at any time.

Managing a Bundled Bill with Hosted Payments

  1. Plug provides access to your user’s most recent utility statements. When a new utility statement is available you will be notified via a New Utility Statement Available Webhook Event. You may also poll the Plug API for this data.
  2. After determining that your user has received a new utility Statement, create an invoice via the API. You will provide custom credit and debit line items. You should also include a Utility Remittance Line Item.
  3. Collect the invoice. If there are pending Utility Remittance Items on the invoice, we will charge the payment method the following day. See the Money Transmitter Compliance section below for more details.
    1. If the invoice includes a Utility Remittance Line Item, you must collect the invoice within 10 days of the utility statement’s issue date. If the invoice is not collected, Arc will automatically unenroll your user from Bundle.
  4. Arc will send an Invoice Collection Succeeded Webhook Event after a successful charge. If collecting the invoice is unsuccessful, you will receive an Invoice Collection Failed Webhook Event. In the latter case you will need to notify your user to update their payment method.

Updating a Payment Method

You can see all the payment methods tied to a client_user_id in the Bundle API. You can also request a Payment Method by ID.

Edit an Existing Payment Method

This feature is currently not available. Please add a new payment method and make it your user’s default.

Adding a New Payment Method

Arc collects your user’s payment method via Stripe Checkout. You will be able to customize the payment method collection form through your Stripe Connect account. The Stripe Connect account will be set up during the Bundle onboarding process. Contact your Arc representative for more information.

  1. Make a request to create a Stripe Checkout Session.
  2. The URL provided in the response is the Stripe Checkout URL. You should redirect your user to this URL so Arc can collect the user’s payment method.

The first payment method your user adds will be set as the default payment method. If your user adds subsequent payment methods you will need to explicitly update the default payment method.

Setting Default Payment Method

Arc can host multiple payment methods for your users. The first payment method your user adds will be set as the default payment method.The default payment method will always be used to charge your user. To update the default payment method, make a request to the Set Default Payment Method endpoint in the Bundle API.

📘

Default Payment Methods

If charging the default payment method fails, Arc will not attempt to charge any other payment method on file. A payment method must be made the default in order to be charged.

Removing a Payment Method

You can remove a payment method by posting to the Delete Payment Method endpoint. Note that you will not be able to remove a payment method that is set as the default payment method.

Removing Users from Hosted Payments

There are a few triggers that result in Arc automatically un-enrolling your user from Hosted Payments:

  • Your user will be automatically unenrolled from Hosted Payments if we are unable to collect an Invoice using the user’s default Payment Method. If a credit card is declined, Arc will attempt to collect payment every 3 days for a total of 5 attempts. If an ACH method is declined, Arc will continue to try and collect payment every 3 days for a total of 3 attempts. Automatic un-enrollment will occur after the final decline. You will receive an Invoice Collection Failed Webhook Event after each attempt to collect an Invoice. It is your responsibility to contact your user to update their Payment Method.
  • A request to collect an Invoice has not been received within 10 days of a Utility Statement’s issue date.
  • Your user’s Utility Credentials are no longer valid and the user has not updated them via Connect. Automatic un-enrollment will occur 12 days after Arc detects incorrect Utility Credentials. Recall that your Webhook Event handler will receive a Utility Credential Revoked Webhook Event when a Utility Credential becomes incorrect. See instructions for updating a Utility Credential with Connect.
  • The user has moved and the utility has issued a final utility statement.

You can request to remove a user’s Utility Account from Hosted Payments for any reason. Just like enrollment, unenrolling your user is an asynchronous process. Arc will send a Hosted Payments Pending Removal (Beta) Webhook Event and a Hosted Payments Removed (Beta) Webhook Event as the status of the Bundle Enrollment changes. As always, you can poll for these status updates in the API.

Sandboxed Functionality

Both enrollment and removal from Hosted Payments are asynchronous processes. Therefore, we have created a pathway for you to ‘simulate’ these events in real time when testing with sandboxed API Keys.

Enrollment

You can simulate both a successful and unsuccessful enrollment in Hosted Payments with the sandboxed endpoints. You can also simulate removing an active Bundle Enrollment.

Accept

  • Updates the status of all Bundle Enrollments associated with this Utility Credential from pending_enrollment to enrolled. Triggers the Hosted Payments Enrolled Webhook Event.

Reject

  • Updates the status of all Bundle Enrollments associated with this Utility Credential from pending_enrollment to ineligible. Triggers the Hosted Payments Ineligible Webhook Event.

Removal

  • Updates the status of all Bundle Enrollments associated with this Utility Credential from enrolled to removed. Triggers the Hosted Payments Removed Webhook Event.

Rebills

For a variety of reasons, a Utility will sometimes edit or reissue a utility statement. We flag these potential rebills in the Plug API with billing_flags. If a Utility Statement has a billing_flag with type = 'possible_rebill' , the Utility Statement may be a duplicate/slight variation on a previous Utility Statement. We provide the conflicting Utility Statement as conflicting_utility_statement_id in the billing_flag metadata.

When you receive a possible rebill via the Plug API, we recommend manually reviewing the PDFs of the two Utility Statements using UtilityStatement#pdf_url. If you determine that the flagged Utility Statement is a rebill and you have already created a Utility Remittance Item/Invoice with a Utility Remittance Line Item for the original Utility Statement, further action may be required. There are 3 scenarios to consider.

  • The utility_charge on the flagged Utility Statement is the same as the utility_charge on the conflicting Utility Statement. The Utility may have tweaked the service dates or some other field. No action is needed.
  • The utility_charge on the flagged Utility Statement is less than the utility_charge on the conflicting Utility Statement, In this case, you may have overpaid the customer’s bill. This overpayment should be reflected on your customer’s next Utility Statement. No action is needed.
  • The utility_charge on the flagged Utility Statement is greater than the utility_charge on the conflicting Utility Statement, In this case, you may have an outstanding balance to pay on your customer’s behalf.
    • Create a new Utility Remittance Item/Invoice with a Utility Remittance Line Item and set amount_cents to cover the remaining balance. Note that the new Utility Remittance Item/Invoice with a Utility Remittance Line Item should be created with the newer flagged utility_statement_id.

Onboarding

At this point in time we do not offer self-service onboarding for Bundle. Please contact your Arc representative to get your Enterprise Account set up to support Bundle.

Updated 6 months ago