Overview

This integration syncs Stripe disputes and dispute reversals into NetSuite through PayPack. It has two parts:

• Disputes: when Stripe records a dispute, PayPack records it in NetSuite like a refund (a Cash Refund, or a Credit Memo with a Customer Refund) and stores the dispute details in a PayPack custom record.
• Dispute Reversals: PayPack checks Stripe for updates on those disputes. When a dispute is won, PayPack records it in NetSuite like a payment (a Cash Sale or a Customer Payment).

Both parts run on a schedule and use the same PayPack configuration and field mappings. Every run is logged for troubleshooting

Import Modes

Disputes and Dispute Reversals are imported in batch only. The related saved searches will need to be adjusted for testing and reimporting any records that errored out. 

Configuration Settings

All dispute settings are located under the Disputes subtab within the Data Orchestration tab. Under this subtab, the Dispute and Dispute Reversal field groups contain all configuration fields required for managing the Disputes flow.

Note: Click any field label in the Dispute and Dispute Reversal field groups to see a description of its purpose and usage.

Field Descriptions

Dispute fields

• Enable Disputes Flow: Check/mark to enable importing Stripe disputes into NetSuite. Uncheck to stop all dispute imports.
   

• Last Exported Date: Shows the last time disputes were imported from Stripe (in Unix timestamp). This value is used in the next import to fetch only disputes created after this time using the created[gte] parameter.
  Note: The system updates this field after every flow execution, and it is read-only.
   

• Transaction Type: Determines which NetSuite transactions are created. Choose Cash Sale / Cash Refund or Customer Payment / Customer Refund, based on your accounting workflow. Note: With Cash Sale / Cash Refund, a Cash Refund is created for disputes and a Cash Sale for dispute reversals. With Customer Payment / Customer Refund, a Credit Memo plus a Customer Refund is created for disputes, and a Customer Payment for dispute reversals.  A transaction type must be selected. Without one, disputes cannot be processed.

• Dispute Line Item: A NetSuite item used in Credit Memo to map the total Stripe dispute amount.
  
  Note: Use only non-inventory items. To use condition-based mapping, leave the Dispute Line Item field empty and use static or dynamic mapping. Filling in these fields sets a global default that overrides any conditional logic in item mappings of the Credit Memo Field Mappings.
   

• Credit Memo Field Mappings: Controls how Stripe Dispute fields are mapped to NetSuite Credit Memo fields.
  Note: Fields from the Stripe dispute object can be used.
  Refer to the Sample Credit Memo Field Mappings at the end of this document for reference. Also, for detailed JSON mapping examples and instructions, refer to the Field Mapping Documentation.
   

• Refund Account: Select the NetSuite account where Customer Refund / Cash Refund will be recorded. All imported Stripe disputes are posted to this account.
  
  Note: To use condition-based mapping, leave the Refund Account field empty and use static or dynamic mapping. Filling in this field sets a global default that overrides any conditional logic in the Customer Refund / Cash Refund Field Mappings.
  Refer to the Field Mapping Documentation for examples and detailed instructions on implementing conditional mappings.
   

• Refund Method: Select the payment method to be used for recording the Stripe dispute on the Customer Refund / Cash Refund record.
  
  Note: To use condition-based mapping, leave the Refund Method field empty and use static or dynamic mapping. Filling in this field sets a global default that overrides any conditional logic in the Customer Refund / Cash Refund Field Mappings.
  Refer to the Field Mapping Documentation for examples and detailed instructions on implementing conditional mappings. 

• Customer Refund / Cash Refund Field Mappings: Controls how Stripe Dispute fields are mapped to NetSuite Customer Refund / Cash Refund fields.
  Note: Fields from the Stripe dispute object can be used.
  Refer to the Sample Customer Refund Field Mappings or Sample Cash Refund Field Mappings at the end of this document for reference. Also, for detailed JSON mapping examples and instructions, refer to the Field Mapping Documentation.
   

Dispute Reversal fields

• NetSuite Dispute Records Saved Search: A saved search in NetSuite used to fetch dispute records with a status other than “won or lost”. The search retrieves disputes corresponding to Stripe disputes to facilitate status updates.
   

• Payment Account: Select the NetSuite Account where Stripe dispute payments will be recorded on the Customer Payment / Cash Sale record.
  
  Note: To use condition-based mapping, leave the Payment Account field empty and use static or dynamic mapping. Filling in this field sets a global default that overrides any conditional logic in the Customer Payment Field Mappings.
  Refer to the Field Mapping Documentation for examples and detailed instructions on implementing conditional mappings.
   

