Overview

This integration syncs Stripe Refunds into NetSuite through PayPack. For each Stripe refund, PayPack creates a NetSuite Credit Memo from the related invoice, then creates a Customer Refund and applies the Credit Memo to it.

All import modes use the same PayPack configuration and field mappings, so results are consistent however a refund is imported. Every run is logged for troubleshooting

Import Modes

Before You Start

Refunds are matched to NetSuite through the original payment. Stripe refunds do not include an invoice ID, so PayPack uses the refund's Stripe payment intent to find the NetSuite Customer Payment that PayPack imported earlier, and from it the related NetSuite invoice.

• The original payment must already be imported into NetSuite (for example, by the Invoice or Payment import).
• That Customer Payment must be linked to a NetSuite invoice.
• If either is missing, the refund is skipped and noted in the PayPack Flow Record Log.

Configuration Settings

All refund settings are located under the Refunds subtab within the Data Orchestration tab. Inside this subtab, the Refunds field group contains all configuration fields required for managing the Refunds flow.

Note: Click any field label in the Refunds field group to see a description of its purpose and usage.

Field Descriptions

• Enable Refunds Flow: Check/mark to enable importing Stripe refunds into NetSuite. Uncheck to stop all refunds imports.

• Update Stripe Refund Metadata: Check/mark to automatically write the NetSuite Customer Refund Internal ID back to the corresponding Stripe refund after it is created.
   

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

• Credit memo Line Item for Partial Refunds: Maps the total Stripe partial refund amount to the selected NetSuite item. Regardless of the number of lines on the Stripe invoice, only one line will be added to the NetSuite Credit Memo for partial refunds.

Configuring Items for Partial Refunds

A refund is treated as partial when the refund amount is less than the NetSuite invoice total. Otherwise it is a full refund.

• Full refund: all lines transformed from the invoice are kept on the Credit Memo as they are.
• Partial refund, item priority:
  • If Credit Memo Line Item for Partial Refunds is configured, a single line is added to the Credit Memo with that item, and the partial refund amount from Stripe is applied to it.
  • If it is not configured, the first invoice line item is used, whether the invoice has one line or several.

Note: Item mappings are not mandatory. Even if item mappings are provided, the Credit Memo line will use either the configured Credit Memo Line Item for Partial Refunds or the first invoice line item.

Note: If your Credit Memos need required or custom line-level fields, map them in the item-level mappings. If a required value is not mapped, Credit Memo creation fails because of missing mandatory field values.

• Credit Memo Field Mappings: Controls how Stripe Refund fields are mapped to NetSuite Credit Memo fields. Map the Stripe Refund ID (PayPack) field on the Credit Memo. PayPack uses it to recognize refunds it has already imported
  Note: Fields from the Stripe refund 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.
   

• Customer Refund Account: Select the NetSuite account where customer refunds will be recorded. All imported Stripe refunds are posted to this account.
  Note: To use condition-based mapping, leave the Customer 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 Field Mappings.

• Customer Refund Method: Select the refund method in NetSuite for recording Stripe refunds.

Note: To use condition-based mapping, leave the Customer 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 Field Mappings.

• Customer Refund Field Mappings: Controls how Stripe Refund fields are mapped to NetSuite Customer Refund fields. This includes applying the Credit Memo created, using the configured sublist mappings, which reference the generated NetSuite Credit Memo ID.
  Note: Fields from the Stripe refund object can be used. The NetSuite Credit Memo record ID can be accessed in mappings as a nsCreditMemoId.Refer to the Sample Customer Refund Field Mappings at the end of this document for reference on how to correctly apply a Credit Memo to a Customer Refund. Also, for detailed JSON mapping examples and instructions, refer to the Field Mapping Documentation.

• Map the Stripe Refund ID (PayPack) field on the Credit Memo. PayPack uses it to recognize refunds it has already imported. See the Sample Credit Memo Field Mappings below and the Field Mapping Documentation.
• Customer Refund Account: Select the NetSuite account where customer refunds will be recorded. All imported Stripe refunds are posted to this account. Note: To use condition-based mapping, leave this field empty and use static or dynamic mapping. Filling it in sets a global default that overrides any conditional logic in the Customer Refund Field Mappings.
• Customer Refund Method: Select the refund method in NetSuite for recording Stripe refunds. Note: To use condition-based mapping, leave this field empty and use static or dynamic mapping. Filling it in sets a global default that overrides any conditional logic in the Customer Refund Field Mappings.
• Customer Refund Field Mappings: Controls how Stripe refund fields map to NetSuite Customer Refund fields. This includes applying the Credit Memo through the sublist mappings, which reference the generated NetSuite Credit Memo ID. Note: Fields from the Stripe refund object can be used. The NetSuite Credit Memo record ID is available in mappings as nsCreditMemoId. See the Sample Customer Refund Field Mappings below and the Field Mapping Documentation.

