Invoice attribute element

Learn how to use the invoice attribute element

The invoice attribute element collects customer data needed for e-invoicing purposes and then uses that data to create an invoice attribute.

For more details on how to use the element with specific selling entities, refer to the Handling e-invoicing requirements page.

How it works

To use the element, you'll typically collect enough information from customers during checkouts so that Digital River can determine the appropriate selling entity. At this point, you can create an invoice attribute element.

This prompts DigitalRiver.js to call to our country specification service to get the schemas it needs to build a data collection form. Once the form loads on your front end, customers select the appropriate options, enter their personal information, and click the submit button.

DigitalRiver.js then packages the form's data in a create invoice attribute request sent to our tax service. If that service successfully creates an invoice attribute, you receive the on complete event. That event's payload contains the invoice attribute's unique identifier.

You use this identifier to associate the invoice attribute with the checkout. Our tax service then attempts to validate the invoice attribute, and, if that validation proves successful, the object's data is added to the checkout.

At the time of order creation, our tax service once again validates the invoice attribute and Digital River's commerce system persists this object data. This allows our reporting services to periodically retrieve this data and transmit it to third-party e-invoicing services integrated with the appropriate tax agencies in each supported country.

Refer to the Handling e-invoicing requirements page for information on how to use the element to meet invoicing requirements in these countries.

Localizing the invoice attribute element

When instantiating a DigitalRiver object for use with the invoice attribute element, you can either set locale to en-US or zh-TW.

let digitalriver = new DigitalRiver("YOUR_PUBLIC_API_KEY", {
     "locale": "zh-TW"
})r

For both localization options, the following shows what the element presents to Taiwan-based customers who use a citizen digital certificate carrier.

Note that the element also helps customers properly format their entries for certain fields.

en-US: English (United States)

zh-TW: Chinese (Taiwan)

createElement('invoiceAttribute', options)

Once you instantiate a Digital River object, you can use it to create an invoice attribute element.

This version of the createElement() method has two required parameters: 'invoiceAttribute' and a configuration object.

let invoiceAttribute = digitalriver.createElement('invoiceAttribute', options)

Invoice attribute element configuration object

The element's configuration object consists of a required invoiceAttribute and an optional classes and style.

const options = {
    invoiceAttribute: {
        sessionId: "e2f7e5ee-4c14-494f-bd14-2a9f3a375da3",
        // country, type and sellingEntity are not needed if sessionId is provided
        // country: "TW",
        // sellingEntity: "DR_TAIWAN-ENTITY"
        // type: "individual",
        // email: "[e-mail]"
    },
    classes: {
        base: "DRElement",
        complete: "invoiceAttribute-complete",
        empty: "invoiceAttribute-empty",
        focus: "invoiceAttribute-focus",
        invalid: "invoiceAttribute-invalid"
    },
    style: {
        base: {
            color: "#495057",
            height: "35px",
            fontSize: "1rem",
            fontFamily: "apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif",
            ":hover": {
                color: "#ccc",
            }
        },
        complete: {
            ":hover": {
                color: "#495057",
            },
        },
         empty: {
            ":hover": {
                color: "#dddddd",
            },
        },
        focus: {
            ":hover": {
                color: "#135bef",
            },
        },
        invalid: {
            color: "red"
        }
   }
};

let invoiceAttribute = digitalriver.createElement('invoiceAttribute', options)

invoiceAttribute

The configuration object's invoiceAttribute contains the following properties:

• sessionId: The transaction's payment session identifier. This value is required if you don't specify country and sellingEntity. However, if you do pass sessionId, then your integration must have already collected the customer's shipping and/or billing information and used it to update the checkout with a shipTo.address.country and/or billTo.address.country. Once this is done, Digital River will have the data it needs to calculate the checkout's sellingEntity. When you fetch the checkout's payment.session.id , pass that value to sessionId, and create the element, DigitalRiver.js looks up the transaction's country and selling entity in the payment session and calls to the Country Specs API to retrieve the schemas needed to build the invoice attribute element's data entry forms.

• country: The shipping or billing address country of the customer getting the invoice. This value is only required if you don't specify sessionId.

• sellingEntity: The selling entity of the transaction. This value is only required if you don't specify sessionId.