• Payment Method: Select the payment method in NetSuite for recording Stripe dispute payments on the Customer Payment / Cash Sale record.
  
  Note: To use condition-based mapping, leave the Payment Method field empty and use static or dynamic mapping. Filling in this field sets a global default that overrides any conditional logic in the Customer Payment Field Mappings.
  Refer to the Field Mapping Documentation for examples and detailed instructions on implementing conditional mappings.
   

• Cash Sale Line Item: A NetSuite item used in Cash Sale to map the total Stripe dispute amount.
  Note: Use only non-inventory items. To use condition-based mapping, leave the Cash Sale Line Item field empty and use static or dynamic mapping. Filling in these fields sets a global default that overrides any conditional logic in item mappings of the Cash Sale Field Mappings.
   

• Customer Payment / Cash Sale Field Mappings: Controls how Stripe Dispute fields are mapped to NetSuite Customer Payment / Cash Sale fields.
  Notes: In these mappings, the Stripe dispute data is available under stripeDisputeData (for example, stripeDisputeData.id). Values from the saved search are available by their column label (for example, dispute_customer_id).
  Refer to the Sample Customer Payment Field Mappings or Sample Cash Sale Field Mappings at the end of this document for reference. Also, for detailed JSON mapping examples and instructions, refer to the Field Mapping Documentation.
• Notes: In these mappings, the Stripe dispute data is available under stripeDisputeData (for example, stripeDisputeData.id). Values from the saved search are available by their column label (for example, dispute_customer_id). See the Sample Customer Payment and Cash Sale Field Mappings below and the Field Mapping Documentation.

How the Import Works

Disputes

1. Get disputes. Disputes are fetched from Stripe together with their charge. Only disputes created after the Last Exported Date are fetched. Disputes already in NetSuite are skipped, using the Dispute ID on the PayPack Stripe Disputes custom record.
2. Check the transaction type. PayPack reads the Transaction Type from your configuration. If none is set, the dispute cannot be processed.
3. Create the PayPack Stripe Disputes record. A custom record stores the Stripe dispute details, such as the dispute ID, charge ID, dispute amount and Stripe customer ID.
4. Create the NetSuite transactions. PayPack creates a Cash Refund, or a Credit Memo and a Customer Refund, using your mappings, refund method and refund account. If mapped, the Stripe Dispute ID is stored in the Stripe Dispute Id (PayPack) field. Before creating a record, PayPack checks whether one already exists for the same Stripe dispute ID, and skips it if so. Each created or skipped record is logged in the PayPack Flow Record Log.

Dispute Reversals

1. Get dispute records. PayPack loads the PayPack Stripe Disputes records from the configured saved search (status other than won or lost).
2. Get the latest Stripe dispute. For each record, PayPack fetches the current dispute data from Stripe using the dispute ID.
3. Check the transaction type. If none is set, the dispute cannot be processed and an error asks you to select one.
4. Create the NetSuite transaction. A Cash Sale or Customer Payment is created only when the Stripe dispute status is won. Disputes with any other status are updated on the NetSuite dispute record but do not create a transaction. If mapped, the Stripe Dispute ID is stored in the Stripe Dispute Id (PayPack) field, and PayPack skips the record if one already exists for that dispute. Each created or skipped record is logged in the PayPack Flow Record Log.
5. Update the NetSuite dispute record with the latest status from Stripe.

Script Details

Disputes (Map/Reduce)

Script: PayPack S2NS Dispute Import MR. Runs on a schedule you define.

• First run: fetches disputes created on or after the Dispute Start Date. Later runs fetch only disputes created after the Last Exported Date, so nothing is imported twice.
• Parameters:
  • Stripe Account Id (custscript_pp_stripe_dis_account_id): internal ID of the PayPack Stripe Account Configuration record.
  • Dispute Start Date (custscript_pp_dispute_start_date): used only on the first run, or when no Last Exported Date exists. Enter a Unix timestamp in seconds, for example 1761147332. The Last Exported Date is updated automatically when a run completes.

Dispute Reversals (Map/Reduce)

Script: PayPack S2NS Dispute Reversal Import MR. Runs on a schedule you define.

• Processes only the disputes that need a status check, using the saved search for the specified Stripe account.
• Parameter:
  • PayPack Stripe Account (custscript_pp_stripe_disputerever_acc_id): internal ID of the PayPack Stripe Account Configuration record.

