Collect Payments via Stripe

Nue's Billing Accelerator simplifies the invoicing and collection workflow for businesses by seamlessly integrating with Stripe. By effortlessly generating invoices from orders and smoothly transferring them to Stripe for payment processing, Nue ensures a streamlined experience. When customers settle their invoices via Stripe, either by using the payment link in the invoice email or through automatic credit card charges, Nue automatically updates the corresponding invoice, marking the balance as paid. This powerful integration between Nue and Stripe presents businesses with an efficient and hassle-free billing solution, empowering them to effectively manage their finances.

The following diagram illustrates how Nue integrates with Stripe for payments and collections at a high level.

Setup Stripe Connection

Permissions Required

Please enable the following permissions in the user role: 

• Integrations
  • Manage Stripe Integration
• Collections
  • View Payment Application
  • Manage Payment Application

Setup Connection

• Navigate to System Settings
• Search for Stripe Integration

• Enter Publishable Key and Secret Key

  • You can get Publishable key and Secret key here: https://dashboard.stripe.com/apikeys

  • Please note that Stripe has Live Mode and Test Mode.  The keys for each mode are different. In Live Mode, the secret key cannot be revealed directly, we can roll the secret key and keep the secret-key locally.
• Click Activate.  If everything works well, you can see the ACTIVE indicator showing the connection is live.

Map Existing Stripe Customers with Salesforce Accounts

This step is required only if you already have an existing Stripe instance and you would like to map the customers in your Stripe instance to the accounts in Salesforce.   

When a new invoice is generated, Nue creates a new customer record in Stripe, if the customer doesn't exist.  We are using this mapping to determine if a customer already exists in Stripe.

Prepare Mapping Data

Export Salesforce Accounts

In this step, we will export Salesforce Accounts using Dataload.io provided by Salesforce.

• Login to Salesforce and navigate to Setup
• Search Dataloader.io in Quick Find and click to launch Dataloader.io
• Login to Dataloader.io with Salesforce
• Click 'New Export Task' and select “Account“ Object with “Account ID“ and “Account Name“, click Save & Run
  
• Click to download the export file.  

Export Stripe Customers

• Navigate to Stripe Dashboard to view the List of Customers
• Click Export button
• In the Export popup, select Data Range ALL, select ID and Name, and click Export

Create Mapping File

First, you need to download the Nue customer mapping template. 

• Login to Nue, and navigate to System Settings
• Search settings: "Stripe Integration"
• Click 'Import Mapping' button, and click Download template. 

In the template, insert the data using the data exported from Salesforce and Stripe to create the account and customer mapping.

After the mapping is complete, save it as a CSV file.

Import Mapping File

Click 'Import' button to import the CSV mapping files.  If there are errors, you will see an Error link where you can download the Error CSV file.  You can correct the error and re-import the CSV file.

Collection Scenarios Overview

Now let's take a deeper look at the following common collection scenarios.

PAY INVOICES  When invoices are generated in Nue by the billing engine, Nue will automatically transfer the invoices to Stripe. An email is sent to customers’ email address on file with the invoice PDF attached.

• One-time payments
• Recurring payments

ISSUE CREDITS When credit memos are created or negative invoices are generated in Nue by the billing engine, Nue will automatically transfer the credit memos or negative invoices to Stripe as credits.  The credits will be used later to pay future invoices by Stripe.

ISSUE CREDIT-NOTE When issue a credit-note within the invocie in Stripe, Nue will take it as a credit applied to the invoice. 

NON-ELECTRONIC PAYMENTS Customers can send in non-electronic payments for invoices in Stripe.  Finance ops users can mark the invoices as Paid in Stripe, and then the invoices’ payment statuses will be synchronized back to Nue.  

CANCEL INVOICES When active invoices are canceled in Nue, they will be voided in Stripe, and vice versa.

REFUND Finance ops users can refund customers in Stripe, which will in turn generate a credit memo or a negative invoice in Nue. 

