Skip to main content

Bills and payments

These are features that allow users to download bills and view their transaction history, as well as their current payment settings and forecast for future payments if applicable. Certain account configurations also allow card payments to be made.

Bills list​

Where the user can see a list of bills for an account and download the documents. This list is scoped to a given ledger ID, so where there are multiple ledgers on an account that produce billing documents, we display a list.

Storybook

Note​

Since the 'MAIN' ledger has been deprecated, bills for the main ledger are not being returned by the ledgers.bills API. For this use case, we can use the account.bills API.

One-off card payments​

Certain ledgers allow users to make payments to be recorded against the ledger balance. This is an example of making a payment onto the MAIN ledger type.

Validation rules for payment amount​

This example includes some front end validation on the payment amount based on the ledger balance. From a Kraken perspective, there isn't a 'correct' maximum amount and there isn't any backend validation that triggers for the amount you pay. Different markets sometimes want to encourage different behaviour around credit balance, with certain markets discouraging building up credit balances and using payment strategies that clear the balance on receipt of bill, and certain markets encouraging it to smooth out direct debit payments into a regular amount. To demonstrate this, this example lets people pay up to £1000, unless they have a larger negative balance than that, in which case, they can pay up to that balance amount. The idea behind this kind of validation is it helps to prevent people who don't have a large negative balance from making a large payment by mistake (accidentally adding another 0 for example).

We use Stripe to process card payments. The Stripe integration is implemented using the Stripe.js and React Stripe.js libraries.

Note​

You can find more information about how to initialise Stripe in your app here.

Storybook

Flow of Control​

The flow of control for one-off card payments is as follows:

  1. The user navigates to the one-off payments url and using the ledger selector, the user selects the ledger they want to make a payment for.
  2. A request is made to Kraken to get the amount owed on the selected ledger so it can be displayed on the page.
  3. The user enters the amount they wish to pay using the form and clicks the 'Enter card details' button.
  4. Using the amount, a request is made to Kraken to fetch a secret token, which is then stored in React Context, and then the page redirects to the card details page.
  5. In order to render the Stripe card details form, the following happens:
    1. Using the environment variable NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY (described here), a function is called that loads the Stripe.js script and initializes a Stripe object.
    2. The Kraken secret token is retrieved from context.
    3. The above 2 items are passed to the Stripe Elements provider as props. This in turn renders the Stripe card details form and creates a Stripe Elements instance and a Stripe PaymentIntent.
  6. Using the Stripe form, the user enters their card details and clicks 'Pay now'.
  7. This will trigger the confirm payment flow:
    1. The React Stripe.js' useElements hook has access the Elements instance (which has payment information collected by the Stripe Payment Element).
    2. The React Stripe.js' useStripe hook has access the Stripe instance passed to the Elements provider.
    3. Using the Stripe instance, the confirmCardPayment method is called along with the Elements instance as an argument value, which will confirm the payment with Stripe.
    4. Upon successful payment, the amount paid is stored in React Context.
    5. The page redirects to the success page, which retrieves the paid amount from context and displays it along with a success message.

Required environment variables​

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY should be added to your vercel environment variables as described here.

Customising the Stripe card details form​

The Stripe card details form's appearance can be amended by altering the object returned from CoralStripeAppearance or creating your own appearance object prop for the Stripe Elements provider.

import { Elements } from '@stripe/react-stripe-js';

const appearance = {
    ...CoralStripeAppearance(),
    style: {
        base: {
        color: '#000',
        fontFamily: 'Roboto, sans-serif',
        fontSmoothing: 'antialiased',
        fontSize: '16px',
        '::placeholder': {
            color: '#000',
            },
        },
    };
}

return (
    <Elements
        options={{ appearance }}
    >
        {...}
    </Elements>
);

Ledger payments and charges​

For a given ledger type, it can be helpful to provide a list of transactions recorded against that ledger. We also optionally show:

  • the current balance of the ledger (currently based on the ledger type)
  • the payment schedules for the ledger (current and future)
  • the next forecast payment for a ledger (if that's possible to forecast from the ledgers payment schedules)

French electricity ledger​

This example shows a French Electricity ledger. This ledger type is scoped to a particular electricity supply point, so it's supported to have multiple French Electricity ledgers per account. The user can choose the one they want to see charged for from the dropdown.

Charges are created on these ledgers annually or monthly, depending on the billing settings of the currently active agreement, so we don't show the balance since for many customers, for most of the year, it will just show credit accumulating. We could consider showing the balance figure if the current agreements associated to the ledger are billed monthly, since the balance would show a more up to date position.

We also display the payment forecast (when returned by the API) and current and future payment schedules.

Storybook

Main ledger​

This example shows a Main ledger in a British energy Kraken. The main ledger is a legacy set up, but is analogous to a single supplementary ledger that might have charges or credits from a variety of sources - it could be gas, electricity, customer service gestures etc.

Charges for energy services are typically created on these ledgers each month. We show the current balance of the ledger, along with the running balance when each transaction is applied.

We also display the payment forecast (when returned by the API) and current and future payment schedules.

Storybook

Payment schedules​

We show current and future payment schedules attached to a ledger in these views. Here are some examples of how that can look depending on the state of the account.

Current and Future payment schedule​

You might see this when a customer has changed the amount they pay per month

Storybook

Current holiday and future payment schedule​

You might see this when a customer is currently on a payment holiday

Storybook

There are more examples available in Storybook

Payment Instructions​

Payment instructions are set up for ledgers to allow payments to be requested by Kraken. We can use the setUpDirectDebitInstruction mutation to create or update the details for this.

Troubleshooting​

When this API is called, it requires that the Address Line 4 of the account billing address to be set, otherwise you may see this error:

Validation failed (city is required if any address fields are provided /customers/city);