The Refund request allows you to perform a full or partial refund on a transaction that was processed through the Payment API.
The refund is automatically performed in the currency of the original transaction.
Supported Payment Methods
We support refunds through our API if any of the following payment methods were used:
- ACH
- Cards/Wallets
- PayPal
- SEPA
Refund Period
Refunds can only be issued for transactions less than 2 years old.
Retrieving Refund Details
To view details about the refunds on a specific transaction, use the Retrieve call for that transaction type. For example, Retrieve Card Transaction or Retrieve ACH/ECP Transaction.
Retrieve the transaction using the transactionId to view all refunds for that transaction. Retrieve the transaction using the refundTransactionId to view a specific refund and all its details (such as metadata).
Card and ACH/ECP Refunds
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.
Colorado Delivery Fee
Per Colorado tax law, the Colorado delivery fee is not refundable except for cancelled, chargeback or voided transactions. This includes the tax portion except in the case of certain chargebacks.
Request Content
Send a test request
Go to API Explorer to send a test request to our sandbox environment and receive a response in real time.
Enter the relevant IDs as path parameters in the request URL and an optional request body.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| {transaction-id} | integer | required to retrieve by transaction. | Unique identifier that BlueSnap assigned to the transaction. |
| {merchant-transaction-id} | integer | required to retrieve transaction by merchant transaction ID. | Unique identifier that the merchant assigned to the transaction. |
By Transaction ID
https://sandbox.bluesnap.com/services/2/transactions/refund/{transaction-id}
For example:
https://sandbox.bluesnap.com/services/2/transactions/refund/123456789
By Merchant Transaction ID
https://sandbox.bluesnap.com/services/2/transactions/refund/merchant/{merchant-transaction-id}
For example:
https://sandbox.bluesnap.com/services/2/transactions/refund/merchant/mtid_001
Query String Parameters
| Parameter | Description |
|---|---|
simulatenofunds | This parameter is available for testing in the sandbox environment only and requires that you have pending refunds enabled. When set to true, it simulates a "no-funds available" scenario, even if the account has a positive balance and has enough funds to process the refund. This lets you easily test your pending refund workflows.If you do not have pending refunds enabled on your account, you receive a not-enough-funds error when set to true.Example: simulatenofunds=true |
Request Body
Send a refund object, with the following:
| Property | Type | Required |
|---|---|---|
amount | decimal | optional |
cancel-subscriptions | boolean | optional |
reason | string | optional |
tax-amount | decimal | optional (included if a partial refund of transaction involving taxes) |
transaction-meta-data | container | optional (see transaction-meta-data) |
vendors-refund-info | container | optional (see vendors-refund-info) |
Response Details
If successful, the response HTTP status code is 200 and contains the refund object.
Examples
Request Example
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>'
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039318399?simulatenofunds=true \
-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>'
Response Example
<?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 #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>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<refund xmlns="http://ws.plimus.com">
<refundTransactionId>2148039782</refundTransactionId>
<transactionMetaData>
<metaData>
<metaKey>shippingAmount2</metaKey>
<metaValue>10</metaValue>
<metaDescription>Shipping Amount</metaDescription>
</metaData>
</transactionMetaData>
<reason>test full refund</reason>
<refundStatus>PENDING</refundStatus>
</refund>