LATE FEES Finance ops users can create Late Fees as debit memos for overdue invoices in Nue.  The late fees will be transfered to Stripe and appear on the invoices sent to the customers.

Pay Invoices

User Scenario: Customer Smart Revenue Inc. purchases a 12-month subscription of VROOM CLOUD STORAGE with a total of $1200, billed monthly.  The first invoice is created on 05/16, with a payment term of 30 days.  Customer receives the invoice via Stripe, and pays in Stripe.

As usual, a sales user creates a containing the VROOM CLOUD STORAGE product line that finalizes into an order.  Once the order is activated, the first invoice of this order is generated, and available to view in the Lifecycle Manager. 

• To generate the first invoice automatically upon order activation, enable billing setting Automatically generate first invoice when an order is activated. 
• If this setting is not enabled, you can run an on-demand Billing Schedule to generate invoices.  

You can follow the steps below to access and activate the invoices: 

• Open the account, and click Manage Customer Lifecycle. 
• Click on the Activate icon to activate the invoice.

Once the invoice is activated, it will be transferred to Stripe for payments.  When you click 'Search' to refresh the invoice list, you can see the Payment Status and External Invoice ID both populated with the following data: 

• Payment Status: Indicates the status of the payment.  Available values include: Transferred, Paid, Error.
  • When the Payment Status is Error, you can see the payment error message details in the Payment Details column.
• External Invoice ID: Stores the corresponding Invoice ID in Stripe.

You can also click on the 'View' icon in the Actions column to see the invoice details in Salesforce.

In the Invoice Detail page, you can see the Hosted Payment Page URL.

The Stripe hosted payment page is used to create a pre-built, hosted payment page that can be used to collect payments online. When a customer clicks on the link, they will be taken to the Stripe hosted payment page. The page will display the amount of the purchase and the payment methods that are available. The customer can then enter their payment information and complete the purchase.

You can configure flows in Salesforce to embed this hosted payment URL in an email sent to the customer, or configure Stripe to automatically send email to the customer with the hosted payment page embedded.Open payment page via the payment URL, you will see the payment detail as below, you are able to select one of the available payment methods, the payment methods will be enabled when create the invoice according to Stripe default invoice settings. 

Specify Payment Method

you can also enable a specific payment method (e.g. ACH, Credit Card) within the Order creation process -> Payment Method Setting. Once the associated invoice billed and transferred to Stripe, customer could pay the invoice via the specified payment method. When an invoice generated from multiple orders, all specifiied payment methods will be enabled in Stripe payment page.

Stripe Account, Order Primary Contact and Billing/Shipping Address

When an invoice is transferred to Stripe for payments, Nue first checks if the customer already exists.  If not, Nue creates a new customer in Stripe with the information of the account in Nue.  Nue sets the Email address,  billing address and shipping address of the newly created account in Stripe as the Email address of the Order Primary Contact field, Billing Address  and Shipping Address in the Nue account by default. Also, you are able to manually mapping Salesforce Account fields to Stripe Customer (via API), which means the Salesforce account information will be automatically transferred to Stripe Customer.

It is important to set the Order Primary Contact field in the Account object to a contact having a valid Email address.  This email address is used for Stripe to send emails to the customer.

Payments via Stripe

Once the customer receives the invoice with the hosted payment URL and pays the invoice, the following occurs: 

• The Invoice Status is set to Paid, in both Stripe and Nue.
• The Invoice Balance is set to 0 in Nue.
• A Payment Application record is created under the Invoice in Nue, containing the payment details.

Applying Credit Balance

If there is credit balance in customer's acocunt, the next invoice will show the credit balance being applied, and in Nue, a Payment Application(Credit Type) was created associated with the invoice and offset the invoice balance.

Recurring Billing and Payments

With Nue, you can set up a recurring billing schedule to bill customers on a regular basis.  For example, if a customer has a 12-month subscription, and is billed on a monthly basis, Nue will generate 12 invoices each month.  Nue will transfer these monthly invoices to Stripe for collection whenever they are activated.  

