{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/transactions/refund/:transaction-id","auth":"optional","settings":"","results":{"codes":[]},"params":[{"name":"transaction-id","type":"string","default":"","desc":"ID of the transaction to be refunded <br><span style=\"color:#F37500\">*required if not using `merchant-transaction-id`*</span>","required":false,"in":"path","ref":"","_id":"5ff4bd08b7e9dd003355183d"},{"name":"merchant-transaction-id","type":"string","default":"","desc":"ID of the merchant transaction to be refunded <br><span style=\"color:#F37500\">*required if not using `transaction-id`*</span>","required":false,"in":"path","ref":"","_id":"6108234d38540100269068fe"}],"examples":{"codes":[]},"method":"post"},"next":{"description":"","pages":[]},"title":"Refund","type":"endpoint","slug":"refund","excerpt":"","body":"The Refund request allows you to perform a full or partial refund on a transaction that was processed through the Payment API.   \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Notes\",\n  \"body\": \"**Refund currency**\\nThe refund is automatically performed in the currency of the original transaction. \\n\\n**Refunds for card and ACH transactions**\\nFor card and ACH transactions, when you issue a refund, we will first attempt to void the transaction. \\n   * For cards, if the transaction cannot be voided, a refund will be issued.\\n   * For ACH, you will need to issue a refund once the transaction has been settled.\\n\\n**Retrieving refund details**\\nTo view details about the refunds on a specific transaction, use the **Retrieve** call for that transaction type (such as [Retrieve Card Transaction](doc:retrieve) or [Retrieve ACH/ECP Transaction](doc:retrieve-ecp-transaction)). \\n  * Retrieve the transaction using the `transaction-id` to view **all refunds** for that transaction. \\n  * Retrieve the transaction using the `refund-transaction-id` to view a **specific refund** and all its details (such as metadata).\"\n}\n[/block]\n<a class=\"btn btn-success\" href=\"#section-api-explorer\" role=\"button\">Try it in the API Explorer</a>\n\n###Request Content\nSend a **[refund](doc:refund-1)** object, with the following: \n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`amount` &nbsp;&nbsp;&nbsp; *decimal* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`tax-amount` &nbsp;&nbsp;&nbsp; *decimal* &nbsp;&nbsp;&nbsp;optional (included if a partial refund of transaction involving taxes)\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`reason` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`cancel-subscriptions` &nbsp;&nbsp;&nbsp; *boolean* &nbsp;&nbsp;&nbsp;optional\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`vendors-refund-info` &nbsp;&nbsp;&nbsp; *container* &nbsp;&nbsp;&nbsp;optional (see [vendors-refund-info](doc:vendors-refund-info))\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`transaction-meta-data` &nbsp;&nbsp;&nbsp; *container* &nbsp;&nbsp;&nbsp;optional (see [transaction-meta-data](doc:transaction-meta-data))\n\n###Response Details\nIf successful, the response HTTP status code is 200 OK and contains the [**refund**](doc:refund-1) object.\n\n<hr>\n\n##Example\n\n###Request Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039318399 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Accept: application/xml' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <reason>Refund for order #1992</reason>\\n  <cancel-subscriptions>false</cancel-subscriptions>\\n  <transaction-meta-data>\\n    <meta-data>\\n      <meta-key>refundedItems</meta-key>\\n      <meta-value>1552,8832</meta-value>\\n      <meta-description>Refunded Items</meta-description>\\n    </meta-data>\\n    <meta-data>\\n      <meta-key>keyNumber2</meta-key>\\n      <meta-value>KTD</meta-value>\\n      <meta-description>Metadata 2</meta-description>\\n    </meta-data>\\n  </transaction-meta-data>\\n</refund>'\",\n      \"language\": \"curl\",\n      \"name\": \"Refund request: Full refund with metadata\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287997 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Accept: application/xml' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <amount>10</amount>\\n  <cancel-subscriptions>false</cancel-subscriptions>\\n</refund>'\",\n      \"language\": \"curl\",\n      \"name\": \"Partial refund\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287997 \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Accept: application/xml' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <amount>52.50</amount>\\n  <tax-amount>2.50</tax-amount>\\n</refund>'\",\n      \"language\": \"curl\",\n      \"name\": \"Partial refund with tax\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/merchant/1011671987  \\\\\\n-H 'Content-Type: application/xml' \\\\\\n-H 'Accept: application/xml' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <reason>Refund for order #1992</reason>\\n</refund>'\",\n      \"language\": \"curl\",\n      \"name\": \"with Merchant Transaction ID\"\n    }\n  ]\n}\n[/block]\n###Response Example \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\" standalone=\\\"yes\\\"?>\\n<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <refund-transaction-id>1039318651</refund-transaction-id>\\n  <transaction-meta-data>\\n    <meta-data>\\n      <meta-key>refundedItems</meta-key>\\n      <meta-value>1552,8832</meta-value>\\n      <meta-description>Refunded Items</meta-description>\\n    </meta-data>\\n    <meta-data>\\n      <meta-key>keyNumber2</meta-key>\\n      <meta-value>KTD</meta-value>\\n      <meta-description>Metadata 2</meta-description>\\n    </meta-data>\\n  </transaction-meta-data>\\n  <reason>Refund for order &#x23;1992</reason>\\n  <cancel-subscriptions>false</cancel-subscriptions>\\n</refund>\",\n      \"language\": \"xml\",\n      \"name\": \"Full refund with metadata\"\n    },\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\" standalone=\\\"yes\\\"?>\\n<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <refund-transaction-id>1039318669</refund-transaction-id>\\n  <amount>10</amount>\\n  <cancel-subscriptions>false</cancel-subscriptions>\\n</refund>\",\n      \"language\": \"xml\",\n      \"name\": \"Partial refund\"\n    },\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\" standalone=\\\"yes\\\"?>\\n<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <refund-transaction-id>1039318670</refund-transaction-id>\\n  <amount>52.50</amount>\\n  <tax-amount>2.50</tax-amount>\\n</refund>\",\n      \"language\": \"xml\",\n      \"name\": \"Partial refund with tax\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n<hr>\n\n##Example Descriptions\nFor details about the above examples, see:\n\n* [Full refund with metadata](#section-full-refund-with-metadata)\n* [Partial refund](#section-partial-refund)\n* [Partial refund with tax](#section-partial-refund-with-tax)\n* [with Merchant Transaction ID](#section-with-merchant-transaction-id)\n\n### Full refund with metadata\nThis example shows a refund request with metadata for the full transaction amount. Simply omit `amount` to refund the full transaction amount. To pass metadata, include `transaction-meta-data` in the request. \n\n### Partial refund  \nThis example shows a partial refund, with the amount specified by the `amount` parameter. \n\n### Partial refund with tax\nThis example shows a partial refund for a transaction involving taxes. The refund amount, including tax, is specified by the `amount` parameter, and the tax amount to be refunded is specified in the `tax-amount` parameter. See the [Taxes guide](https://developers.bluesnap.com/v8976-Basics/docs/taxes) for more information.\n\n### with Merchant Transaction ID\nThis example shows a basic refund request using the `merchant-transaction-id` at the end of the request URL instead of the `transactionId`.\n\n##API Explorer\nTo test a call, enter an existing transaction ID in the `transaction-id` field. This automatically inserts the ID into the request URL. Enter any relevant parameters in the request body. You can use the code below as a starting point. Click **Try It** when you're ready to run your request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<refund xmlns=\\\"http://ws.plimus.com\\\">\\n  <reason>Refund for order #1992</reason>\\n  <cancel-subscriptions>false</cancel-subscriptions>\\n  <transaction-meta-data>\\n    <meta-data>\\n      <meta-key>refundedItems</meta-key>\\n      <meta-value>1552,8832</meta-value>\\n      <meta-description>Refunded Items</meta-description>\\n    </meta-data>\\n    <meta-data>\\n      <meta-key>keyNumber2</meta-key>\\n      <meta-value>KTD</meta-value>\\n      <meta-description>Metadata 2</meta-description>\\n    </meta-data>\\n  </transaction-meta-data>\\n</refund>\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"61a5208deadb750070998f45","createdAt":"2021-01-05T19:23:03.314Z","user":"5ea72d649148ff00653f6bbc","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Refunds","slug":"refunds","order":9,"from_sync":false,"reference":false,"_id":"61a5208deadb750070998e8d","version":"61a5208deadb750070998f48","project":"57336fd5a6a9c40e00e13a0b","createdAt":"2016-08-19T11:04:31.283Z","__v":0},"version":{"version":"8976-XML","version_clean":"8976.0.0-XML","codename":"3.40 Release","is_stable":false,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["61a5208deadb750070998e87","61a5208deadb750070998e88","61a5208deadb750070998e89","61a5208deadb750070998e8a","61a5208deadb750070998e8b","61a5208deadb750070998e8c","61a5208deadb750070998e8d","61a5208deadb750070998e8e","61a5208deadb750070998e8f","61a5208deadb750070998e90","61a5208deadb750070998e91","61a5208deadb750070998e92","61a5208deadb750070998e93","61a5208deadb750070998e94","61a5208deadb750070998e95","61a5208deadb750070998e96","61a5208deadb750070998e97","61a5208deadb750070998e98","61a5208deadb750070998e99","61a5208deadb750070998e9a"],"_id":"61a5208deadb750070998f48","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"60fed269718a45001c25b4a0","createdAt":"2018-04-24T15:24:22.608Z","releaseDate":"2018-04-24T15:24:22.608Z"},"project":"57336fd5a6a9c40e00e13a0b","__v":34,"parentDoc":null}

