Invoice attribute element
Learn how to use the invoice attribute element
Last updated
Learn how to use the invoice attribute element
Last updated
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 , refer to the page.
To use the element, you'll typically collect enough information from customers during so that Digital River can determine the appropriate . At this point, you can .
This prompts to call to our 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 event. That event's payload contains the invoice attribute's unique identifier.
You use this identifier to associate the invoice attribute with the . 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 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 page for information on using the element to meet invoicing requirements in these countries.
When for use with the invoice attribute element, you can either set locale
to en-US
or zh-TW
.
For both localization options, the following shows what the element presents to Taiwan-based customers who use a citizen digital certificate carrier.
createElement('invoiceAttribute', options)
invoiceAttribute
The configuration object's invoiceAttribute
contains the following properties:
country
: The shipping or billing address country of the customer getting the invoice. This value is only required if you don't specify sessionId
.
classes
style
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.
unmount()
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.
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.
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.
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.
If Digital River successfully creates an invoice attribute, then event
contains that object.
If the create invoice attribute request fails, then event
contains an error.
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.
Once you , you can use it to create an invoice attribute element.
This version of the createElement()
method has two required parameters: 'invoiceAttribute'
and a .
The element's configuration object consists of a required and an optional and .
sessionId
: The transaction's 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 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 .
When you fetch the checkout's , 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 to retrieve the schemas needed to build the invoice attribute element's data entry forms.
sellingEntity
: The 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 and then pass sessionId
.
This feature allows you to use the to determine, based on the customer's type, whether an invoice attribute is required.
In the following example, the sellingEntity.id
is DR_TAIWAN-ENTITY
. For individual customers, the 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
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 selects the member carrier option (which requires an email address), the element won't display that data collection field.
For details, refer to .
For details, refer to .
If this method is successful, then the is triggered.
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 .
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 to reactivate the element and make it visible.
You should handle on complete by passing the event's id
to your backend and using that value to set invoiceAttributeId
in the body of a request. This associates the invoice attribute with the .
You can also respond to the event by calling or to close the element and make it no longer visible to customers.