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
- Pay by Bank (Open Banking)
- 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:
- Retrieve ECP Transaction (ACH/ECP)
- Retrieve (Cards/Wallets)
- Retrieve Pay by Bank Transaction
- Retrieve PayPal Transaction
- Retrieve SEPA DD Transaction
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
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 |
|---|---|---|---|
| {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.