Troubleshoot the connector

Use this guide to troubleshoot issues with the Stripe Connector for NetSuite, including identifying and resolving errors when syncing records or loading payment pages.

For further assistance, contact your implementation partner or Stripe support.

Sync records from Stripe to NetSuite

The following table describes data errors you might encounter when syncing records from Stripe to NetSuite. You can view all errors in the connector app’s sync records window.

invoice: {
   "department_id": 2
}

Sync payouts to NetSuite

The following errors can occur when syncing payouts from Stripe to NetSuite. You can view payout sync errors on the payout details page in the connector app.

Bank deposit account missing

The bank_deposit_account_missing error code indicates that the connector couldn’t fetch the NetSuite bank deposit account. This happens when the bank account is deleted in NetSuite, the internal ID in connector settings is incorrect, or the Stripe Limited Access role lacks permission to view the account.

To resolve this issue:

1. Log in to your NetSuite account.
2. Navigate to Lists > Accounting > Accounts.
3. Verify the bank deposit account exists and note its internal ID.
4. Check that the Stripe Limited Access role has permission to view the account.
5. In the Stripe Connector for NetSuite app, go to App settings.
6. Navigate to the Account Mapping tab and update the bank deposit account mapping with the correct internal ID.

Unsynced transactions found

The inventorying_waiting_on_child_records error code indicates that one or more transactions in the payout haven’t synced to NetSuite yet. The payout deposit can’t be created until all associated transactions sync successfully. This is a waiting state, not necessarily an error.

To resolve this issue:

1. In the connector app, navigate to the payout details page.
2. Review the list of transactions with sync issues.
3. For each unsynced transaction, check its sync status and error message.
4. Resolve any errors preventing the sync (such as missing customer or account mapping issues).
5. Retry the sync if needed. After all transactions sync, the payout deposit automatically proceeds.

NetSuite account mapping not set

The missing_netsuite_account_mapping error code indicates that a required NetSuite account mapping isn’t configured. The error message specifies which account type is missing (for example, income, fee, refund, or adjustment accounts).

To resolve this issue:

1. Review the specific error message to identify which account mapping is missing.
2. In the connector app, go to App settings > Accounts mapping.
3. Configure the required account mapping and save your changes.
4. Retry the payout sync.

NetSuite bank deposit account not set

The payout_currency_account_missing indicates that no bank deposit account is configured for this payout’s currency. Each currency you receive payouts in (USD, EUR, GBP, and so on) requires a corresponding bank deposit account.

To resolve this issue:

1. In the connector app, go to App settings > Accounts mapping.
2. Find the Bank deposit accounts section.
3. Add a bank deposit account mapping for the payout’s currency.
4. Save your changes and retry the payout sync.

NetSuite subsidiary unavailable

The subsidary_not_found_likely_permission_issue error code indicates that the connector can’t access the NetSuite subsidiary. This is most commonly caused by the Stripe Limited Access role lacking permission to view subsidiaries, the subsidiary record being deleted or inactivated, or no subsidiaries being configured on the bank deposit account.

To resolve this issue:

1. Log in to NetSuite as an administrator and navigate to Setup > Users/Roles > Manage Roles.
2. Edit the Stripe Limited Access role.
3. Under the Subsidiaries tab, make sure the role has access to all required subsidiaries.
4. Verify the Lists > Subsidiaries permission is set to at least View.
5. Save the role changes and retry the payout sync.

NetSuite subsidiary search failed

The subsidary_search_failed error code indicates that the connector encountered an error while searching for child subsidiaries in NetSuite. This typically indicates a network timeout, rate limiting, or that the Stripe Limited Access role lacks permission to perform subsidiary searches.

To resolve this issue:

1. Wait a few minutes and retry the payout sync.
2. If the error persists, log in to NetSuite as an administrator and navigate to Setup > Users/Roles > Manage Roles.
3. Verify the Stripe Limited Access role has Lists > Subsidiaries permission set to Full and Reports > Search permission enabled.
4. Check that subsidiaries are properly configured on the bank deposit account.
5. Contact Stripe support if the issue continues.

NetSuite undeposited funds account unavailable

The undep_funds_account_fetch_error error code indicates that the connector couldn’t fetch the undeposited funds account from NetSuite. This can happen due to network issues, or permission issues accessing the account.

To resolve this issue:

1. Log in to NetSuite and navigate to Lists > Accounting > Accounts.
2. Search for your undeposited funds account and verify it exists and is active.
3. Check that the Stripe Limited Access role has permission to view the account.
4. In the connector app, go to App settings > Accounts mapping and update the undeposited funds account mapping if needed.
5. Retry the payout sync.

NetSuite undeposited funds account not set

The undep_funds_account_not_found error code indicates that no undeposited funds account is configured in your connector settings, or the configured account mapping is empty. This account is required for processing payout deposits.

To resolve this issue:

1. In the connector app, go to App settings > Accounts mapping.
2. Find the Undeposited Funds Account setting.
3. Select the appropriate undeposited funds account from your NetSuite chart of accounts.
4. Save your changes and retry the payout sync.

