On This Page

Update Invoice Settings

Use invoice settings to configure and manage the behavior, appearance, and security of your invoice payments and payment page. You can update these settings:

For additional information about using payer authentication for invoicing, see Add Payer Authentication to Invoicing.

Reset to Default Settings

To reset your invoice settings to their default values, send the corresponding fields you want to reset with no value. This does not apply to the payment page label controls.

Endpoints

Send your API request message to one of these endpoints:

Production:

PUT https://api.cybersource.com/invoicing/v2/invoiceSettings?productType=INVOICING

Test:

PUT https://apitest.cybersource.com/invoicing/v2/invoiceSettings?productType=INVOICING

India Production:

PUT https://api.in,cybersource.com/invoicing/v2/invoiceSettings?productType=INVOICING

Fields for Updating Invoice Settings

The update invoice settings request does not require a specific set of fields. Instead, you can choose the fields to include in your request based on aspects of your checkout experience, email communications, and payer authentication enablement that you want to update.

Branding Identity Settings
Name	API Request Field	Description
Business Name	invoiceSettingsInformation. merchantDisplayName	The business name displayed on the invoice.
Currency	invoiceSettingsInformation. defaultCurrencyCode	The currency of the billed amount. The currency code default value is set to USD when this field is not specified. Only three-character ISO Standard Currency Codes are accepted. For more information, see ISO Standard Currency Codes reference guide..
Header Background Color	invoiceSettingsInformation. headerStyle.backgroundColor	The background color of the displayed invoice. Only hexadecimal code values with a prefixed # are accepted. Example: #000000
Logo	invoiceSettingsInformation. merchantLogo	The binary format of your logo that determines the image displayed to your customers. Image files are restricted to 1 MB and must be encoded in Base64 format. These are the supported file types: gif jpg png
VAT Tax Number	invoiceSettingsInformation. vatRegistrationNumber	The government-assigned tax identification number.
VAT Tax Number Displayed	invoiceSettingsInformation. showVatNumber	The toggle for displaying the VAT tax number in the invoice. Possible values: false : Do not display the VAT tax number. true : Display the VAT tax number.

Payment Page Label Control Settings: Rename Label
Name	API Request Field	Description
Label	invoiceSettingsInformation. customLabels[]key	The label that you can edit to display a custom text on the invoice creation page and the payment page. Possible values: billTo : billed customer name companyName : company name customerId : customer identifier description : invoice description discount : discount value invoiceNumber : invoice number partialPayment : partial payment amount shipping : shipping amount tax : tax amount Including this field set to no value does not update your settings.
Custom Label	invoiceSettingsInformation. customLabels[]value	The custom text you want to display instead of the default label text. Set this field to the text you want to display instead of the label you set in the invoiceSettingsInformation.customLabels[]key field. Including this field set to no value does not update your settings.

Payment Page Label Control Settings: Remove Label
Name	API Request Field	Description
Label	invoiceSettingsInformation. customLabels[]key	The label on the payment page that can be removed. Possible values: customerId : customer identifier description : invoice description discount : discount value invoiceNumber : invoice number partialPayment : partial payment amount Including this field set to no value does not update your settings.
Hide Label Toggle	invoiceSettingsInformation. customLabels[]hidden	The toggle that determines if the label included in the invoiceSettingsInformation.customLabels[]key field can display on the payment page. Possible values: true : label is removed from payment page false : label displays on payment page Including this field set to no value does not update your settings.

Payment Page Label Control Settings: Remove Label by Product
Name	API Request Field	Description
Label	invoiceSettingsInformation. customLabels[]key	The label on the payment page that can be removed. Possible values: discount : invoice discount amount tax : invoice tax amount Including this field set to no value does not update your settings.
Hide Label for Invoices	invoiceSettingsInformation. customLabels[] hiddenForInvoice	The toggle that determines if the label included in the invoiceSettingsInformation.customLabels[]key field can display on the payment page. Possible values: true : label is removed from invoice payment page false : label displays on invoice payment page Including this field set to no value does not update your settings.
Hide Label for Invoice Item	invoiceSettingsInformation. customLabels[] hiddenForItem	The toggle that determines if the label included in the invoiceSettingsInformation.customLabels[]key field can display on an itemized invoice payment page. Possible values: true : label is removed from itemized invoice payment page false : label displays on itemized invoice payment page Including this field set to no value does not update your settings.