Payment API (XML)

Card/Wallet Transactions

PayPal Transactions

ACH/ECP Transactions

iDEAL Transactions

Local Bank Transfer transactions

SEPA Direct Debit Transactions

Sofort Transactions

Batch Transactions

Refunds

Vaulted Shoppers

Subscriptions

Fraud Review

Marketplace

Wallets

Errors

Resources

Test Data & Codes

Guides & Tools

Mobile SDK

postRefund

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

transaction-id:
string
ID of the transaction to be refunded <br><span style="color:#F37500">*required if not using `merchant-transaction-id`*</span>
merchant-transaction-id:
string
ID of the merchant transaction to be refunded <br><span style="color:#F37500">*required if not using `transaction-id`*</span>

Documentation

The Refund request allows you to perform a full or partial refund on a transaction that was processed through the Payment API.

Notes

Refund currency
The refund is automatically performed in the currency of the original transaction.

Refunds for card and ACH transactions
For card and ACH transactions, when you issue a refund, we will first attempt to void the transaction.

  • For cards, if the transaction cannot be voided, a refund will be issued.
  • For ACH, you will need to issue a refund once the transaction has been settled.

Retrieving refund details
To view details about the refunds on a specific transaction, use the Retrieve call for that transaction type (such as Retrieve Card Transaction or Retrieve ACH/ECP Transaction).

  • Retrieve the transaction using the transaction-id to view all refunds for that transaction.
  • Retrieve the transaction using the refund-transaction-id to view a specific refund and all its details (such as metadata).

