NetSuite - Payment creation & events
Initiating payments
Payment event handling
Payment paid out event handling
Payment failed event handling
Payment chargeback & late failure event handling
The process for collecting direct debit payments for NetSuite invoices is outlined in this section.
Note: there are alternative methods for creating payments for invoices as outlined in the FAQs.
Initiating payments
The first step to creating a direct debit payment for a customer with an active mandate is populating & saving the related fields on the NetSuite invoice.
| Field | GC Subtab | Description | Editable? |
|---|---|---|---|
| Due date | N/A |
(Required for payment initiation) The due date of the invoice. This will determine the charge date for the GoCardless payment. If the due date is after the next possible charge date for the customer's mandate, the GoCardless payment will be charged on the invoice due date. If the due date is before the next possible charge date for the customer's mandate, the GoCardless payment will be charged on the next possible charge date. |
Y |
| Document number | N/A | The Invoice document number will be set as the payment description in GoCardless. The GoCardless payment description is displayed on email notifications to the customer. | Y |
| Pay with GoCardless | GoCardless > Request information |
(Required for payment initiation) When this checkbox is selected for an open invoice that has a mandate populated and does not have an existing GoCardless payment against it, a payment request will be sent through to GoCardless within 5 minutes following the invoice save. |
Y |
| Payment reference | GoCardless > Request information |
(Optional) An optional payment reference can be input before saving an invoice with the "Pay with GoCardless" checkbox selected. When a reference is input, it will populate the payment reference in GoCardless which partially drives how the payment appears on the customer's bank statement. See details here. |
Y (10 character limit) |
| Amount due | N/A |
(Non-zero amount required for payment initiation) The amount due on the invoice will determine the amount of the GoCardless payment. |
Y |
| Currency | N/A |
(Required for payment initiation) The invoice currency will determine the GoCardless payment currency. If the invoice currency isn’t mapped to a GoCardless currency under GoCardless > Setup > GoCardless currency mapping, the payment will fail to be initiated. |
Y |
The following non-editable fields will also be populated on the invoice for viewing purposes:
| Field | GC Subtab | Description | Editable? |
|---|---|---|---|
| GoCardless account | GoCardless > Request information |
(Required for payment initiation) The GoCardless configuration record (i.e. account) that's associated with the customer. This will be auto-populated on the invoice from the associated customer record. |
N |
| Integration status | GoCardless > Request information | The status of the payment request to GoCardless: Pending: this means the payment request hasn't been sent to GoCardless yet (either the invoice was saved without the "Pay with GoCardless" checkbox selected, or the invoice was saved with the "Pay with GoCardless" checkbox selected and the request hasn't gone through yet). |
N |
| Mandate | GoCardless > Request information |
(Required for payment initiation) The mandate that's assigned to the customer in the invoice currency. This will be auto-populated on the invoice from the associated customer record. If the customer doesn’t have a mandate in the invoice currency, or the mandate is in an unchargeable state (cancelled, expired, etc.), an error message will be displayed upon saving the invoice with the “Pay with GoCardless” field selected. |
N |
Things to note:
- Payment amounts: the integration creates one GoCardless payment per NetSuite invoice for the outstanding invoice amount. It does not natively support splitting a single invoice into multiple GoCardless payments (e.g. a payment plan), or collecting partial payments.
- Credits and invoice amount adjustments: Once a payment has been created in GoCardless, the integration cannot account for credits subsequently applied to the invoice or any other adjustments to the invoice amount. To ensure the correct amount is collected, any credits and amount adjustments should be applied to the invoice before the "Pay with GoCardless" checkbox is selected. If an invoice does need to be adjusted after a payment has already been initiated, the payment will need to be cancelled directly in the GoCardless dashboard and then re-initiated using the "Retry payment" button on the invoice. To avoid this additional overhead, we recommend only initiating GoCardless payments once an invoice is in its final state.
-
Creating invoices via CSV import or API integration:
- If you create or update invoices via a CSV import, ensure the "Run Server SuiteScript" option is enabled in the import settings (under Step 2: Import Options → Advanced Options). If the CSV import job does not have this enabled, the integration SuiteBundle scripts will not fire during the import. This means the required read-only GoCardless fields (Mandate, GoCardless account) won’t populate, and the invoices won’t be picked up for processing.
- If your NetSuite invoices originate from another system (e.g. a CRM or billing platform) and are pushed into NetSuite via API or integration, it's important to confirm that the integration writing to NetSuite triggers SuiteScript execution. If not, the required read-only GoCardless fields (Mandate, GoCardless account) won’t populate, and the invoices won’t be picked up for processing.
Integration logic for picking up invoices for processing:
The integration uses a saved search to determine which invoices to submit for processing. The saved search is called GoCardless | Celigo | Invoice sync search. The Celigo integration will process the invoices returned by this saved search every 5 minutes.
The saved search uses the following filters:
- Main Line is true — ensures only the header line of each invoice is returned, not individual line items.
- Type is Invoice
- Integration status is any of: Pending, Failed, or none (i.e. blank) — this ensures the integration picks up new invoices that haven't been processed yet, as well as any that previously failed due to API errors such as an exceeded transaction limit (note, these are not payment retries as the payment was never created in this scenario)
- Approval Status is none of: Pending Approval, Rejected — so only fully approved invoices are picked up.
- The Mandate status is any of Active, Reinstated, Replaced, or Pending Customer Approval
- Pay with GoCardless is true
Resolving missing mandate IDs:
If the mandate is missing from the invoice’s GoCardless > Request Information subtab, but the customer has an active mandate assigned in the invoice currency, you can follow the below steps to refresh the mandate ID on the invoice:
- Edit the customer’s mandate > unassign the customer > save
- Re-edit the customer’s mandate > reassign the customer > save
This will retrigger the script to update the mandate on the customer’s open invoices.
Troubleshooting unprocessed invoices:
If an invoice doesn’t get picked up for processing (the GoCardless > Request Information > Integration Status field remains as pending on the invoice), it could be due to one of the following:
- One or more of the required invoice fields is missing. You can compare your invoice fields to the required fields in the above tables to validate this.
-
The invoice does not meet the saved search criteria. You can run the saved search in NetSuite to validate this.
- In NetSuite, go to Transactions → Lists → Saved Searches (or navigate to Reports → Saved Searches → All Saved Searches).
- Search for the title "GoCardless | Celigo | Invoice sync search" or look for the search ID customsearch_ns_gc_inv_search.
- Click the search title to open it.
- Click the Preview button to run it and see the current results.
- If the required fields are populated and the invoice is returned by the saved search, please reach out to GoCardless for further troubleshooting. If none of your invoices are being picked up for processing, this points towards an integration configuration issue that GoCardless can help resolve If the GoCardless > Request Information > Integration Status field is set to failed on the invoice, that means the invoice was processed by GoCardless, but the request failed due to an API error (for example, the amount exceeded the transaction limit on your account). The Integration error field will display the related error message.
Payment events
After the invoice is saved with the “Pay with GoCardless” checkbox selected, the payment will be created in GoCardless within minutes. A script runs every 5 minutes, and sends payment requests to GoCardless for invoices that meet the following conditions:
- Fully approved & in the open state.
- Related to a customer with a mandate in the “Active” or “Pending Customer Approval” status.
- Has the “GoCardless Account” field populated - this is inherited from the customer record’s “GoCardless Configuration” field.
- Has the “Pay with GoCardless” checkbox selected without an existing GoCardless payment against it.
Once the payment is created in GoCardless, the following fields will be populated or updated on the invoice:
| Field | GC Subtab | Description | Editable? |
|---|---|---|---|
| Integration status | GoCardless > Request information | The status of the payment request to GoCardless: Processed: This means the payment request was successfully sent to GoCardless. The details in the "transaction information" section should be populated at this time. Failed: This means the payment request to GoCardless failed. The related error message will be displayed in the "Integration error" field. |
N |
| Integration error | GoCardless > Request information | When this "Integration status" field is set to "failed", the error message will be displayed in this field to explain why it failed. After the appropriate adjustments have been made, you can re-attempt the payment request by re-saving the invoice with the "Pay with GoCardless" box selected. |
N |
| Payment status | GoCardless > Transaction information | The status of the GoCardless payment. It will initially be set to “pending submission”. This means, the payment has been created in GoCardless, and is pending submission to the bank for processing. | N |
| Description | GoCardless > Transaction information | The description associated with the payment status. | N |
| Charge date | GoCardless > Transaction information | The charge date of the GoCardless payment. It will equal the invoice due date unless the invoice due date was prior to the next possible charge date on the customer's mandate. | N |
| GoCardless payment ID | GoCardless > Transaction information | The GoCardless payment ID. | N |
Data flow - payment creation
As the GoCardless payment processes, the following fields will be updated on the invoice so you have full visibility into where your payment stands within NetSuite:
| Field | GC Subtab | Description | Editable? |
|---|---|---|---|
| Payment status | GoCardless > Transaction information | The status of the GoCardless payment. It will be set to one of the following: Pending submission: The payment has been created in GoCardless, and is pending submission to the bank for processing. Submitted: The payment has been submitted to the bank for processing Confirmed: The payment has been collected from the customer’s bank account, and is now being held by GoCardless pending being paid out. Paid out: The payment has left GoCardless and has been sent to the creditor’s bank account. Failed: The payment could not be collected, usually because the customer did not have sufficient funds available. Resubmission requested: A request to resubmit the failed payment was initiated (see the Payment failures section) Charged back: The customer initiated a chargeback through their bank, and the payment has been returned to the customer. Cancelled: The payment was cancelled. Chargeback settled: The chargeback has been settled in a payout Late failure settled: The late failure has been settled in a payout |
N |
| Reason code | GoCardless > Transaction information | The reason code that’s associated with the payment status. This only applies to some payment statuses such as failed, charged back, etc. See details here. | N |
| Description | GoCardless > Transaction information | The description associated with the payment status. See details here. | N |
Troubleshooting invoice updates for payment events:
If the GoCardless fields aren’t being updated on an invoice after the GoCardless payment was initiated, it could be due to custom validations in your NetSuite account. If you’ve made fields mandatory on your invoice form, any time the integration attempts to update the GoCardless invoice fields, NetSuite may reject the update if the mandatory field isn't populated. The "Ignore Mandatory Fields" flag is set to true to prevent these types of issues, but this flag does not bypass all validations (for example, server-side script validation rules). Please review and verify whether there are any validations on your invoice form that wouldn’t be prevented by the "Ignore Mandatory Fields" setting before using the integration.
Data flow - payment status updates
Payment paid out event
Once a GoCardless payment is settled, it transitions to the “Paid out” status. At this point,
- A payment record will be created in NetSuite and applied to the related invoice. The Payment will be created with the Undeposited Funds account. It will initially have the Not Deposited status, but it will transition to Deposited once the corresponding payout has reconciled in NetSuite.
- Undeposited Funds account usage: Please confirm whether the usage of the Undeposited Funds bank account aligns with your NetSuite account preferences (Setup → Accounting → Accounting Preferences → Use Undeposited Funds Account for Customer Payments). If this setting is enabled, NetSuite automatically assigns the Undeposited Funds account to new payment records which is how the integration is designed to function. When this setting is disabled, an account ID typically needs to be explicitly set when creating payments, which the integration doesn’t handle. As a workaround, our integration will force the usage of the Undeposited Funds account in this scenario. You should only move forward with the integration if you’re comfortable with this approach.
- Applying Customer Payment amounts to invoices: If the invoice balance is adjusted after the GoCardless payment is initiated (for example, by applying a credit), there would be a discrepancy between the GoCardless payment amount and the invoice balance. In this case, the integration applies up to the open invoice balance to the invoice and leaves any remaining amount from the payment unapplied.
- The invoice will be marked as “Paid in full”.
- The payment status, reason code, and description fields will be updated on the invoice as outlined in the above section.
Troubleshooting missing payments:
If the payment records aren’t being created in NetSuite for your paid out GoCardless payments, it could be due to one of the following:
- Closed accounting periods: NetSuite will reject the creation of a Customer Payment if the transaction date falls within a locked accounting period. The payment date is determined by when the GoCardless paid_out event is received.
- Custom User Event scripts on Customer Payment records that conflict with the integration: If you have custom scripts deployed on Customer Payment records (for example, a script that enforces specific field values or triggers additional validation on save), these can conflict with what the integration is trying to write. The integration sets the “Ignore Mandatory Fields” flag to true when creating records to avoid these types of issues, but this flag does not bypass all validations. Please review and verify whether there are any validations on your Customer Payment records that wouldn’t be prevented by the “Ignore Mandatory Fields” setting before using the integration.
- The payment wasn’t created via the GoCardless for NetSuite integration: For example, it was created directly in the GoCardless dashboard and it doesn’t have an invoiceId metadata identifier linking it to an invoice in NetSuite.
Data flow - payment paid out event
Payment failed event
If a payment fails, the payment status details will be updated on the invoice, including the failure reason code and description.
Payment chargeback & late failure events
After a GoCardless payment is "paid out", it could fail or become charged back in rare cases. When this occurs, the integration will unapply the Payment from the Invoice in NetSuite, create a Refund record to represent the chargeback or late failure, and apply the Payment to that Refund. The invoice will be re-opened as a result.
The Payment Status field on the invoice will also be updated to reflect the post-payout chargeback or failure.
Refund and deposit creation
The handling of post-payout chargeback and late failures differs slightly depending on whether the Payment is Deposited or Not Deposited in NetSuite at the time of the event.
If the Payment was not yet deposited at the time of the chargeback or late failure settlement:
- The Payment will be unapplied from the Invoice
- A Refund will be created and the payment will be applied to the Refund
- A zero-amount Deposit will be created to clear the Undeposited Funds account without any net GL impact.
If the Payment was already deposited at the time of the chargeback or late failure settlement:
- The Payment will be unapplied from the Invoice
- A Refund will be created and the Payment will be applied to the Refund
The Refund is created using the following details:
- Customer - sourced from the Payment
- Account - Undeposited Funds if the Payment was Not Deposited. Deposit bank account if the Payment was Deposited.
- Amount - sourced from the Payment
- Currency - sourced from the Payment
- Exchange Rate - sourced from the Payment
- Date - Arrival date of the payout in which the chargeback or late failure was settled
- Credit side of the transaction - Sourced from the Refund’s Account field (see above)
- Debit side of the transaction - The AR account is sourced from the charged back or late failed Payment record in NetSuite.
Refunds and Deposits (when applicable) are created using the chargeback_settled and late_failure_settled events from GoCardless, rather than the initial charged_back and failed events. This ensures that records are only created in NetSuite once the chargeback or late failure has settled in a payout, and that dates align with what appears on your bank statement.
The Refund date and corresponding Deposit date (when applicable) are set to the arrival_date of the payout in which the chargeback or late failure was settled.
Payment status updates
The Payment Status field on the GoCardless > Transaction Information subtab of the invoice is updated as follows:
- The charged_back and failed events update the Payment Status field to reflect the chargeback or failure as soon as it occurs - no additional actions are triggered from these events.
- The chargeback_settled and late_failure_settled events also update the same Payment Status field when settlement is confirmed and trigger the Refund creation.