• type: This optional parameter represents the type of customer requesting the invoice. The acceptable values are individual or business. You can either set type or set the checkout's customerType and then pass sessionId. This feature allows you to use the on ready event to determine, based on the customer's type, whether an invoice attribute is required. In the following example, the checkout's sellingEntity.id is DR_TAIWAN-ENTITY. For individual customers, the on ready event indicates that an invoicing system exists and that customer's must supply their invoice information. The same event type indicates that no invoice attribute requirements exist for business customers

Individual

on ready event

{
    "hasInvoices": true,
    "invoiceRequired": true,
    "individual": [
        {
            "type": "tw_individual_mobile_barcode",
            "attributes": [
                {
                    "attributeName": "MOBILE_BARCODE",
                    "isRequired": true
                }
            ]
        },
        {
            "type": "tw_individual_citizen_cert",
            "attributes": [
                {
                    "attributeName": "CITIZEN_DIGITAL_CERT",
                    "isRequired": true
                }
            ]
        },
        {
            "type": "tw_individual_member_carrier",
            "attributes": [
                {
                    "attributeName": "MEMBER_CARRIER",
                    "isRequired": true
                }
            ]
        },
        {
            "type": "tw_individual_donate",
            "attributes": [
                {
                    "attributeName": "CHARITY_NAME",
                    "isRequired": true
                }
            ]
        }
    ],
    "hasIndividualInvoiceTypes": true,
    "elementType": "invoiceattribute"
}

Business

on ready event

{
    "hasInvoices": false,
    "elementType": "invoiceattribute"
}

• email: The element won't prompt a customer for their email address if specified. This is useful if your integration collects a customer's email address before creating the invoice attribute element. If this is the case, you can pass email and prevent customers from having to enter the same information twice during the checkout process. For example, if invoiceAttribute contains email and a customer getting a Taiwanese eGUI selects the member carrier option (which requires an email address) , the element won't display that data collection field.

email not specified

email specified

classes

For details, refer to Custom classes

style

For details, refer to Custom styles

mount()

The mount() method displays the invoice attribute element in the container you designate. The method has one required parameter: the id of the div that should hold the element.

...
<div id="invoice-attribute"></div>
...
invoiceAttribute.mount('invoice-attribute');
...

If this method is successful, then the on ready event is triggered.

unmount()

The unmount() method removes the invoice attribute element from the page. Once called, the element is no longer visible to customers. However, you can later re-add the element to div by invoking mount().

...
invoiceAttribute.unmount();
...

destroy()

The destroy() method removes the invoice attribute element from the page and deactivates the element's functionality. Once the method is invoked, you can't call mount() to reactivate the element and make it visible.

...
invoiceAttribute.destroy();
...

on('ready', handler)

When the element opens and can accept user input, the on ready event is triggered. This version of on() has two required parameters: 'ready' and an event handler.

invoiceAttribute.on('ready', function(event) {
  // element is ready and can accept user input
})

The event contains all the possible data fields that might be displayed to customers in the element. The fields that are displayed depend on what options customers select.

The ready event is useful for information and testing purposes, but your integration doesn't necessarily have to implement any code to handle it.

For example, the payload of the following on ready event indicates that the customer's country (Taiwan) has an e-invoicing system for individual customers and they must provide invoice information.

The element will ask customers whether to select the mobile barcode carrier, citizen digital certificate carrier, or member carrier option. It also allows customers to bypass the carrier option entirely and instead designate a charity. Whatever option customers select, the event indicates that the element won't allow them to submit the form until they've specified a value.

{
    "hasInvoices": true,
    "invoiceRequired": true,
    "individual": [
        {
            "type": "tw_individual_mobile_barcode",
            "attributes": [
                {
                    "attributeName": "MOBILE_BARCODE",
                    "isRequired": true
                }
            ]
        },
        {
            "type": "tw_individual_citizen_cert",
            "attributes": [
                {
                    "attributeName": "CITIZEN_DIGITAL_CERT",
                    "isRequired": true
                }
            ]
        },
        {
            "type": "tw_individual_member_carrier",
            "attributes": [
                {
                    "attributeName": "MEMBER_CARRIER",
                    "isRequired": true
                }
            ]
        },
        {
            "type": "tw_individual_donate",
            "attributes": [
                {
                    "attributeName": "CHARITY_NAME",
                    "isRequired": true
                }
            ]
        }
    ],
    "hasIndividualInvoiceTypes": true,
    "elementType": "invoiceattribute"
}