Try it in the API Explorer

Request Content

Send a refund object, with the following:
      amount     decimal    optional
      tax-amount     decimal    optional (included if a partial refund of transaction involving taxes)
      reason     string    optional
      cancel-subscriptions     boolean    optional
      vendors-refund-info     container    optional (see vendors-refund-info)
      transaction-meta-data     container    optional (see transaction-meta-data)

Response Details

If successful, the response HTTP status code is 200 OK and contains the refund object.

Example

Request Example

Refund request: Full refund with metadata
Partial refund
Partial refund with tax
with Merchant Transaction ID
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039318399 \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<refund xmlns="http://ws.plimus.com">
  <reason>Refund for order #1992</reason>
  <cancel-subscriptions>false</cancel-subscriptions>
  <transaction-meta-data>
    <meta-data>
      <meta-key>refundedItems</meta-key>
      <meta-value>1552,8832</meta-value>
      <meta-description>Refunded Items</meta-description>
    </meta-data>
    <meta-data>
      <meta-key>keyNumber2</meta-key>
      <meta-value>KTD</meta-value>
      <meta-description>Metadata 2</meta-description>
    </meta-data>
  </transaction-meta-data>
</refund>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287997 \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<refund xmlns="http://ws.plimus.com">
  <amount>10</amount>
  <cancel-subscriptions>false</cancel-subscriptions>
