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.
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 make a 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 that gets 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 that are integrated with the appropriate tax agencies in each supported country.
For information on how to use the element to meet invoicing requirements in these countries, refer to the Handling e-invoicing requirements page.
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 opt to use a citizen digital certificate carrier.
For certain fields, note that the element also helps customers properly format their entries.
en-US: English (United States)
zh-TW: Chinese (Taiwan)


Once you instantiate a Digital River object, you can use it to 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)
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: "[email protected]"
},
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)
The configuration object's
invoiceAttribute
contains the following properties:sessionId
: The transaction's payment session identifier. This value is required if you don't specifycountry
andsellingEntity
. However, if you do passsessionId
, then your integration must have already collected the customer's shipping and/or billing information and used it to update the checkout with ashipTo.address.country
and/orbillTo.address.country
. Once this is done, Digital River has the data it needs to calculate the checkout'ssellingEntity
. When you fetch the checkout'spayment.session.id
, pass that value tosessionId
, and create the element, DigitalRiver.js looks up the transaction's country and selling entity in the payment session and makes a call 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 specifysessionId
.sellingEntity
: The selling entity of the transaction. This value is only required if you don't specifysessionId
.type
: This optional parameter represents the type of customer requesting the invoice. The acceptable values areindividual
orbusiness
. You can either settype
or set the checkout'scustomerType
and then passsessionId
. 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'ssellingEntity.id
isDR_TAIWAN-ENTITY
. For individual customers, the on ready event indicates that an invoicing system exists and that customer's must supply their invoice information. For business customers, the same event type indicates that no invoice attribute requirements exist.
Individual
Business
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"
}
on ready event
{
"hasInvoices": false,
"elementType": "invoiceattribute"
}
email
: If specified, the element won't prompt customers for their email address. This is useful if your integration collects a customer's email address prior to creating the invoice attribute element. If this is the case, you can passemail
and prevent customer's from having to enter the same information twice during the checkout process. For example, ifinvoiceAttribute
containsemail
and a customer getting a Taiwanese eGUI selects the member carrier option (which requires an email address) then the element won't display that data collection field.
email not specified
email specified


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');
...
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();
...
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();
...
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 actually displayed depends 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 in this case) has an e-invoicing system in place for individual customers and they are required to provide invoice information.
The element will ask customers whether they want to select the mobile barcode carrier, citizen digital certificate carrier, or member carrier option. It also gives customers the ability 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"
}
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"
}'
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, please try again later” to customers.
<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: "[email protected]"
},
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>
Last modified 5mo ago