Stripe Integration Setup

this document outlines the steps needed to configure stripe and nue in preparation for any of the following stripe integration scenarios collect payments via stripe invoicing docid nbzb70twgpswffpy5hz collect payments via nue payment links docid 9 rcffm0h ptxhwub01u permissions required please enable the following permissions in the user role integrations manage stripe integration collections view payment application manage payment application process payment process refund apply credit memos unapply credit memos writeoff invoices setup stripe connection in {{nueapp}} , navigate to system settings search for stripe integration enter publishable key and secret key you can get publishable key and secret key in stripe dashboard please note that stripe operates in both live mode and test mode, each with its own set of api keys in live mode, the secret key cannot be viewed directly for security reasons however, you can rotate the secret key and securely store the new key locally for integration purposes click test to verify the connection if the test is successful, click activate once activated, an active indicator will confirm that the connection is live and functioning properly stripe connection successfully set up configure collection preference under "collection preferences", select the collection preference according to your stripe integration use case use stripe invoicing and stripe payments for payment collection for this payment workflow, which means invoices are generated and managed through stripe’s native invoicing system allowing for features like hosted invoice pages, built in tax handling, and flexible payment reminders after invoices are activated in nue, we send invoices physically to stripe invoicing, so that customers can use the stripe dashboard to manage payments, refunds, credits, dunning, etc this is different from using stripe payments , which initiates one off payment transactions directly via api without generating an invoice by using stripe invoicing, nue provides a more complete billing experience that supports recurring billing, dunning, and payment reconciliation — all while maintaining a clear audit trail and customer facing invoice history stripe invoicing charges customers 0 4% per transaction, in addition to the stripe payments charges they have to pay configure collection method you can choose to enable any of the following collection methods for stripe invoicing automatically charge this option would automatically charge the end customer’s payment method without human intervention if possible if the end customer’s selected payment method(s) cannot be charged automatically, or there is no credit card on file, it will fall back to “send email” send email this option would always send an email with the invoice attached as long as the customer's email is available smart collection this option would be using an informed approach to collect payments from end customers if any of the selected payment method(s) only supports send email due to stripe limitation(e g , bank transfer), collect the payment by email otherwise, if the end customer has the selected payment method on file (e g , credit card), collect the payment by charging the payment method automatically; otherwise, collect the payment by email with the invoice attached use nue collections and stripe payments for payment collection for this payment workflow, stripe provides a secure and seamless checkout experience, while nue manages the end to end billing and collections process nue handles recurring billing logic — including subscription terms, billing cycles, renewals, and revenue reporting — ensuring full control and flexibility this approach combines stripe’s reliable payment processing with nue’s subscription and revenue automation, delivering a branded and user friendly experience all financial operations such as payments, refunds, credit memos, debit memos, and dunning must be executed within nue to maintain data integrity and consistency configure email notifications you can choose to enable any of the following email notifications ✅ invoice notification sends an invoice to the customer’s contact with an embedded payment link using the invoicepaymentlinkemailtemplate email template ✅ payment receipt sends a payment receipt to the customer’s contact using the invoicepaymentlinkemailtemplate email template ✅ failed payment notification notifies the customer’s contact when a payment fails, using the failedpaymenttemplate email template ✅ subscription level failed payment notification sends a failed payment alert specific to a subscription using the subscriptionfailedpaymenttemplate email template users can customize the email content by editing the classic email templates in salesforce or by creating new templates once created, these custom templates can be selected and assigned to the appropriate notification options to configure email templates in the connected salesforce org, please follow the steps below 1\ login to salesforce and go to setup 2\ navigate to classic email templates in the quick find box, type email templates click classic email templates 3 select the “nue email templates” folder, then click on the specific template you want to edit the following video provides a step by step guide on how to set up nue payment links powered by stripe integration health monitor when stripe is enabled, transaction status updates are delivered to nue through a dedicated webhook endpoint if a webhook delivery fails, system administrators can easily view the failure status and retry the webhook with a single click health monitor jpg map existing stripe customers with salesforce/nue accounts this step is necessary only if you have an existing stripe account and want to associate the customers in stripe with corresponding accounts in salesforce when a new invoice is activated, nue checks if the customer already exists in stripe if not, it creates a new customer record in stripe this mapping is used to ensure accurate linkage between salesforce accounts / nue customers and stripe customers here’s an enhanced and clearer version of your instructions to associate existing stripe customers with salesforce accounts in nue, you’ll need to prepare a customer mapping file this process includes exporting data from both salesforce and stripe, then creating a structured mapping file in csv format using nue’s template 1\ export salesforce accounts use dataloader io, a salesforce supported tool, to extract account data log in to salesforce and navigate to setup in the quick find box, search for dataloader io and click to open it authenticate with your salesforce credentials click new export task and select the account object choose the fields account id and account name click save & run , then download the export file when the task completes 2\ export stripe customers use the stripe dashboard to export existing customer records log in to your stripe dashboard navigate to customers click the export button in the export popup set data range to all select fields customer id and customer name click export download the exported csv file 3\ create mapping file in nue format log in to nue and navigate to system settings search for stripe integration settings click import mapping , then click download template to get the required csv format 4\ populate and upload the mapping file open the downloaded template in excel or any csv editor match nue account ids with stripe customer ids using the data from your exports fill out the mapping template accordingly save the file as a csv when your mapping file is ready, go back to stripe integration settings in nue and upload it via the import mapping function this ensures that nue recognizes and links the correct stripe customers to their nue/salesforce accounts without creating duplicates during invoice synchronization manage field mapping between nue and stripe nue’s stripe integration supports custom field mapping between nue and stripe for both customer and invoice objects if you are using stripe invoicing , and have custom fields, you should configure field mappings for both customer and invoice objects this ensures that all relevant data is included when invoices are transferred to stripe if you are using stripe payments (without stripe invoicing), customer field mappings need to be configured in this setup, invoices remain in nue and are not sent to stripe, so invoice field mappings are not applicable map customer fields 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 https //docs stripe com/api/customers/object nue field stripe field name description name name tax exempt taxexempt email emal phone phone billing country address country billing state address state billing city address city billing street address line1 biling postal code address postal code shipping country shipping address country shipping state shipping address state shipping city shipping address city shipping street shipping address line1 shipping postal code shipping address postal code order primary contact → name shipping name order primary contact → phone shipping phone note the field in nue must also have a mapping in salesforce this is to ensure that salesforce, nue and stripe will be sychronized end to end to learn more about salesforce and nue custom field mapping, please refer to manage custom fields docid\ tguor j2gqmocfcc bu3m the following image shows an example of fields on stripe's customer object if you prefer to transfer custom data from nue's customer object instead of using nue's default mappings, you can override the mapping by creating a new metadata mapping record using this api create metadata mappings docid\ yhpjywdkgqdibfevr8bpm for instance, you can map nue's customer custom email c to stripe's customer email post https //api nue io/stripe/metadata mapping { "metadatamappinglist" \[ { "sourceobject" "customer", "sourcefield" "custom email c", "sourcevalue" null, "targetobject" "customer", "targetfield" "email" } ] } to retrieve a list of supported target fields, use list target object fields docid 3yhuuzo5swahhsxd9p48 api map invoice fields docid 39907ab5a4ec3e0a1b644d44ebb18548b1420f20 nue supports mapping custom fields from customer, order, or invoice objects to invoice metadata in stripe when an invoice is created, billed, or activated, the specified custom field values are automatically populated into the corresponding stripe metadata fields, ensuring consistent metadata synchronization throughout the invoice lifecycle standard field mapping the following table shows the standard field mapping for the invoice object between nue and stripe n ue invoice fields stripe invoice fields currency code invoice currency due date invoice duedate order → payment methods invoice payment settings ​payment ​method ​types the following table shows the standard field mapping for the invoice item object between nue and stripe nue invoice item fields stripe invoice item fields transaction quantity invoiceitem quantity tax amount invoiceitem taxamount tax code invoiceitem taxcode tax mode invoiceitem taxbehavior start date invoiceitem start end date invoiceitem end custom field mapping you can also map custom fields from nue objects including account, order, and invoice to stripe invoice fields, including both standard and custom fields this is achieved using the following api for example, if you want to display a custom “po number” field on the stripe invoice template, and this field exists on the salesforce order object, follow these steps follow steps in manage custom fields docid\ tguor j2gqmocfcc bu3m to create a custom field named po number (api name ponumber c ) on the order object use the create metadata mappings docid\ yhpjywdkgqdibfevr8bpm api to define the mapping between the custom field in salesforce and the appropriate field in stripe this setup helps to ensure that the “po number” from the order is automatically included on the stripe invoice, maintaining consistency across systems additional notes before creating field mappings via api, make sure to check the following verify custom field metadata exists in nue by using get object definition docid\ p3abdzb w8azmakiabajy api ensure the mapping doesn’t already exist using list all metadata mappings docid\ lomf2fclhocxmedqfgrql api these checks help prevent errors and ensure a clean, consistent mapping configuration when submitting your mapping configurations, it’s best practice to send a single request that includes all desired mappings, rather than making multiple individual requests this ensures consistency and reduces the chance of conflicts or incomplete mappings the following shows a curl example of listing all metadata mappings curl location 'https //api nue io/stripe/metadata mapping' \\ \ header 'nue api key {nue api key}' 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" }, { "sourceobject" "invoice", "sourcefield" "custom synced", "sourcevalue" null, "targetobject" "payment", "targetfield" "metadata synced" } ] } variable description sourceobject the api name of the source object in nue available values include customer, order, invoice sourcefield the api name of the source field in nue the following values are allowed api name of any field on the sourceobject; a field on a related object with lookup relationship, in the form of lookuprelationshipname fieldname , for example, orderprimarycontact phone sourcevalue if sourcevalue is specified, please do not specify values for sourceobject and sourcefield a constant value, which can be used to display the custom field name in the invoice pdf generated by stripe for example, in 'po number' targetobject the api name of the target object in stripe available values include customer, invoice, payment targetfield the api name of the target field in stripe