</refund>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287997 \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<refund xmlns="http://ws.plimus.com">
  <amount>52.50</amount>
  <tax-amount>2.50</tax-amount>
</refund>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/merchant/1011671987  \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<refund xmlns="http://ws.plimus.com">
  <reason>Refund for order #1992</reason>
</refund>'

Response Example

Full refund with metadata
Partial refund
Partial refund with tax
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<refund xmlns="http://ws.plimus.com">
  <refund-transaction-id>1039318651</refund-transaction-id>
  <transaction-meta-data>
    <meta-data>
      <meta-key>refundedItems</meta-key>
      <meta-value>1552,8832</meta-value>
      <meta-description>Refunded Items</meta-description>
    </meta-data>
    <meta-data>
      <meta-key>keyNumber2</meta-key>
      <meta-value>KTD</meta-value>
      <meta-description>Metadata 2</meta-description>
    </meta-data>
  </transaction-meta-data>
  <reason>Refund for order &#x23;1992</reason>
  <cancel-subscriptions>false</cancel-subscriptions>
</refund>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<refund xmlns="http://ws.plimus.com">
  <refund-transaction-id>1039318669</refund-transaction-id>
  <amount>10</amount>
  <cancel-subscriptions>false</cancel-subscriptions>
</refund>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<refund xmlns="http://ws.plimus.com">
  <refund-transaction-id>1039318670</refund-transaction-id>
  <amount>52.50</amount>
  <tax-amount>2.50</tax-amount>
</refund>

Back to Top

Example Descriptions

For details about the above examples, see:

Full refund with metadata

This example shows a refund request with metadata for the full transaction amount. Simply omit amount to refund the full transaction amount. To pass metadata, include transaction-meta-data in the request.

Partial refund

This example shows a partial refund, with the amount specified by the amount parameter.

Partial refund with tax

This example shows a partial refund for a transaction involving taxes. The refund amount, including tax, is specified by the amount parameter, and the tax amount to be refunded is specified in the tax-amount parameter. See the Taxes guide for more information.

with Merchant Transaction ID

This example shows a basic refund request using the merchant-transaction-id at the end of the request URL instead of the transactionId.

API Explorer

To test a call, enter an existing transaction ID in the transaction-id field. This automatically inserts the ID into the request URL. Enter any relevant parameters in the request body. You can use the code below as a starting point. Click Try It when you're ready to run your request.

XML
<refund xmlns="http://ws.plimus.com">
  <reason>Refund for order #1992</reason>
  <cancel-subscriptions>false</cancel-subscriptions>
  <transaction-meta-data>
    <meta-data>
      <meta-key>refundedItems</meta-key>
      <meta-value>1552,8832</meta-value>
      <meta-description>Refunded Items</meta-description>
    </meta-data>
    <meta-data>
      <meta-key>keyNumber2</meta-key>
      <meta-value>KTD</meta-value>
      <meta-description>Metadata 2</meta-description>
    </meta-data>
  </transaction-meta-data>
</refund>

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}