Deploying and Scheduling

1. Go to Customization > Scripting > Scripts.
2. Filter by Type: Map/Reduce and search for PayPack S2NS Dispute Import MR or PayPack S2NS Dispute Reversal Import MR. Click View.
3. Click Deploy Script.
4. On the deployment, set the Stripe Account Id parameter to the internal ID of the relevant PayPack Stripe Account Configuration record.
5. On the Schedule subtab, choose the event type (single, daily, weekly, monthly or yearly), start and end dates (or No End Date), and the repeat interval.
6. Click Save.

Sample Field Mappings

IDs below are placeholders. Replace them with your own values.

Cash Refund Field Mappings

{
  "fields": [
    {
      "generate": "entity",
      "dynamicLookup": {
        "recordType": "customer",
        "filters": [
          ["custentity_nm_stripecharge_customer_id", "is", "{{charge.customer}}"]
        ],
        "resultField": "internalid",
        "default": ""
      }
    },
    { "generate": "location", "hardCodedValue": "<LOCATION_ID>" },
    { "generate": "custbody_pp_stripe_dispute_id", "extract": "id" }
  ],
  "sublist": {
    "item": [
      { "generate": "item", "hardCodedValue": "<ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": "1" },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "handlebars": "{{toFixed (divide amount 100) 2}}" },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" }
    ]
  }
}

Credit Memo Field Mappings

{
  "fields": [
    {
      "generate": "entity",
      "dynamicLookup": {
        "recordType": "customer",
        "filters": [
          ["custentity_nm_stripecharge_customer_id", "is", "{{charge.customer}}"]
        ],
        "resultField": "internalid",
        "default": ""
      }
    },
    { "generate": "location", "hardCodedValue": "<LOCATION_ID>" },
    { "generate": "custbody_pp_stripe_dispute_id", "extract": "id" }
  ],
  "sublist": {
    "item": [
      { "generate": "item", "hardCodedValue": "<ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": "1" },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "handlebars": "{{toFixed (divide amount 100) 2}}" },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" }
    ]
  }
}

Customer Refund Field Mappings

{
  "fields": [
    {
      "generate": "customer",
      "dynamicLookup": {
        "recordType": "customer",
        "filters": [
          ["custentity_nm_stripecharge_customer_id", "is", "{{charge.customer}}"]
        ],
        "resultField": "internalid",
        "default": ""
      }
    },
    { "generate": "account", "hardCodedValue": "<ACCOUNT_ID>" },
    { "generate": "total", "handlebars": "{{toFixed (divide amount 100) 2}}" },
    { "generate": "custbody_nm_pp_stripe_refund_id", "extract": "id" },
    { "generate": "paymentmethod", "hardCodedValue": "<PAYMENT_METHOD_ID>" }
  ],
  "sublist": {
    "apply": [
      { "generate": "apply", "hardCodedValue": "T" },
      { "generate": "doc", "extract": "nsCreditMemoId" }
    ]
  }
}

Cash Sale Field Mappings

{
  "fields": [
    {
      "generate": "entity",
      "dynamicLookup": {
        "recordType": "customer",
        "filters": [
          ["custentity_nm_stripecharge_customer_id", "is", "{{dispute_customer_id}}"]
        ],
        "resultField": "internalid",
        "default": ""
      }
    },
    { "generate": "custbody_pp_stripe_dispute_id", "extract": "stripeDisputeData.id" },
    { "generate": "location", "hardCodedValue": "<LOCATION_ID>" }
  ],
  "sublist": {
    "item": [
      { "generate": "item", "hardCodedValue": "<ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": "1" },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "handlebars": "{{toFixed (divide lines.data[].pricing.unit_amount_decimal 100) 2}}" },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" }
    ]
  }
}

Customer Payment Field Mappings

{
  "fields": [
    {
      "generate": "customer",
      "dynamicLookup": {
        "recordType": "customer",
        "filters": [
          ["custentity_nm_stripecharge_customer_id", "is", "{{dispute_customer_id}}"]
        ],
        "resultField": "internalid",
        "default": ""
      }
    },
    { "generate": "payment", "handlebars": "{{toFixed (divide stripeDisputeData.amount 100) 2}}" },
    { "generate": "location", "hardCodedValue": "<LOCATION_ID>" },
    { "generate": "custbody_pp_stripe_dispute_id", "extract": "stripeDisputeData.id" }
  ]
}