Temporary NetSuite error

The transient_netsuite_error error code indicates that a temporary error occurred while communicating with NetSuite, such as a network timeout, rate limiting, or temporary unavailability. The connector automatically retries these operations.

To resolve this issue:

No action required. The connector automatically retries with exponential backoff. If the error persists for more than 24 hours, contact Stripe support.

Invalid transactions found

The validating_waiting_on_child_records error code indicates that one or more transactions in the payout failed validation checks. The payout deposit can’t be created until you resolve all validation errors. This is a waiting state while you fix the underlying transaction issues.

To resolve this issue:

1. In the connector app, navigate to the payout details page.
2. Review the list of transactions with validation errors.
3. Each transaction shows its specific validation error (for example, amount mismatch, already deposited, deleted record, or invalid subsidiary).
4. Resolve each validation error following the guidance in the Payout transaction validation section.
5. After you resolve all validation errors, the payout deposit automatically proceeds.

Payout transaction validation

The following validation errors can occur for individual transactions within a payout. Each transaction in a payout is validated before the deposit can be created. You can view these errors on the payout details page in the connector app.

Already deposited

The already_deposited error code indicates that the NetSuite record (Cash Sale, Customer Payment, and so on) has a status of Deposited, meaning it’s already included in a manually created NetSuite bank deposit, or the payment record itself has been updated to a different GL account than Undeposited Funds. NetSuite doesn’t allow the same record to be deposited twice.

To resolve this issue:

1. Log in to your NetSuite account.
2. Navigate to one of the already_deposited customer payments.
3. Verify that the payment’s account is set to Undeposited Funds.
   • If yes, check the Deposit ID field to find the bank deposit that it has been manually included in.
     • Navigate to this bank deposit and remove this transaction from the bank deposit.
   • If no, update the account on the customer payment to Undeposited Funds.
4. Retry the payout sync.
5. If the record was correctly deposited in a previous payout:
   • The Stripe transaction might need to be excluded from payout syncing.
   • Contact Stripe support for assistance reconciling.

NetSuite record deleted

The deleted_netsuite_record error code indicates that the NetSuite record linked to this Stripe transaction is deleted, inactivated, or can’t be found. This can happen if someone manually deleted the record, a script or workflow deleted it, the record is in a different subsidiary, or the record is voided.

To resolve this issue:

1. Log in to NetSuite and check if the record is intentionally deleted by reviewing System Notes or audit trails.
2. If the deletion is unintentional, manually recreate the record in NetSuite with the correct amount and details.
3. Contact Stripe support to relink the Stripe transaction to the correct NetSuite record.
4. Retry the payout sync.

NetSuite record already linked to another transaction

The duplicate_netsuite_record_in_payout error code indicates that the same NetSuite record internal ID is linked to multiple Stripe transactions within this payout. Each Stripe transaction must be linked to a unique NetSuite record. This typically happens when a record is manually linked incorrectly or duplicate syncs create duplicate associations. The error message shows which Stripe resource ID conflicts and the shared NetSuite record ID.

To resolve this issue:

1. Review the error message to identify the conflicting Stripe transaction and shared NetSuite record ID.
2. Determine which Stripe transaction should remain linked to the existing NetSuite record.
3. For the other transaction(s):
   • Create new NetSuite records in NetSuite matching the Stripe transaction details.
4. Use the manual override tool in the SCN app drawer to link the transaction to the correct NetSuite record.
5. If this doesn’t work, contact Stripe support to update the record linkages.
6. Retry the payout sync.

Invalid subsidiary

The invalid_subsidiary error code indicates that the subsidiary on the NetSuite record doesn’t match the valid subsidiaries for the bank deposit account. This can happen with multi-subsidiary NetSuite accounts when the record is created under a different subsidiary, the bank deposit account’s subsidiary configuration changes, or a workflow modifies the record’s subsidiary.

To resolve this issue:

1. Log in to NetSuite and find the NetSuite record linked to this transaction.
2. Check the Subsidiary field on the record.
3. Compare it to the subsidiaries configured on your bank deposit account.
4. Either edit the NetSuite record to use a valid subsidiary, or update the bank deposit account to include this subsidiary.
5. Changing subsidiaries on records might have accounting implications. Consult your accounting team.
6. Retry the payout sync.

Undeposited funds account mismatch

The undep_funds_account_mismatch error code indicates the undeposited funds account on the NetSuite record doesn’t match the account configured in your connector settings. All records in a payout deposit must post to the same undeposited funds account for the deposit to balance correctly.

To resolve this issue:

1. Log in to NetSuite and find the NetSuite record linked to this transaction.
2. Check the Account field on the record’s line item.
3. Compare it to the undeposited funds account in your connector settings.
4. Either edit the NetSuite record to use the correct undeposited funds account, or update your connector settings to match the account used on records.
5. Changing accounts on records might require journal entries to correct. Consult your accounting team.
6. Retry the payout sync.

Transaction amount mismatch