Recurring Billing Schedule

You can create a Billing Schedule that generates invoices for recurring products and automatically activate generated invoices on a daily, monthly basis or even with a custom schedule.  

Once the Billing Schedule is active, the invoices will be generated and activated on a scheduled basis.  They will be transferred to Stripe at the same time.

Automatic Charge

In this section, you can choose your preferred Stripe collection method. If you select Automatically Charge or Smart Collection, Stripe will automatically charge the invoiced amount using the ACH or credit card information saved on file for your customers. Once the payment is successfully processed, the invoice status will update to “Paid,” and the outstanding balance will be set to zero.

Issue Credits

User Scenario: Customer Smart Revenue reduces 50% storage units for VROOM CLOUD STORAGE in the mid-term.  Company wants to issue a credit memo towards furture payments.

To implement this user scenario, first, you can create a change quote/order to reduce 50% of the storage unit of the subscription, and activate this order. 

Then you can run a billing schedule, which will generate a credit memo with prorated amounts for this change order.  If you do not enable Credit Memos, a negative invoice will be generated instead.

You can view the Credit Memos in the Lifecycle Manager.  The Payment Status shows whether it has been transferred successfully to Stripe. 

After the credit memo is transferred to Stripe, it will be added as Credit Balance of the coresponding customer in Stripe.

• Login to Stripe and navigate to Customers.  Open the customer and see the credit balance automatically transferred.
• This credit balance will be automatically applied to pay for future invoices of the same customer. 

Issue Credit Note

You can also issue a credit note within the Stripe invoice.

You can follow the steps below to issue a credit note to an invoice in Stripe: 

1. Access the Stripe Dashboard: Log in to your Stripe account at https://dashboard.stripe.com/.

2. Locate the invoice: Navigate to the "Invoice" section in Customer detail, search the invoice number on the top search bar or find it out in invoice list.

3. Issue a credit note: Navigate to the "credit note" section in Invoice detail.

4. entry reason, credit amount and then click issue credit note

After that, a Payment Application(Credit Type) was created associated with the invoice and offset the invoice balance.

Receive Non-Electronic Payments

Often times, companies want to process non-electronic payments, for example: 

• When your customer is located in a country where electronic payments are not widely accepted. There are many countries where electronic payments are not as common. In these cases, you may need to accept cash or check payments.
• When your customer is making a large purchase. Some customers may prefer to pay for large purchases with cash or check. This is especially true if they are concerned about fraud or identity theft.

If a non-electronic payment is received, Finance Ops can login to Stripe, open the invoice, and click More > Change Invoice Status, and set the status to Paid with some additional internal notes, e.g., Check Number. 

Once the invoice status is updated in Stripe, Nue will automatically do the following to the corresponding invoice record in Nue: 

• Change the payment status to Paid; 
• Set the invoice balance to $0; 
• Create a payment application record.

Cancel Invoices and Credit Memos

Users can cancel invoices and credit memos both in Nue and Nue on Salesforce, provided that sufficient permissions are granted.

Cancel Invoices

When an active invoice is canceled in Salesforce or Nue, its corresponding invoice is Voided in Stripe.

When an unpaid invoice is canceled in Stripe, its corresponding invoice is Canceled in Nue and Salesforce.

Occasionally, you might create an incorrect order, which generates an invalid invoice and gets paid via Stripe automatically if the customer has a default credit card on file, or has credits in the credit balance.  In this case, the invoice's Payment Status becomes PAID, in both Stripe and Nue.  You can cancel a Paid invoice, which will trigger the following operations: 

• Process credit-card or othe electronic payment refund in Stripe
• Create credit-back type credit-memo / negative invoice and negative Payment Applications associated to the credit-memo/negative invoice (as well as Nue on Salesforce); 
• Cancel all related debit memos associated to the invoice in Nue (as well as Nue on Salesforce); 
• Change the invoice status from Active to Canceled
• Change the invoice payment status from Paid to Refunded

