Refunds
Read about how you can model 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.
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.
In addition, you can also specify amounts as tax inclusive or exclusive.
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.
- Vertex for e-Commerce user issues refund to the buyer: You (the merchant/Vertex for e-Commerce user) 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 e-Commerce: You use the Refund Transaction request to integrate the refunds in Vertex for e-Commerce with your store or applications 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 Vertex for e-Commerce: The request is processed by the service.
- Refund details returned in the API response.
- Credit sent per settings to buyer or seller: A credit note is sent to the email specified in the
buyer_emailfield. - Buyer receives credit note.
Transaction refund
To issue a complete refund of an entire transaction, you can use the Refund Transaction request.
For example:
POST https://{service_url}/api/v3/seller/transactions/{key}/refunds
where
service_urlis the service's URL.[Key]is the key of the transaction that you want to refund. This value is returned by the Store Transaction request in thetransaction_keyfield.
You must also specify the refund amount, reason, and line keys in the body of the request:
{
"refunds": [
{
"line_key": "{{transaction_line_key_1}}",
"refund_amount": "100",
"refund_reason": "Partial refund of line 1"
},
{
"line_key": "{{transaction_line_key_2}}",
"refund_amount": "20",
"refund_reason": "Full refund of line 2"
}
]
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": "{{transaction_line_key_1}}" line key:
{
"refunds": [
{
"line_key": "{{transaction_line_key_1}}",
"refund_amount": "100",
"refund_reason": "Partial refund of line 1"
},
]
The transaction line response looks like this:
"refunds": [
{
"refund_reason": "Defect",
"refund_amount": 20.00,
"refund_timestamp": "2025-03-27T11:14:02Z",
"refund_note_url": "(URL)",
"refund_tax_amount": 1.62,
"refund_note_number": 1,
"refund_note_subnumber": 1,
"refund_key": "GxdnMeSt5UPlrEUsHHKsXg",
"refund_total_amount": 21.62
}
],
Tax inclusive and exclusive amounts
You can create refunds of amounts that are tax inclusive or exclusive. This mirrors how amounts work generally. See Amounts and Pricing.
You can use the following fields to model amounts for refunds:
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",
}
]
}
'
The following example is for a tax exclusive price of 75:
{
"refunds": [
{
"refund_reason": "Defect",
"line_key": "abc12120913",
"refund_amount": 75
}
]
}
'
Example response
The following is an example of a response to the Refund Transaction request:
{
"transaction": {
"ship_to_address": {
"city": "Big city",
"country_code": "GB",
"postal_code": "00000",
"street_name": "Street name",
"address_detail": "2nd fl",
"building_number": "100a",
"tax_region": "GB"
},
"description": "Transaction description",
"amount": 200,
"required_fields": {
"tax_required_fields": [],
"storage_required_fields": []
},
"refunded_amount": 120.00,
"marketplace_code": "V4EDemo",
"tax_country_codes": "GB",
"key": "PSqiwAQAAPJFqz_jLCgzo6VMqW1xn5klQ9goY6w",
"tax_amount": 40,
"update_date": "2025-03-28",
"invoice_timestamp": "2025-03-01T12:00:00Z",
"confirm_timestamp": "2025-03-28T07:06:07Z",
"tax_liability_owner_codes": "",
"create_timestamp": "2025-03-28T07:01:36Z",
"transaction_lines": [
{
"description": "Product 1",
"reverse_charge": false,
"amount": 100.00,
"refunded_amount": 100.00,
"tax_engine_additional_parameters": [
{
"param": "FLEX.output.FlexCode25",
"value": "OSC-AK-TEST"
}
],
"tax_rule_applied": "physical-tax",
"unit_price": 100.00,
"taxes": [
{
"tax_type": "VAT",
"imposition_type": "VAT",
"tax_jurisdiction_code": "78295",
"tax_amount": 20.0,
"tax_calculation_rule_id": "v301086121",
"exempt_amount": 0.0,
"tax_base_amount": 100,
"tax_jurisdiction_type": "COUNTRY",
"rate": 20,
"taxable_amount": 100.0,
"tax_authority_name": "UNITED KINGDOM",
"rate_type": "Standard",
"tax_authority_id": "78295",
"tax_name": "VAT physical",
"non_taxable_amount": 0.0,
"imposition": "VAT",
"amount_fraction_taxable": 1
}
],
"tax_amount": 20.00,
"seller_tax_number": "GB123456789",
"tax_region": "GB",
"invoice_place": "Postal address line 1, Postal address line 2, Postal address line 3",
"invoice_number": "GB2025-1",
"tax_exempt": false,
"additional_currencies": {
"invoice": {
"amount": 82.59,
"currency_code": "GBP",
"fx_date": "2025-02-28T12:00:00Z",
"fx_rate": 0.825900231252,
"fx_source": "source_bankofengland",
"total_amount": 99.11,
"tax_amount": 16.52
}
},
"tax_country_code": "GB",
"line_key": "UwJ85ua2PYVf48bX",
"custom_id": "",
"refunded_tax_amount": 20.00,
"tax_address_kind": "ship_to_address",
"ship_from_address": {
"country_code": "GB",
"tax_region": "GB"
},
"tax_engine": "oseries",
"invoice_status": "R",
"kind": "b2c",
"product_tax_code": {
"class": "TPP/Goods"
},
"invoice_image_url": "(URL)",
"tax_number_service": "tax.service.gov.uk",
"refunded_total_amount": 120.00,
"product_class": "P",
"custom_rules_applied": [],
"line_num": 1,
"is_seller_permanent": true,
"quantity": 1.000000000000,
"invoice_capable": true,
"total_amount": 120.00,
"seller_code": "V4EDemo_Seller3",
"invoice_image_url_secret": "id4-IlvR2vU4GMn7",
"refunds": [
{
"refund_reason": "Refund line X",
"refund_amount": 100.00,
"refund_timestamp": "2025-03-28T07:16:37Z",
"refund_note_url": "(URL)",
"refund_tax_amount": 20.00,
"refund_note_number": 1,
"refund_note_subnumber": 1,
"refund_key": "OrTyp5dwX4pL0AtM1qmCJg",
"refund_total_amount": 120.00
}
],
"tax_entity_name": "United Kingdom",
"tax_supported": true
},
{
"description": "Shipping",
"reverse_charge": false,
"amount": 100.00,
"refunded_amount": 20.00,
"tax_engine_additional_parameters": [
{
"param": "FLEX.output.FlexCode25",
"value": "OSC-AK-TEST"
}
],
"tax_rule_applied": "postage-insurance-vat",
"unit_price": 100.00,
"taxes": [
{
"tax_type": "VAT",
"imposition_type": "VAT",
"tax_jurisdiction_code": "78295",
"tax_amount": 20.00,
"tax_calculation_rule_id": "v301086121",
"exempt_amount": 0.0,
"tax_base_amount": 100.00,
"tax_jurisdiction_type": "COUNTRY",
"rate": 20,
"taxable_amount": 100.0,
"tax_authority_name": "UNITED KINGDOM",
"rate_type": "Standard",
"tax_authority_id": "78295",
"tax_name": "VAT physical",
"non_taxable_amount": 0.0,
"imposition": "VAT",
"amount_fraction_taxable": 1
}
],
"tax_amount": 20.00,
"seller_tax_number": "GB123456789",
"tax_region": "GB",
"invoice_place": "Postal address line 1, Postal address line 2, Postal address line 3",
"invoice_number": "GB2025-1",
"additional_currencies": {
"invoice": {
"amount": 82.59,
"currency_code": "GBP",
"fx_date": "2025-02-28T12:00:00Z",
"fx_rate": 0.825900231252,
"fx_source": "source_bankofengland",
"total_amount": 99.11,
"tax_amount": 16.52
}
},
"tax_country_code": "GB",
"line_key": "bjjMpRAXWINsH9uZ",
"custom_id": "",
"refunded_tax_amount": 4.00,
"tax_address_kind": "ship_to_address",
"ship_from_address": {
"country_code": "GB",
"tax_region": "GB"
},
"tax_engine": "oseries",
"invoice_status": "R",
"kind": "b2c",
"invoice_image_url": "(URL)",
"tax_number_service": "tax.service.gov.uk",
"refunded_total_amount": 24.00,
"product_class": "S",
"custom_rules_applied": [
"postage-insurance-vat"
],
"line_num": 2,
"is_seller_permanent": true,
"quantity": 1.000000000000,
"invoice_capable": true,
"total_amount": 120.00,
"seller_code": "V4EDemo_Seller3",
"invoice_image_url_secret": "id4-IlvR2vU4GMn7",
"refunds": [
{
"refund_reason": "Refund line Y",
"refund_amount": 20.00,
"refund_timestamp": "2025-03-28T07:16:37Z",
"refund_note_url": "(URL)",
"refund_tax_amount": 4.00,
"refund_note_number": 1,
"refund_note_subnumber": 2,
"refund_key": "EJa36uLAd7SmXiOuL8OPPg",
"refund_total_amount": 24.00
}
],
"tax_entity_name": "United Kingdom",
"tax_supported": true
}
],
"discounts": [],
"refunded_tax_amount": 24.00,
"product_classes": "SP",
"billing_address": {
"city": "The big city",
"country_code": "GB",
"postal_code": "00000",
"street_name": "The street name",
"building_number": "100a",
"tax_region": "GB"
},
"status": "C",
"refunded_total_amount": 144.00,
"update_timestamp": "2025-03-28T07:01:36Z",
"buyer_name": "Test buyer",
"tax_timestamp": "2025-03-01T12:00:00Z",
"total_amount": 240,
"invoice_image_url_secret": "id4-IlvR2vU4GMn7",
"currency_code": "EUR"
}
}
Updated about 1 month ago