The unequal_amounts error code indicates that the transaction amount in Stripe doesn’t match the amount on the linked NetSuite record. The amounts must match exactly for the payout deposit to balance. Common causes include manual edits to the NetSuite record amount, workflows or scripts that modify amounts, currency conversion differences, and tax or fee adjustments applied in NetSuite.

To resolve this issue:

1. In the connector app, note the exact amount from the Stripe transaction.
2. Log in to NetSuite and find the NetSuite record linked to this transaction.
3. Compare the Total or Amount field with the Stripe amount.
4. Identify the source of the discrepancy by checking System Notes for manual edits, or reviewing workflow and script logs for automated changes.
5. Either correct the NetSuite record to match the Stripe amount, or if the NetSuite amount is intentionally different, contact Stripe support for guidance.
6. Retry the payout sync.

Deposit search failed

The deposit_search_failed error code indicates that the connector couldn’t search for deposit records in NetSuite to verify if a record is already deposited. This can be caused by permission issues or connectivity problems.

To resolve this issue:

1. Log in to NetSuite as an administrator and navigate to Setup > Users/Roles > Manage Roles.
2. Edit the Stripe Limited Access role.
3. Verify the role has Transactions > Make Deposits permission set to at least View.
4. Check that Reports > Search permission is enabled.
5. Retry the payout sync. If the error persists, contact Stripe support.

Other payout errors

If you encounter any of the following error codes, they indicate internal issues that the connector will either automatically retry or that require Stripe support to resolve:

• unexpected_breakage_error: An unexpected internal error occurred.
• unexpected_subsidiary_initialization_error: An error occurred while initializing subsidiary data.
• multiple_successful_translations_found: A data integrity issue where the same transaction was synced multiple times.

For these errors, contact Stripe support with your payout ID (for example, po_xxx) and the error code.

Load invoice or customer payment pages

The following table describes errors you might encounter when attempting to load an invoice payment page or a customer payment page. You can view all errors in the connector app’s sync records window.

Duplicate payments

Stripe and NetSuite handle duplicate payments differently. While Stripe allows overpayment of an invoice, NetSuite returns an error if a customer attempts to make a payment on a fully paid invoice. By default, if a duplicate payment occurs in Stripe, the connector won’t sync the payment because NetSuite doesn’t allow a second payment.

If a duplicate payment causes an error when the connector attempts to reconcile the payout during deposit automation, you can fix the issue by manually removing the first payment from the invoice to allow the second payment.

You can also allow the connector to handle duplicate payments for you. If you have a NetSuite invoice that’s fully paid, the connector brings over duplicate payments as unapplied payments in NetSuite. The unapplied payment includes the following memo: Stripe Payment Error: could not apply to invoice XYZ. You can then use these unapplied payments on another invoice, or refund the payments manually in Stripe. To search for duplicate payments in NetSuite, create a saved search using the memo as your criteria.

You can enable the connector to handle duplicate payments in the following ways:

• Allow all duplicate payments in the connector by default. To do so, go to your connector settings and enable Allow duplicate invoice payments in your Stripe app settings. Contact your implementation partner to understand all accounting and technical implementations before they enable this feature for you.

• Using the Stripe API, add the netsuite_allow_duplicate: true field in the metadata of a duplicate Stripe charge.

Stripe payment link fields

Make sure to configure the following fields correctly.

Hidden GUID field

The Hidden GUID field won’t automatically create randomized IDs for invoices created before you installed the payment links bundle. This includes invoices created from previous sales orders.

If you receive a large volume of errors as a result of this default functionality, contact your Stripe representative.

Bundle updates

When you update the bundle, the Default Value configuration resets to the default settings. You must reconfigure the Default Value configuration for it to function properly again for your customers.

Permissions

If you require specific permissions to access invoices, make sure to add those permissions to the Stripe Limited Access role (for example, by navigating to Lists > Tax Details > Full). This allows the connector to access invoice information to create an invoice payment page.

Access roles

The GUID might disappear after you save it for specific access roles that have fewer permissions than an admin. For example, View access is insufficient. To grant the appropriate permissions, go to the Stripe Payment Page Guid custom field (custbody_stripe_payment_link_guid) and select Access. Add the role and grant Edit access in the custom field.

Bulk syncing records

Use the Support Tool to add Stripe records for re-syncing and to track their progress.

Sync status

1. In the Dashboard, go to Settings > Installed apps > Stripe Connector for NetSuite > Support Tooling.

2. Click Sync records.

3. Paste one or more Stripe resource IDs, separated by commas. The maximum number of IDs you can submit at once is shown in the UI.

4. Click Submit.

After you click submit, Accepted IDs are added to the queue immediately. Rejected IDs appear in an error list with one of the following reasons:

• Fix the issue (for example, correct an invalid ID).
• Resubmit any IDs that failed, if necessary.

View sync status

To view the sync status, from the Support Tooling page, click View Sync Status, then paste the comma-separated IDs you want to check, and click Submit.

Review the following sections to understand queue statuses, sync statuses, error types.

Queue statuses

Sync statuses

Error types

Prioritized

The Prioritized column indicates that the record sync is for the provided ID is prioritized over other record syncs.