You can also cancel a Partially Refunded or Refunded invoice, which will trigger the following operations:

- Use Case 1: Cancel a Refunded invoice

• Cancel all related debit memos associated to the invoice in Nue (as well as Nue on Salesforce); 
• Change the invoice status from Active to Canceled

- Use Case 2: Cancel a Partially Refunded invoice

• Process credit-card or othe electronic payment refund in Stripe
• Create credit-back type credit-memo / negative invoice and negative Payment Applications associated to the credit-memo/negative invoice (as well as Nue on Salesforce); 
• Change the invoice status from Active to Canceled
• Change the invoice payment status from Partially Refunded to Refunded

To cancel an order, sometimes you'll also need to cancel the associated credit-back credit memo / negative invoice which was generated during refunding process. You need to cancel the orginal refunded invoice first and then cancel the credit back credit memo / negative invoice. 

Cancel Credit Memos

When a credit memo is canceled in Salesforce or Nue, the Credit Balance of the customer in Stripe is reduced by the same amount.

Process Refund

When finance ops users process refund of a particular payment issued to an invoice transfered from Nue, Nue will create a credit memo (or a negative invoice, if Credit Memo feature is not enabled) in Nue to offset the original invoice.  

The following diagram illustrates the transactions and their relationships in the refund process. 

Issue Refund in Stripe

You can follow the steps below to issue a refund to an invoice in Stripe: 

1. Access the Stripe Dashboard: Log in to your Stripe account at https://dashboard.stripe.com/.

2. Locate the Payment: Navigate to the "Payments" section or use the search functionality to find the specific payment for which you want to issue a refund.

3. Open the Payment Details: Click on the payment to open its details.

4. Initiate a Refund: Within the payment details, locate the "Refund" button or link, usually located near the transaction information.

5. Specify the Refund Amount: Enter the amount you wish to refund to the customer. It can be a full or partial refund.

6. Choose Refund Method: Select the refund method based on your preferences and the original payment method used by the customer. Stripe allows you to refund directly to the customer's card, store the refund as a credit on their account, or issue an off-session refund.

7. Add Refund Reason (Optional): You may have the option to include a reason for the refund, which can be helpful for record-keeping purposes.

8. Confirm and Process Refund: Double-check the refund details and click the "Refund" or "Submit" button to process the refund. Stripe will initiate the refund process and handle the necessary transactions to return the funds to the customer.

9. Confirmation and Notifications: Once the refund is processed, you will receive a confirmation in the Stripe Dashboard, and Stripe will automatically notify the customer via email or other preferred communication channels, depending on your account settings.

Access Credit Memo in Nue

After a refund is issued, you can access the credit memo generated in Nue.

• Login to Nue on Salesforce
• Open the account details, and click Manage Customer Lifecycle to navigate to the Lifecycle Manager
• Click 'Credit Memo'.  
• You can find the credit memo created with Payment Status Credit Back.

Similar to payment operations, refund operations create Payment Application records with Refund record type associated to the credit memo.  You can click the 'View' icon to open the credit memo details page to see the payment application records.

The Payment Status of the original invoice will be changed to Refunded.  

Partial Refund

Finance ops users can process partial refund as well.  For each partial refund issued from Stripe, a new credit memo record containing credit memo items will be created and linked to the original invoice.  The payment status of the original invoice will be changed to Partially Refunded.  

Process Late Fee

When an invoice is overdue, finance ops users can add a late fee in Nue as a debit memo.  In Late Fee - a Debit Memo Use Case, you can learn about how to create and manage Late Fees as credit memos in Nue, and how to get them collected in Stripe.  In summary - 

• For each overdue invoice in Nue, you can apply a late fee as a debit memo.  The debit memo record will be associated with the invoice.  
• The debit memo record will be transferred to Stripe.  In Stripe, the original invoice will be voided, and a new invoice will be created containing the original invoice items, as well as the late fee.
• Once the user pays for the invoice, 2 credit memo items will be created back in Nue, one associated to the original invoice, the other one associated to the debit memo.  Payment application records will be created accordingly as well.

