Trigger Stripe Payments in NetSuite

Programmatically trigger payments in NetSuite on orders or invoices using payment or customer tokens from Stripe. This workflow enables you to develop unique payment flows within NetSuite, while leaving the complexity of processing payments and handling payment failures to SuiteSync.

In most cases, SuiteSync's automatic payment system or eCommerce workflow fit common use-cases. However, if you have a unique payment flow, the triggered payments system can help provide the tools to give you more control and customization around processing payments using Stripe, within NetSuite.

Here are some cases where this is helpful:

  • You want to control the exact minute a charge is run in Stripe, as opposed to waiting for the daily automatic payments run.
  • Your customers have many different payment methods (multiple cards, bank accounts, etc) and you have custom business logic which determines which payment method is used.
  • You have sales orders in NetSuite and want to create payments in Stripe and NetSuite customer deposits automatically.

Here's an overview of how this works:

  1. A script, CSV import, API call, workflow, etc adds a Stripe customer or payment source ID to a invoice or sales order.
  2. The customer ID or payment token could be pulled from an external system that you have access to, or directly from NetSuite. It does not matter where the Stripe customer or payment token is sourced from.
  3. SuiteSync monitors invoice and sales orders. If it detects a invoice or sales order with a Stripe customer or payment token, a payment attempt is made against the default card of the customer, or the payment token that was specified.
  4. If the payment attempt succeeds, a customer payment or customer deposit is created against the invoice or sales order.
  5. If the payment fails, the failure is noted on the invoice or sales order. You can programmatically respond to payment failures using SuiteScript or a NetSuite workflow.

Creating a Payment with a Stripe Customer ID

You can specify a Stripe Customer ID on the "Stripe Transaction ID" field on a NetSuite invoice. If an invoice has a Stripe customer ID in the "Stripe Transaction ID" field, SuiteSync attempts to create a payment using the Stripe customer's default payment method. Payment failures are reported on the invoice in the same way as an automatic payment failure.

Immediately when a customer ID is added to the invoice, SuiteSync pulls the default card for the customer and attempts to charge the card for the amount due on the invoice. If you need to re-run a payment from a customer reference (if a previous payment attempt failed, for instance), just update the "Stripe Transaction ID" field with a customer reference and a payment will be re-attempted.

The Stripe Customer ID starts with cus_ and is specified on the external ID field of the associated customer. If you want to trigger a payment within a NetSuite script or workflow, the external ID of the customer associated with an invoice can be copied to the "Stripe Transaction ID" field.

Here's an example of how to copy the Stripe Customer ID to the "Stripe Transaction ID" field:

var invoiceInternalID = 123;

var invoiceCustomerID = nlapiLookupField('invoice', invoiceInternalID, 'entity')
var stripeCustomerID = nlapiLookupField('customer', invoiceCustomerID, 'externalid');

nlapiSubmitField('invoice', invoiceInternalID, 'custbody_suitesync_authorization_code', stripeCustomerID);

View Full Script Example

You can also use this method with SalesOrders. If you specify a customer or payment source ID on the SalesOrder "Stripe Transaction ID" field SuiteSync generates a customer deposit for the SalesOrder. Note that a deposit is only created if the order is a "Pending Billing" status.

Creating a Payment with a Stripe Payment Source ID

Using a payment source ID (i.e. a card_, ba_, etc reference) as a way to trigger payment creation can be a great way to control both the timing and the exact payment method that is used for automatic payments. Simply add a payment source ID to the "Stripe Transaction ID" field in NetSuite (custbody_suitesync_authorization_code) and SuiteSync will attempt to charge that payment source.

Here are some additional technical details about how this works:

  • If an unchargeable payment source is the Stripe customer default source (i.e. an unverified bank), an error message indicating that the charge failed because of this reason will be issued. In other words, the charge will still be attempted and this case will not silently fail.
  • Note that the Stripe customer must be "linked" to the NetSuite customer for this functionality to work. In other words, a Stripe customer with the charge or payment source ID must have already been "connected" to the NetSuite customer.
  • If you are planning on linking multiple Stripe customers to a single NetSuite customer, you cannot use this functionality. Triggered payments using a payment source only works when a one-to-one mapping between Stripe and NetSuite customers is maintained.
  • If the payment source specified is invalid (i.e. source ID cannot be found on the customer) a note is added to the invoice and the invalid source ID is removed.
  • If a Stripe customer is not linked to the NetSuite customer, the integration does not report an error and the token ID is not removed. The reason for this is it is common to have multiple Stripe accounts connected to NetSuite. In this case, one SuiteSync/Stripe account may have a valid customer link but another may not.
  • If the payment source fails to charge, an error message containing the customer and source ID which failed is added to the NetSuite invoice memo field. Note that if the payment source is the default source for the customer, then the source ID is not added.
  • The description of the Stripe charge created by a payment source ID starts with "Triggered Payment for NetSuite Invoice". This description is passed over to the customer payment in NetSuite on the memo field.
  • If creating a charge with the specified payment source fails, any modification to the invoice causes another payment attempt to be made. For instance, if you update the "Stripe Transaction ID" field to a different payment source value, this will trigger another payment attempt to be made with the new payment source value.