How the Import Works

Batch and On-Demand imports follow the same steps.

1. Get refunds

• Refunds are fetched from the Stripe API.
  • Batch: only refunds created on or after the Last Exported Date.
  • On-Demand: only the Stripe refund IDs you specify on the deployment.
• Refunds already in NetSuite are skipped, using the Stripe Refund Id (PayPack) field on the Credit Memo.

2. Identify the related invoice

• PayPack gets the Stripe payment intent from the refund and uses its Payment Intent ID (PayPack) to find the matching NetSuite Customer Payment.
• From that payment it reads the NetSuite invoice ID and the invoice total.
• If no Customer Payment is found, or the payment has no linked invoice, the refund is skipped.

3. Retrieve the invoice line items

• PayPack looks up the NetSuite invoice's lines to decide which item to use if the refund is partial.

4. Identify the refund type

• The refund amount is compared with the invoice total. A refund smaller than the invoice total is a partial refund.

5. Create the Credit Memo

• The NetSuite invoice is transformed into a Credit Memo and your field mappings are applied.
• Full refund: all invoice lines are kept. Partial refund: a single line is added (see Configuring Items for Partial Refunds).
• If mapped, the Stripe Refund ID is stored in the Stripe Refund ID (PayPack) field on the Credit Memo.
• Each created or skipped refund is logged in the PayPack Flow Record Log.

6. Create the Customer Refund

• A NetSuite Customer Refund is created after the Credit Memo.
• The Credit Memo is applied to the Customer Refund through the sublist mappings.
• Fields such as customer, amount and Stripe Refund ID (PayPack) are filled from your mappings.

7. Update Stripe metadata

• The NetSuite Customer Refund record ID is written back to the Stripe refund.
• Skipped if Update Stripe Refund Metadata is not checked.

Script Details

Batch (Map/Reduce)

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

• First run: fetches refunds created on or after the Refund Start Date. Later runs fetch only refunds created after the Last Exported Date, so nothing is imported twice.
• Parameters:
  • Stripe Account Id (custscript_pp_refund_stripe_account_id): internal ID of the PayPack Stripe Account Configuration record.
  • Refund Start Date (custscript_pp_refund_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.

On-Demand (Map/Reduce)

Script: PayPack S2NS Refund Import MR OnDemand. Runs only when you trigger it. Use it mainly to import missing refunds.

• Parameters:
  • Stripe Account Id (custscript_pp_od_ref_stripe_account_id): internal ID of the PayPack Stripe Account Configuration record.
  • Stripe Refund IDs (custscript_pp_od_stripe_refund_ids): comma-separated list of the Stripe refunds to import.

Deploying and Scheduling

1. Go to Customization > Scripting > Scripts.
2. Filter by Type: Map/Reduce and open the Batch or On-Demand script.
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. Batch: 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. Click Save.
6. On-Demand: enter the refund IDs and use Save and Execute.

Sample Field Mappings

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

Sample Credit Memo Field Mappings

{
  "fields": [
    { "generate": "location", "hardCodedValue": "<LOCATION_ID>" },
    { "generate": "custbody_nm_pp_stripe_refund_id", "extract": "id" }
  ],
  "sublist": {
    "item": [
      { "generate": "item", "hardCodedValue": "<ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": "1" },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "handlebars": "{{toFixed (divide amountRefunded 100) 2}}" },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" }
    ]
  }
}

Sample Customer Refund Field Mappings

{
  "fields": [
    { "generate": "location", "hardCodedValue": "<LOCATION_ID>" },
    { "generate": "custbody_nm_pp_stripe_refund_id", "extract": "id" }
  ],
  "sublist": {
    "item": [
      { "generate": "item", "hardCodedValue": "<ITEM_ID>" },
      { "generate": "quantity", "hardCodedValue": "1" },
      { "generate": "price", "hardCodedValue": "-1" },
      { "generate": "amount", "handlebars": "{{toFixed (divide amountRefunded 100) 2}}" },
      { "generate": "taxcode", "hardCodedValue": "<TAX_CODE_ID>" }
    ]
  }
}
Sample Customer Refund Field Mappings
{
  "fields": [
    {
      "generate": "customer",
      "dynamicLookup": {
        "recordType": "customer",
        "filters": [
          ["custentity_nm_stripecharge_customer_id", "is", "{{charge.customer}}"]
        ],
        "resultField": "internalid",
        "default": ""
      }
    },
    { "generate": "total", "handlebars": "{{toFixed (divide amountRefunded 100) 2}}" },
    { "generate": "custbody_nm_pp_stripe_refund_id", "extract": "id" }
  ],
  "sublist": {
    "apply": [
      { "generate": "apply", "hardCodedValue": "T" },
      { "generate": "doc", "extract": "nsCreditMemoId" }
    ]
  }
}