Links

Handling e-invoicing requirements

Learn how to handle e-invoicing requirements in specific countries
On this page you'll find background information on the unique e-invoicing requirements that exist in Taiwan along with a high-level overview of how to build an integration that satisfies them.

Background

You can use the Digital River APIs to make domestic sales in Taiwan. More specifically, if the checkout contains physical goods, then those goods must both ship from and ship to Taiwan; and if the checkout only contains digital goods, then the goods must bill to that same country.
When these conditions are met, we assign Digital River Taiwan as the transaction's selling entity.
If this is the assigned entity, then your integration needs to collect specific information from customers so that it can get added to a Government Uniform Invoice (GUI).
These invoices are used by the Taiwanese government to boost tax revenue and minimize tax avoidance. Before issuing them to customers, companies must apply to the government for a series of 8-digit GUI numbers.
Every two months, companies inform the tax authorities how many GUI numbers they issued (along with corresponding sales revenue) and how many GUI numbers remain unused. This allows the government to better determine whether companies are engaging in tax avoidance.
Recently, in an attempt to reduce paper waste, Taiwan introduced eGUI requirements. Digital River's e-invoicing service helps you comply with these new mandates.
In these B2C transactions, customers must designate a media, called a "carrier", that they want to use to associate the GUI number with their personal identity. Alternatively, customers can elect to donate their GUI number to a charity that they select from a predefined list.
To collect this information, you must create an invoice attribute element.
In B2B transactions, customers don't designate a carrier. They must, however, supply their tax identifier for inclusion on the eGUI. If customers fail to do so, they can't deduct their business expenses. So, if customers are checking out as a business entity, you'll need to collect this information by using either the tax identifier element or, in the case of registered checkouts, giving customers the option of selecting a saved tax identifier.
After the transaction is complete, the GUI numbers are entered into a government-run lottery. This incentivizes customers to (1) only do business with merchants that issue GUIs and (2) request GUIs from merchants. Customers holding winning numbers are later notified that they have won a cash prize or the money is donated to the selected charity.

Integrating with the e-invoice service

The following section describes one possible approach you might use to implement a flow for a guest checkout that is assigned a sellingEntity.id of DR_TAIWAN-ENTITY.
In registered checkouts, you may decide to implement additional operations that save and/or retrieve a customer's tax identifier.
After customers initiate checkout, you could use a control (such as a radio button or checkbox) to determine whether they're purchasing the goods as an individual or business entity and a form to collect their shipping and/or billing information.
If customers are making the purchase as a business entity, then your forms should have a field for them to enter their organization/company name and require them to supply this information before they can submit the form.
Add a click event handler to the form's submit button that processes the event by using the data collected from customers to set the checkout's customerType, shipTo and/or billTo.
If customerType is business, then make sure you set shipTo.organization and/or billTo.organization.
POST /checkouts/{id}
curl --location --request POST 'https://api.digitalriver.com/checkouts/7890d7c5-e15a-4827-80b0-8652de82ad04' \
...
--header 'Authorization: Bearer <Secret API Key>' \
...
--data-raw '{
"customerType": "business",
"shipTo": {
"address": {
"line1": "台南市安平區光州路3號",
"city": "Tainan",
"postalCode": "708",
"state": "Taiwan",
"country": "TW"
},
"name": "John Doe",
"organization": "Acme, Inc."
},
"billTo": {
"address": {
"line1": "台南市安平區光州路3號",
"city": "Tainan",
"postalCode": "708",
"state": "Taiwan",
"country": "TW"
},
"name": "John Doe",
"organization": "Acme, Inc."
}
}'
In the response, determine whether the checkout's sellingEntity.id is DR_TAIWAN-ENTITY. If that's the case, check whether customerType is individual or business.
Checkout
{
"id": "7890d7c5-e15a-4827-80b0-8652de82ad04",
...
"customerType": "individual",
...
"sellingEntity": {
"id": "DR_TAIWAN-ENTITY",
"name": "Digital River Taiwan"
},
...
}
If customerType is individual, retrieve payment.session.id, pass it to sessionId in the invoice attribute element's configuration object, and then create and mount the element. When you receive the on complete event, retrieve id from the event's payload and pass it as invoiceAttributeId in the body of an update checkout request.
If customerType is business, retrieve the checkout's payment.session.id, pass it to sessionId in the tax identifier element's configuration object and then create and mount the element. Handle on change by checking the event's payload to determine whether elementType is taxidentifier and complete is true. If this is the case, retrieve identifier.type and identifier.value and pass them as type and value in the body of a create tax identifier request. From the response, retrieve id and pass it as taxIdentifiers[].id in the body of an update checkout request.
Once that's done, you can collect the customer's shipping choice (if applicable) and payment. For more details refer to:
Once you submit the create order request, initiate fulfillment operations, and then receive the event with a type of order.complete, you might decide to use its data.object to build an order summary page on your site.
For details, refer to Handling the order complete event.
As part of that operation, you can determine whether the event's data.object (which represents an order) contains invoiceAttribute or taxIdentifiers[].
If invoiceAttribute is populated, then you can display each of its attributes on the summary page. Similarly, if a taxIdentifiers[] exists, you can display its value on that same page.
Digital River has integrated with a third-party service that gives customers access to all of their eGUIs. As a result, you're not required to provide this information to customers on your site. In B2C transactions, the service adds the eGUIs to a customer-accessible website managed by the government. In B2B transactions, customers are sent an email that contains the eGUI number, a link to the national lottery site, and a PDF attachment of the invoice.
For each invoiceAttribute.type, the following provides an example of the data contained in order.complete.
tw_individual_mobile_barcode
tw_individual_member_carrier
tw_individual_citizen_cert
tw_individual_donate
order.complete
{
"id": "32d36468-9c01-49a2-a4d1-31f5abf01308",
"type": "order.complete",
"data": {
"object": {
"id": "231067550336",
...
"invoiceAttribute": {
"id": "d9c6e7b2-3646-418b-8afa-a8cc9e86feda",
"type": "tw_individual_mobile_barcode",
"attributes": {
"MOBILE_BARCODE": "/ABC+123"
},
...
},
...
}
},
...
order.complete
{
"id": "b8da3ffc-6d40-4e7b-9677-eb0ab28525c4",
"type": "order.complete",
"data": {
"object": {
"id": "230957950336",
...
"invoiceAttribute": {
"id": "9557110c-b0ff-4ca3-bb3a-7f0711c31a86",
"type": "tw_individual_member_carrier",
"attributes": {
"MEMBER_CARRIER": "[email protected]"
},
...
},
...
}
},
...
}
order.complete
{
"id": "3e18abe0-8b84-4cd8-ab61-154f109319a8",
"type": "order.complete",
"data": {
"object": {
"id": "230957170336",
...
"invoiceAttribute": {
"id": "6817148d-09eb-451e-b17e-3c47d7e7ff36",
"type": "tw_individual_citizen_cert",
"attributes": {
"CITIZEN_DIGITAL_CERT": "AB12345678901234"
},
...
},
...
}
},
..."
}
order.complete
{
"id": "4276f7cf-a298-4c1c-b13c-c8cfe4be1077",
"type": "order.complete",
"data": {
"object": {
"id": "230958000336",
...
"invoiceAttribute": {
"id": "97144bc7-babb-435d-a4ff-eebac26196df",
"type": "tw_individual_donate",
"attributes": {
"CHARITY_NAME": "財團法人台東基督教醫院",
"CHARITY_CODE": "299"
},
...
},
..."
}
},
...
}