Payment Page Behavior Settings
Name	API Request Field	Description
Customer Shipping Address	invoiceSettingsInformation.shipTo	Enables the invoice payment page to save the customer's shipping address. Possible values: false : Does not save the customer's shipping address true : Save the customer's shipping address
Customer Phone Number	invoiceSettingsInformation.phoneNumber	Enables the invoice payment page to save the customer's phone number. Possible values: false : Does not save the customer's phone number true : Save the customer's phone number
Customer Email	invoiceSettingsInformation.email	Enables the invoice payment page to save the customer's email address. Set to true .
Successful Transaction Redirect URL	invoiceSettingsInformation. customRedirectUrls. paymentAccepted	The URL that the customer is redirected to after completing a successful transaction in which the payment is processed.
Pending Transaction Redirect URL	invoiceSettingsInformation. customRedirectUrls. paymentPending	The URL that the customer is redirected to after completing checkout and the payment is pending.
Failed Transaction Redirect URL	invoiceSettingsInformation. customRedirectUrls. paymentRejected	The URL that the customer is redirected to after a transaction is rejected.

Email Notification Settings
Name	API Request Field	Description
Email Message	invoiceSettingsInformation. customEmailMessage	The custom message in the invoice email.
Email Reminder	invoiceSettingsInformation. enableReminders	The toggle for sending an email reminder to the customer five days before the invoice due and one day after it is past due. Possible values: False : No email reminder is sent. True : Email reminders are sent.
Merchant Email Notification	invoiceSettingsInformation. enableMerchantEmailNotifications	The toggle for the merchant receiving an email notification that a transaction is complete. Possible values: False : No email notification sent True : Email notification sent
Language	invoiceSettingsInformation. deliveryLanguage	The language of the email message sent to the customer. Set to one of these possible values: de-DE : German (Germany) en-US : English (United States) es-419 : Spanish as used in Latin America and the Caribbean fr-FR : French (France) ja-JP : Japanese (Japan) pt-BR : Portuguese (Brazil) ru-RU : Russian (Russia) zh-CN : Chinese (Simplified, People's Republic of China) zh-TW : Chinese (Traditional, Taiwan)

Payer Authentication Enablement Settings
Name	API Request Field	Description
Payer Authentication Enablement	invoiceSettingsInformation. payerAuthenticationInInvoicing	The indicator for payer authentication enablement. Possible values: disable : Disable 3-D Secure enable : Enable 3-D Secure payer authentication For more information about including payer authentication to your invoices, see Add Payer Authentication to Invoicing.

Example: Update Invoice Settings

Request

{
  "invoiceSettingsInformation": {
    "merchantLogo": "/9j/4AWFhYW",
    "merchantDisplayName": "Custom Merchant Display Name",
    "customEmailMessage": "Custom merchant email message",
    "enableReminders": true,
    "headerStyle": {
      "fontColor": "#000001",
      "backgroundColor": "#FFFFFF"
    },
    "deliveryLanguage": "en-US",
    "defaultCurrencyCode": "USD",
    "payerAuthenticationInInvoicing": "enable",
    "showVatNumber": false,
    "vatRegistrationNumber": "Inv1234",
    "shipTo": false,
    "phoneNumber": false,
    "email": false,
    "enableMerchantEmailNotifications": false,
    "customLabels": [
      {
        "key": "billTo",
        "value": "Payee name"
      }
    ],
    "customRedirectUrls": {
      "paymentAccepted": "https://example.com/success",
      "paymentRejected": "https://example.com/fail",
      "paymentPending": "https://example.com/pending"
    }
  }
}

Response to a Successful Request

{
  "submitTimeUtc": "2026-02-03T20:48:27.917947446Z",
  "invoiceSettingsInformation": {
    "merchantLogo": "data:image/JPEG;base64,/9j/4AWFhYW",
    "merchantDisplayName": "Custom Merchant Display Name",
    "customEmailMessage": "Custom merchant email message",
    "enableReminders": true,
    "headerStyle": {
      "fontColor": "#000001",
      "backgroundColor": "#FFFFFF"
    },
    "deliveryLanguage": "en-US",
    "defaultCurrencyCode": "USD",
    "payerAuthentication3DSVersion": "True",
    "showVatNumber": false,
    "phoneNumber": false,
    "shipTo": false,
    "email": true,
    "enableMerchantEmailNotifications": false,
    "customLabels": [
      {
        "key": "billTo",
        "value": "Payee name"
      }
    ],
    "customRedirectUrls": {
      "paymentAccepted": "https://example.com/success",
      "paymentRejected": "https://example.com/fail",
      "paymentPending": "https://example.com/pending"
    }
  },
  "merchantInformation": {
    "name": "API Ref Sandbox",
    "phone": "4251231234",
    "addressDetails": {
      "address1": "123 Main St",
      "city": "Bellevue",
      "state": "WA",
      "country": "us",
      "postalCode": "98005"
    }
  }
}

REST Interactive Example: Update Invoice Settings

Click this image to access the interactive code example for updating invoice settings.

Image and link to the interactive code example for updating invoice
settings. — Update Invoice Settings in the Developer Center Sandbox