on('complete', handler)

Once customers enter properly formatted data in all of the element's required fields and then submit the form, the on complete event is triggered. This version of on() requires two parameters: 'complete' and an event handler.

invoiceAttribute.on('complete', function(event) {
     if(event.error) {
        //handle error
     } else {
        console.log('invoice attribute success', event);
        //send the invoice attribute's id to your back-end and attach it to the checkout
     }
});

If Digital River successfully creates an invoice attribute, then event contains that object.

Ready event (success)

{
    "id": "94fe7ed9-f570-4049-aa37-979a50f0097d",
    "type": "tw_individual_donate",
    "attributes": {
        "CHARITY_NAME": "財團法人瑪利亞社會福利基金會",
        "CHARITY_CODE": "880"
    },
    "createdTime": "2022-06-06T21:17:41Z",
    "updatedTime": "2022-06-06T21:17:41Z",
    "liveMode": false,
    "elementType": "invoiceattribute"
}

You should handle on complete by passing the event's id to your back-end and using that value to set invoiceAttributeId in the body of a POST/checkouts/{id} request. This associates the invoice attribute with the checkout.

curl --location --request POST 'https://api.digitalriver.com/checkouts/7da8bcbc-a139-440e-a684-5eb5f1804995' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Secret API Key>' \
...
--data-raw '{
    "invoiceAttributeId": "de2c8ced-b788-463f-93fb-0b274bc7f9bf"
}'

You can also respond to the event by calling unmount() or destroy() to close the element and make it no longer visible to customers.

If the create invoice attribute request fails, then event contains an error.

Ready event (fail)

{
    "error": {
        "type": "no_network",
        "errors": [
            {
                "message": "Please check your network connection."
            }
        ]
    },
    "elementType": "invoiceattribute"
}

Since the element validates the format of customer-entered data, errors are typically only returned when the invoice attribute service is unreachable, or customers are experiencing connection issues. In these cases, we recommend displaying a message such as “Something went wrong. Try again later” to customers.

Complete example

<html>
    <head>
        <link href="https://js.digitalriverws.com/v1/css/DigitalRiver.css" rel="stylesheet">
        <script src="https://js.digitalriverws.com/v1/DigitalRiver.js"></script>
    </head>
    <body>
        <div id="invoice-attribute"></div>

        <script>
            window.addEventListener('load', function() {
                const options = {
                    locale: 'zh-TW'
                }
                const digitalriver = new DigitalRiver(options);

                const invoiceAttributeOptions = {
                    invoiceAttribute: {
                        sessionId: "e2f7e5ee-4c14-494f-bd14-2a9f3a375da3",
                        // country and sellingEntity are not needed if sessionId is provided
                        // country: "CN",
                        // sellingEntity: "DR_CHINA-ENTITY"
                        // optional properties:
                        // type: "individual"
                        // email: "[e-mail]"
                    },
                    classes: {
                        base: "DRElement",
                        complete: "invoiceAttribute-complete",
                        empty: "invoiceAttribute-empty",
                        focus: "invoiceAttribute-focus",
                        invalid: "invoiceAttribute-invalid"
                    },
                    style: {
                        base: {
                            color: "#495057",
                            height: "35px",
                            fontSize: "1rem",
                            fontFamily: "apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Helvetica Neue,Arial,sans-serif",
                            ":hover": {
                                color: "#ccc",
                            }
                        }
                    }
                };

                let invoiceAttribute = digitalriver.createElement('invoiceAttribute', invoiceAttributeOptions);
                invoiceAttribute.mount('invoice-attribute');

                invoiceAttribute.on('ready', function(details) {
                    console.log(details);
                });

                invoiceAttribute.on('complete', function(details) {
                    if(event.error) {
        //handle error
     } else {
        if(event.error) {
        //handle error
     } else {
        console.log('invoice attribute success', event);
        //send the invoice attribute's id to your back-end and attach it to the checkout
     }
     }
                });
            });
        </script>
    </body>