Refunds
Learn about how you can model refunds and how these are processed.
Modelling Refunds
You use the Create a Refund request to issue refunds and credit notes. See Create a refund.
To create a refund, you use a POST method and the following URL:
https://services.taxamo.com/api/v2/transactions/{key}/refunds/
where {key} is the Transaction Key of the transaction that you wish to refund.
You can specify details in the URL or in the body of the request. See Refunds Schema.
The following example specifies the Transaction Key, the Line Key and the Amount in the URL:
$ curl -X 'POST' 'https://services.taxamo.com/api/v2/transactions/T60YAAAABteWsHwfho8xUz1l4fuo/refunds?line_key=SQ0Kuuvp4P9VnEzq&private_token=priv_***********&total_amount=100'
Refund Types
There are 3 types of refunds:
- Transaction: When a refund is applied to the entire transaction.
- Transaction-line: When a refund is applied to a single line of a transaction. You can only refund a single
line_keyin each Create Refund request. - Bulk Refund endpoint: When a refund is applied to multiple lines in a single request. You use the Bulk Refunds request for these types of refunds.
Transaction Refunds
To refund a transaction completely or partially, you can specify the required amount of the transaction in the total_amount field.
If no line_key or custom_id is specified, the refund is distributed to the first line and subsequent lines until the refund amount is exhausted.
For example:
{
"total_amount": 5000,
"refund_reason": "Faulty goods"
}
Transaction Line Refunds
Note
You can only refund a single
line_keyin each Create Refund request. For example, if you want to refund 3 lines in a transaction, you must send 3 requests, 1 for eachline_key.
To refund a transaction line completely or partially, you can specify the line_key for the line that you want the amount to be applied to. For example:
{
"line_key": "SQ0Kuuvp4P9VnEzq&",
"amount": 10,
"refund_reason": "Substitution"
}
Alternatively, you can use the custom_id field to identify the transaction line. This approach allows you to identify the transaction line without using the line_key. You must add the Custom ID to the transaction line before you create the refund.
For example:
{
"custom_id": "customID_1",
"amount": 10,
"refund_reason": "Replacement"
}
Bulk Refunds API
If you want to refund multiple transaction lines in a single request, you can use the Bulk Refunds request. You can use either the line_key or custom_id fields to specify which lines are to be refunded. This allows you to refund multiple transaction lines in a single request, resulting in a single credit.
US and Canadian Refunds
Some extra fields are available for US and Canadian discounts. See US and Canadian Refunds (Tax Components Schema).
Informative Transactions and Refunds
If you want to do an informative refund, you can use the informative: true field. However, the transaction line that you refund must also be informative.
Refund Processing
The following diagram shows the process flow for a refund:
Refund Processing
The steps are as follows:
- Buyer requests refund. The buyer requests a refund, a reason is provided and the refund is approved by the merchant.
- A Create a refund request is sent that contains the refund details in the attached JSON. This example uses a
custom_idto specify the transaction line:
{
"custom_id": "customID_1",
"amount": 10,
"refund_reason": "Broken goods"
}
- The Create a refund response returns the tax information in the attached JSON. Here, you can specify whether this is a transaction- or line-level refund. In this example, it is a line-level refund:
{
"refund_reason": "Broken goods",
"amount": 10.00,
"refunded_amount": 10.00,
"refund_timestamp": "2024-03-21T14:17:54Z",
"tax_amount": 0.88,
"refunded_tax_amount": 0.88,
"refunded_total_amount": 10.88,
"refund_key": "xyIovZMgd6daTA",
"total_amount": 10.88,
"refunds": [
{
"refund_reason": "Broken goods",
"amount": 10.00,
"informative": null,
"refunded_amount": 10.00,
"refund_timestamp": "2024-03-21T14:17:54Z",
"tax_amount": 0.88,
"refund_note_url": null,
"tax_rate": 8.81,
"line_key": "96LuL-XuL3s4iqZK",
"custom_id": "customID_1",
"refunded_tax_amount": 0.88,
"refund_note_number": null,
"refunded_total_amount": 10.88,
"refund_key": "xyIovZMgd6daTA",
"total_amount": 10.88,
"refund_unique_id": null,
"tax_components": [
{
"revenue": 10.00,
"tax_amount": 0.29,
"tax_result": "TAXABLE",
"city": "DENVER",
"tax_rate": 2.9,
"county": "DENVER",
"tax_authority_name": "COLORADO",
"refunded_tax_amount": 0.29,
"tax_authority_id": "4220",
"tax_name": "Sales and Use Tax",
"revenue_base": 10.00,
"percent_taxable": 1,
"jurisdiction_code": "4220",
"state_code": "CO",
"jurisdiction_type": "STATE"
},
{
"revenue": 10.00,
"tax_amount": 0.48,
"tax_result": "TAXABLE",
"city": "DENVER",
"tax_rate": 4.81,
"county": "DENVER",
"tax_authority_name": "DENVER",
"refunded_tax_amount": 0.48,
"tax_authority_id": "4372",
"tax_name": "Local Sales and Use Tax",
"revenue_base": 10.00,
"percent_taxable": 1,
"jurisdiction_code": "4372",
"state_code": "CO",
"jurisdiction_type": "CITY"
},
{
"revenue": 10.00,
"tax_amount": 0.10,
"tax_result": "TAXABLE",
"city": "DENVER",
"tax_rate": 1,
"county": "DENVER",
"tax_authority_name": "REGIONAL TRANSPORTATION DISTRICT",
"refunded_tax_amount": 0.10,
"tax_authority_id": "78135",
"tax_name": "Local Sales and Use Tax",
"revenue_base": 10.00,
"percent_taxable": 1,
"jurisdiction_code": "78135",
"state_code": "CO",
"jurisdiction_type": "DISTRICT"
},
{
"revenue": 10.00,
"tax_amount": 0.01,
"tax_result": "TAXABLE",
"city": "DENVER",
"tax_rate": 0.1,
"county": "DENVER",
"tax_authority_name": "SCIENTIFIC AND CULTURAL FACILITIES DISTRICT",
"refunded_tax_amount": 0.01,
"tax_authority_id": "78399",
"tax_name": "Local Sales and Use Tax",
"revenue_base": 10.00,
"percent_taxable": 1,
"jurisdiction_code": "78399",
"state_code": "CO",
"jurisdiction_type": "DISTRICT"
}
]
}
]
}
- Refund details are displayed on the merchant's UI. The merchant can use the returned details as they choose.
- Credit note is sent to the buyer. Where applicable, the credit note is sent to the buyer.
- Buyer receives credit note. The credit note is sent to the buyer, per the merchant's configuration. It can be sent as a URL or linked on the UI for download.
Refund Retrieval
You can use the Get transaction refunds request to retrieve a list all refunds.
Updated 9 months ago