Refunds
Refunds are issues to remunerate already collected amounts for a number of reasons.
To integrate refunds with your checkout process, use the Refund Transaction request. See Refund Transactions.
You use the fields in the JSON to specify the refund details. See Refund Object Fields.
The following types of refund are available:
- Transaction Refund: This is when you want to refund the entire amount of a singe transaction. You use the Transaction Key to specify the transaction that you want to refund.
- Transaction Line Refund: This is when you want to refund one or more transaction lines in a transaction. You use the
line_keyto do so. - Amount-based Refund: This is when you want to refund a specific amount in a refund. You can do so for tax inclusive or exclusive total amounts.
Credit notes are also issued once a refund is processed.
Refund Processing
Refunds are modelled using the Refund Transaction request. An example process flow is explained in the following graphic:
The example process flow is as follows. This is a simplified example. As the API is highly customizable, your deployment can vary in any number of ways.
- Buyer requests refund: The buyer requests a refund by whatever means are allowed on the merchant's store.
- Merchant issues a refund to the buyer: The merchant decides this is a valid refund and issues the refund in their system that is in their e-commerce store or via their payment provider.
- Refund Transaction request sent to Vertex for Marketplaces: You use the Refund Transaction request to integrate the refunds in Vertex for Marketplaces with your store's refunds. The request specifies details like the amounts and so on. This is processed and useful information is returned in the response. A credit note may also be sent to the liable party. This can be the buyer or seller and is dependent on other settings.
- Refund issued in V4M: The request is processed by Vertex.
- Credit sent per settings to buyer or seller: A credit note is sent to the liable party, this can be either the buyer or seller. If it is the buyer, it is sent to the email specified in the
buyer_emailfield. If this is not specified, it is sent to the merchant. - Buyer receives credit note.
Full Refund
To issue a complete refund of an entire transaction, you can use the Refund Transaction request.
For example:
POST https://marketplace.taxamo.com/api/v3/marketplace/transactions/[Key]/refunds
where [Key] is the key of the transaction that you want to refund. This value is returned by the Store Transaction request in the key field.
Transaction Line Refund
To refund a specific transaction line, you need to specify the line_key value for the lines you want to refund.
This type of refund refunds the entire transaction line. You cannot refund a partial amount for a transaction line.
The following example is a refund for the "line_key": abc12120913 line key:
{
"refunds": [
{
"refund_reason": "Defect",
"line_key": "abc12120913",
"refund_note_number": 128912312,
"refund_unique_reference": "FGHFH58595903",
}
]
}
'
Amount-based Refund
You can create refunds of amounts that are tax inclusive or exclusive. You can use the following fields to do so:
refund_total_amount: Use this field to for a tax inclusive refund.refund_amount: Use this field for for a tax exclusive refund.
The service will return both tax inclusive and exclusive amounts so you can decide which to use.
You can only refund the amount of a transaction. You cannot refund a partial amount of a transaction line.
For example, the following request is for a tax inclusive amount of 100:
{
"refunds": [
{
"refund_total_amount": 100,
"refund_reason": "Defect",
"line_key": "abc12120913",
"refund_note_number": 1218239121,
"refund_unique_reference": "AFSP2343054"
}
]
}
'
The following example is for a tax exclusive price of 75:
{
"refunds": [
{
"refund_reason": "Defect",
"line_key": "abc12120913",
"refund_note_number": 128912312,
"refund_unique_reference": "FGHFH58595903",
"refund_amount": 75
}
]
}
'
Example Response
The following is an example of a response for a refund that is sent back by the Request Transaction request:
{
"transaction": {
"ship_to_address": {
"city": "Berlin",
"country_code": "DE",
"postal_code": "BA1 2AP",
"street_name": "30 Monmouth Street",
"tax_region": "EU"
},
"description": "OSS 1a REG_EU_B2C; Goods EU, seller EU",
"amount": 149.99,
"purchase_order_number": "1",
"required_fields": {
"tax_required_fields": [],
"storage_required_fields": []
},
"refunded_amount": 3.36,
"marketplace_code": "Test_Marketplace",
"tax_country_codes": "DE",
"key": "Psc2oyAAAA-3uCk8XCmMBOCMuhZ9kol5uJ2DhZg",
"tax_amount": 28.5,
"update_date": "2023-07-03",
"invoice_timestamp": "2023-07-03T05:36:46Z",
"confirm_timestamp": "2023-07-03T05:36:49Z",
"tax_liability_owner_codes": "pl_oss",
"create_timestamp": "2023-07-03T05:36:46Z",
"transaction_lines": [
{
"description": "Handmade Granite Fish",
"reverse_charge": false,
"amount": 149.99,
"refunded_amount": 3.36,
"tax_engine_additional_parameters": [
{
"param": "FLEX.output.Partition",
"value": "ECOMM_test"
}
],
"tax_rule_applied": "physical-tax",
"unit_price": 149.99,
"taxes": [
{
"tax_type": "VAT",
"cached": true,
"imposition_type": "VAT",
"tax_jurisdiction_code": "78283",
"tax_amount": 28.50,
"tax_calculation_rule_id": "v14507680",
"tax_base_amount": 149.99,
"tax_jurisdiction_type": "COUNTRY",
"rate": 19,
"tax_authority_name": "GERMANY",
"rate_type": "Standard",
"tax_authority_id": "78283",
"tax_name": "European VAT physical",
"imposition": "VAT",
"amount_fraction_taxable": 1
}
],
"carrier_id": "DHL",
"tax_amount": 28.50,
"tax_liability_rule": "physical-shipment-inside-EU-seller-inside-EU",
"seller_tax_number": "DE999999999",
"tax_region": "EU",
"invoice_place": "pl_oss Street 1, Warsaw",
"invoice_number": "DE2023-40",
"tax_exempt": false,
"tax_country_code": "DE",
"special_tax_scheme": "OSS",
"line_key": "vHNDqYMMGZf4A4_7",
"custom_id": "line_1",
"refunded_tax_amount": 0.64,
"tax_address_kind": "ship_to_address",
"ship_from_address": {
"country_code": "PL",
"tax_region": "EU"
},
"tax_engine": "oseries",
"invoice_status": "R",
"parcel_reference": "0",
"kind": "b2c",
"product_reference_number": "",
"invoice_image_url": "invoice_url",
"tax_number_service": "vies",
"refunded_total_amount": 4.00,
"product_class": "P",
"tax_liability_owner_code": "pl_oss",
"custom_rules_applied": [],
"line_num": 1,
"is_seller_permanent": true,
"quantity": 1.000000000000,
"invoice_capable": true,
"total_amount": 178.49,
"seller_code": "pl_oss",
"product_cn_code": "0870",
"invoice_image_url_secret": "xRKQL_NWI0VBdnOs",
"refunds": [
{
"refund_reason": "Refund - OSS 2a REG_EU_B2C; Goods EU, seller outside EU",
"refund_amount": 3.36,
"refund_timestamp": "2023-07-03T05:36:55Z",
"refund_note_url": "credit_note_url",
"refund_tax_amount": 0.64,
"refund_note_number": 1,
"refund_note_subnumber": 1,
"refund_key": "WFu-v6uBKPOJwknPUDgChw",
"custom_rules_applied": [],
"refund_total_amount": 4.00
}
],
"tax_entity_name": "Germany",
"tax_supported": true
}
],
"discounts": [],
"location_evidence": {},
"refunded_tax_amount": 0.64,
"product_classes": "P",
"billing_address": {
"city": "Berlin",
"country_code": "DE",
"postal_code": "BA1 2AP",
"street_name": "30 Monmouth Street",
"tax_region": "EU"
},
"status": "C",
"refunded_total_amount": 4.00,
"update_timestamp": "2023-07-03T05:36:46Z",
"buyer_name": "Terry John",
"tax_timestamp": "2023-07-03T05:36:46Z",
"total_amount": 178.49,
"invoice_image_url_secret": "xRKQL_NWI0VBdnOs",
"currency_code": "EUR"
}
}
Refunds for SUT
Sales and Use Tax (SUT) is used for US transactions. SUT does not supports partial amount refunds. This means you can refund a transaction or line for the full amount but not for a partial amount.
In other words, SUT supports the following type of refunds:
- Transaction Refund: You refund an entire transaction for the full amount.
- Transaction Line Refund: You can refund the full amount of one or more transaction lines in the same transaction.
You cannot refund partial amounts of a transaction line.
Updated 10 months ago