Managing customers and invoices

Creating a customer with HelcimPay.js

The HelcimPay.js initialize request allows you to pass a customerRequest object that will be used by the Helcim system to:

• Create a customer object on approved or declined payment that the payment is linked to, using the parameters passed in the request.
• Prepopulate the Cardholder name and AVS Street address and ZIP / Postal code fields in the payment modal.

The customerRequest object allows you to set the following values:

• A unique customerCode reference for the customer, that may match your system
• A contactName that is saved in the customer object and used to prepopulate the Cardholder name field in the payment modal, as well as an optional businessName and cellPhone.
• An optional billingAddress sub-object that is saved in the customer object and used to prepopulate the Street address and ZIP / Postal code fields in the payment modal
• An optional shippingAddress sub-object that that is saved in the customer object.

If a customerRequest object is not passed in the initialize request, the Helcim system will create a basic customer object based on your default customer settings and the payment details passed by the customer in the modal.

Creating an invoice with HelcimPay.js

The HelcimPay.js initialize request allows you to pass a invoiceRequest object that will be used by the Helcim system to:

• Create an invoice object on successful payment that the payment is linked to, using the parameters passed in the request.

The invoiceRequest object allows you to set the following values:

• A unique invoiceNumber reference for the invoice, that may match your system.
• Whether the invoice created has a tipAmount or depositAmount.
• Whether the invoice has any shipping, pickup, tax, or discounts objects.
• An array of objects containing any lineItems objects.

The total amount due on an invoice object created by an invoiceRequest in your HelcimPay.js initialization, can be for the same amount or a different amount the the payment amount passed. If the sum of the different amounts in the invoiceRequest is greater than your payment amount, the invoice will remain with a status of due until the full amount is paid.

If a invoiceRequest object is not passed in the initialize request, the Helcim system will create a basic object based on your default invoice settings.

Linking to an existing customer or invoice

If you have an existing customer or invoice in the Helcim system that you would like to link the payment to, you can utilize the customerCode and invoiceNumber parameters. If you pass both a customerCode and invoiceNumber, the invoice must be associated and linked to the customer object first. You can use the Update invoice endpoint.

Passing an existing customerCode with stored payment details will result in the payment modal pre-populating those details, which is a great way to make subsequent checkouts efficient for your customers. To link a payment to a customer but hide any stored payment details, you can utilize the hideExistingPaymentDetails parameter.