---
updatedAt: 2025-02-11T23:26:20.000Z
agentTools:
  projectIndex: https://docs.shophumm.com.au/llms.txt
---

# Refund API

This allows you to programmatically refund humm purchases.

## Refund Endpoints

| humm Environment    | URL                                                                                |
| :------------------ | :--------------------------------------------------------------------------------- |
| Production Endpoint | <https://buyerapi.shophumm.com.au/api/ExternalRefund/v1/processrefund>             |
| Sandbox Endpoint    | <https://integration-buyerapi.shophumm.com.au/api/ExternalRefund/v1/processrefund> |

## Refund Request

### Headers

| Key          | Value                     |
| :----------- | :------------------------ |
| Content-Type | application/json          |
| User-agent   | product / version comment |

> 🚧 Important!
>
> If you don't specify a User-agent in your request, humm will respond with a 403 error

### Body

```Text Body
{
    "x_merchant_number": "30199250",
    "x_purchase_number": "52004168",
    "x_amount": "10.00",
    "x_reason": "Test refund",
    "signature": "e39ae5f3233f561162836989e050c1b61ba9e3d5eb3d64d4b3701e95fb5850a1"
}
```

See [Signature Generation](https://docs.shophumm.com.au/docs/custom-signature-generation) for information on how to generate the HMAC Signature.

### Example

The following curl command will allow you to test the refunds API. You will need to substitute your `x_merchant_number`, `x_purchase_number` and `signature`

```Text Example
curl \
--header "Content-Type:application/json" \
--header "User-Agent:curl/7.64.1" \
--request POST \
--data '{
    "x_merchant_number": "30199250",
    "x_purchase_number": "52000152",  
    "x_amount": 45.00,
    "x_reason": "test",
    "signature": "a5fc92ddd2326c6099bd0f43bbe75afb54004a6ba68f354cc2b40328341d8ee2"
}' \    
https://integration-buyerapi.shophumm.com.au/api/ExternalRefund/v1/processrefund
```

## Refund Response

| HTTP Status | Reason Code | Reason Description     |
| :---------- | :---------- | :--------------------- |
| 204         | None        | Success                |
| 400         | MERR0001    | API Key Not found      |
| 400         | MERR0003    | Refund Failed          |
| 400         | MERR0004    | Invalid Request        |
| 401         | None        | Failed Signature Check |

## HTTP 400 Reason Codes

To capture the HTTP 400 reason codes, parse the JSON response and use the value in "Message".

For example:

```Text Example
POST /api/ExternalRefund/v1/processrefund HTTP/1.1
Host: integration-buyerapi.shophumm.com.au
Content-Type: application/json
Cookie: hummueid=bc726701-3dc1-43b3-961c-8796df0477a3
Content-Length: 224

{
    "x_merchant_number":"30188525",
    "x_amount":18.50,
    "x_purchase_number":"28237558",
    "x_reason": "Booking Cancelled",
    "signature": "561dae20c677fc705dd511878b9bf4ba55bc3084de2efd6e53795d052d9ce778"
}
```

This returns response headers

![](https://files.readme.io/101ade4-image.png)

To capture the reason, parse the JSON

```Text Message
{
    "Message": "MERR0003"
}
```

## Partial vs Full Refunds

A refund is considered partial if its for an amount less that the purchase amount on the purchase being refunded. A full refund is if its for the full purchase amount.

Multiple partial refunds can be submitted against the same humm purchase (`x_purchase_number`) until the full purchase amount has been refunded.