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

The Payment API supports refunds for the following payment methods:

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:

To retrieve details about all refunds for a transaction, use the transactionId. To retrieve details about a specific refund, use the refundTransactionId. The refundTransactionId is returned in the refund response object.

Card and ACH/ECP Refunds

When you issue a refund for card and ACH/ECP transactions, we attempt to void the transaction before issuing a refund.

If we cannot void a card transaction, we issue the refund. If an ACH/ECP transaction cannot be voided, then you must issue the refund after the transaction is 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

Enter the relevant IDs as path parameters in the request URL and an optional request body.

Path parameters

Parameter	Type	Required	Description
`{transactionId}`	integer	required to retrieve by transaction.	Unique identifier that BlueSnap assigned to the transaction.
`{merchantTransactionId}`	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/{transactionId}

For example:

https://sandbox.bluesnap.com/services/2/transactions/refund/123456789

By Merchant Transaction ID

https://sandbox.bluesnap.com/services/2/transactions/refund/merchant/{merchantTransactionId}

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

Optionally, send a refund object with the following properties:

Property	Type	Requirement
`amount`	decimal	optional
`cancelSubscriptions`	boolean	optional
`reason`	string	optional
`taxAmount`	decimal	optional (included if a partial refund of transaction involving taxes)
`transactionMetaData`	object	optional (see transactionMetaData)
`vendorsRefundInfo`	object	optional (see vendorsRefundInfo)

Response Details

Successful requests return the HTTP response status code 200 OK and a response body that contains a refund object.

Examples

Request Examples

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287689 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "reason": "Refund for order #1992",
  "cancelSubscriptions": false,
  "transactionMetaData": {
    "metaData": [
      {
        "metaValue": "1552,8832",
        "metaKey": "refundedItems",
        "metaDescription": "Refunded Items"
      },
      {
        "metaValue": "Value 2",
        "metaKey": "metaKey2",
        "metaDescription": "Metadata 2"
      }
    ]
  }
}'

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287997 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "amount": 10.75,
  "cancelSubscriptions": false
}'

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287997 \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "amount": 52.50,
  "taxAmount": 2.50
}'

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/merchant/1011671987  \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
    "reason": "Refund for order #1992"
} '

curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions/refund/1039287689?simulatenofunds=true \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "reason": "Refund for order #1992",
  "cancelSubscriptions": false,
  "transactionMetaData": {
    "metaData": [
      {
        "metaValue": "1552,8832",
        "metaKey": "refundedItems",
        "metaDescription": "Refunded Items"
      }
    ]
  }
}'

Response Examples

{
  "refundTransactionId": 1039288153,
  "transactionMetaData": {
    "metaData": [
      {
        "metaKey": "refundedItems",
        "metaValue": "1552,8832",
        "metaDescription": "Refunded Items"
      },
      {
        "metaKey": "metaKey2",
        "metaValue": "Value 2",
        "metaDescription": "Metadata 2"
      }
    ]
  },
  "reason": "Refund for order #1992",
  "cancelSubscriptions": false
}

{
  "refundTransactionId": 1039288355,
  "amount": 10.75,
  "cancelSubscriptions": false
}

{
  "refundTransactionId": 1039288356,
  "amount": 52.50,
  "taxAmount": 2.50
}

{
    "refundTransactionId": 2148039782,
    "transactionMetaData": {
        "metaData": [
            {
                "metaKey": "shippingAmount2",
                "metaValue": "10",
                "metaDescription": "Shipping Amount"
            }
        ]
    },
    "reason": "test full refund",
    "refundStatus": "PENDING"
}

API Explorer

To test a call, enter an existing transaction ID in the transactionId field. This automatically inserts the ID into the request URL. Click the "Try It!" button to submit your test request and see a response.