Process Zero Amount Invoice

Sometimes, customers may not need to pay for the services they have purchased because the services are already included in a bundle that has been paid or the usage of a service doesn't exceed the limit. In such cases, Nue will still generate an invoice with the amount $0 for that billing period. However, there is no need to send such invoices to the customers. Administrators can enable the below setting to prevent the $0 amount invoices from being sent to Stripe. This ensures that customers do not receive any unnecessary invoices that do not require payment.

• Go to Nue System Settings -> Revenue Manager -> Invoices or search for 'Do not send invoices to collection systems with $0 total amount'

If the above setting is enabled and an invoice with a $0 amount is activated, it won't be sent to Stripe automatically. However, the revops manager can still choose to send it to Stripe manually if necessary.

Manage Field Mapping Between Nue and Stripe

In this section, we'll show you how standand fields are mapped between Nue and Stripe, and how to create custom metadata mapping, for Customer, Order, and Invoice.  

Customer

Standard Field Mapping

The following table shows the standard field mapping between Nue and Stripe for the Customer object.  For a full list of Customer fields, please check out this Stripe documentation.  

POST https://api.nue.io/stripe/metadata-mapping 

{
  "metadataMappingList": [
    {
      "sourceObject": "Customer",
      "sourceField": "Custom_Email__c",
      "sourceValue": null,
      "targetObject": "Customer",
      "targetField": "email"
    }
  ]
}

Invoice 

Standard Field Mapping

The following table shows the standard field mapping for the Invoice object between Nue and Stripe. 

The following table shows the standard field mapping for the Invoice Item object between Nue and Stripe

Custom Field Mapping

In Nue, you have the capability to map Salesforce's Account, Order, and Invoice fields to Stripe invoice fields using the same API:

POST https://api.nue.io/stripe/metadata-mapping

In the following example, users would like to add a custom field 'PO Number' to the Invoice template.  The "PO Number" field is a custom field created on Order object.  To achieve this, please follow the steps below: 

• Login to Salesforce and navigate to Settings → Object Manager.  
• Create a custom field on Order object inamed 'PO Number' (PONumber__c) by following these steps.  
• Call the following metadata-API to create 2 custom fields mapping in Stripe: 

POST https://api.nue.io/stripe/metadata-mapping

{
    "metadataMappingList": [
        {
            "sourceValue": "PO number",
            "targetObject": "Invoice",
            "targetField": "custom_fields[0].name"
        },
        {
            "sourceObject": "Order",
            "sourceField": "PONumber__c",
            "sourceValue": null,
            "targetObject": "Invoice",
            "targetField": "custom_fields[0].value"
        }
    ]
}

curl --location 'https://api.nue.io/stripe/metadata-mapping' \
--header 'nue-api-key: {nue-api-key}'

Troubleshoot Payment Transfer Status in Transaction Hub

At times, upon activating an invoice, it may encounter issues in its transfer to Stripe. In such instances, you have the option to use the Transaction Hub to review any encountered errors or initiate a re-issuance of the transfer to Stripe.

Please follow the steps below to access the Transaction Hub for invoices, and re-issue a transfer to Stripe: 

• Login to Nue App, and navigate to Revenue Manager → Invoices
• Locate the 'Transaction Hub' column, as shown in the screenshot below.  This column shows the transfer statuses of invoices to corresponding systems, such as Salesforce, Stripe, Quickbooks, Avalara, etc.  If the icon appears greyed out, it indicates that the transaction has not yet been successfully transferred to the target system.

• To check the transfer status, simply click on the icon. If the icon displays a "Transferred" status, you'll be presented with the Nue ID, External ID, and Last Transferred Time. However, if the icon indicates a "Not Transferred" status, both the current transfer status and any associated error message will be shown. In such cases, you have the option to manually re-issue a transfer to Stripe by clicking the 'Transfer' icon.

,