Refunds

The TapTree Refunds API enables you to return funds to your customers, effectively reversing completed transactions. When a refund is initiated, the amount is deducted from your TapTree account balance. If the balance isn't sufficient to cover the refund, it's temporarily put on hold and automatically processed once your balance is adequate.

Discover the Refunds resource using Postman:

TapTree Postman Collection

Endpoints

Create a refund

POST/v1/payments/:pay_id/refunds

Refund a paid payment.

Retrieve a refund

GET/v1/refunds/:id

Fetch details of a specific refund using its unique identifier.

List all refunds

GET/v1/refunds

Retrieve a list of all refunds.

The refund model

The refund model encompasses all the vital details related to a refund processed for your customer.

Core attributes

Name
id
Type
string
Description
Unique identifier for the refund.
Name
payment_id
Type
string
Description
Identifier for the payment associated with this refund.
Name
org_id
Type
string
Description
Unique identifier for the corresponding organization.
Name
acceptor_id
Type
string
Description
Identifier for the payment acceptor this refund is related to.
Name
created_at
Type
datetime
Description
Timestamp of when the refund was created, in ISO 8601 format.
Name
mode
Type
string
|
Default
default=live
Description
Indicates if the refund was processed in test or live mode.
Name
amount
Type
object
Description
The amount of the refund, containing a string encoded value and the currency. Currency corresponds to a three-letter ISO currency code. Note that currency-wise we currently only support eur.
Name
status
Type
string
Description
Status of the refund.
Possible values: pending processing refunded failed canceled
Name
description
Type
string
Description
Description or reason for the refund.
Name
webhook_url
Type
string
Description
URL for sending refund status updates.
Name
metadata
Type
object
Description
A set of key-value pairs for storing additional information about the refund.
Name
links
Type
object
Description
Links related to the refund object, including URLs to the API, payment, and dashboard.

Response object

{
 "object": "refund",
 "id": "rf_61pMpAZQ5Br",
 "payment_id": "pay_TRzHhx5eZJ",
 "org_id": "org_5A8hsNqGGyW",
 "acceptor_id": "acceptor_Aa54Z3THuFj",
 "created_at": "2021-01-01T00:00:00.000Z",
 "mode": "test",
 "status": "refunded",
 "description": "Defective goods",
 "webhook_url": "https://example.com/webhook/endpoint",
 "amount": {
   "value": "15.00",
   "currency": "eur"
 },
 "metadata": {},
 "links": {
   "api": {
     "href": "https://api.taptree.org/v1/refunds/rf_61pMpAZQ5Br",
     "type": "application/json"
   },
   "checkout": {
     "href": "https://checkout.taptree.org/rf_61pMpAZQ5Br",
     "type": "text/html"
   },
   "dashboard": {
     "href": "https://my.taptree.org/org_5A8hsNqGGyW/refunds/rf_61pMpAZQ5Br",
     "type": "text/html"
   }
 }
}

POST/v1/payments/:id/refunds

Create a Refund

Issue a refund against a specific payment. It's essential for managing transaction reversals where funds need to be returned to the customer.

Required parameters

Name
id
Type
string
Description
To issue a refund, replace id in the endpoint URL with the payment's ID, such as pay_TRzHhx5eZJ.

Optional attributes

Name
amount
Type
object
|
Optional
optional
Description
The amount to be refunded. It must be less than or up to 15 € more than the original payment amount. If omitted, the full remaining capturable amount is refunded.
If you want to refund twenty-five euros and fifty euro cents, you would pass the following object:
{ "value": "25.50", "currency": "eur" }
Name
description
Type
string
|
Optional
optional
Description
A description for the refund for better identification.
Name
webhook_url
Type
string
|
Optional
optional
Description
The URL where webhook updates for the refund will be sent.
Name
metadata
Type
object
|
Optional
optional
Description
A set of key-value pairs for storing additional information about the refund.
Name
allow_overcaptured
Type
boolean
|
Optional
optional
Description
When true, permits refunds exceeding the captured amount.
Name
overcap_pct
Type
string
|
Optional
optional
Description
Maximum percentage above the captured amount allowed for a refund. Defaults to 0.20 (20%).

Request

POST

/v1/payments/pay_TRzHhx5eZJ/refunds

curl -X POST https://api.taptree.org/v1/payments/pay_TRzHhx5eZJ/refunds \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
        "amount": {
            "value": "15.00",
            "currency": "eur"
        },
        "description": "Defective goods",
        "webhook_url": "https://example.com/webhook/endpoint"
      }'

Example response

{
  "object": "refund",
  "id": "rf_61pMpAZQ5Br",
  "payment_id": "pay_TRzHhx5eZJ",
  "org_id": "org_5A8hsNqGGyW",
  "acceptor_id": "acceptor_Aa54Z3THuFj",
  "created_at": "2021-01-01T00:00:00.000Z",
  "mode": "test",
  "status": "refunded",
  "description": "Defective goods",
  "webhook_url": "https://example.com/webhook/endpoint",
  "amount": {
    "value": "15.00",
    "currency": "eur"
  },
  "metadata": {},
  "links": {
    "api": {
      "href": "https://api.taptree.org/v1/refunds/rf_61pMpAZQ5Br",
      "type": "application/json"
    },
    "checkout": {
      "href": "https://checkout.taptree.org/rf_61pMpAZQ5Br",
      "type": "text/html"
    },
    "dashboard": {
      "href": "https://my.taptree.org/org_5A8hsNqGGyW/refunds/rf_61pMpAZQ5Br",
      "type": "text/html"
    }
  }
}

GET/v1/refunds/:id

Retrieve a Refund

Fetch details of a specific refund using its unique identifier. It helps in tracking the status and details of an individual refund transaction.

Required parameters

Name
id
Type
string
Description
The unique identifier of the refund to retrieve. In the endpoint URL, substitute id with the specific refund's ID, such as /v1/refunds/rf_7UhSN1zuXS.

Request

GET

/v1/refunds/rf_61pMpAZQ5Br

curl https://api.taptree.org/v1/refunds/rf_61pMpAZQ5Br \
  -H "Authorization: Bearer {token}"

Example response

{
  "object": "refund",
  "id": "rf_61pMpAZQ5Br",
  "payment_id": "pay_TRzHhx5eZJ",
  "org_id": "org_5A8hsNqGGyW",
  "acceptor_id": "acceptor_Aa54Z3THuFj",
  "created_at": "2021-01-01T00:00:00.000Z",
  "mode": "test",
  "status": "refunded",
  "description": "Defective goods",
  "webhook_url": "https://example.com/webhook/endpoint",
  "amount": {
    "value": "15.00",
    "currency": "eur"
  },
  "metadata": {},
  "links": {
    "api": {
      "href": "https://api.taptree.org/v1/refunds/rf_61pMpAZQ5Br",
      "type": "application/json"
    },
    "checkout": {
      "href": "https://checkout.taptree.org/rf_61pMpAZQ5Br",
      "type": "text/html"
    },
    "dashboard": {
      "href": "https://my.taptree.org/org_5A8hsNqGGyW/refunds/rf_61pMpAZQ5Br",
      "type": "text/html"
    }
  }
}

GET/v1/refunds

List all refunds

Retrieve a paginated list of all refunds to effectively manage and track refund transactions. Utilize limit, starting_after, and ending_before parameters for fine-tuned access and navigation through your refund data.

Optional query parameters

Name
limit
Type
integer
|
Optional
optional
|
Default
default=10
Description
Specify the maximum number of refunds to return in one response, up to 100.
Name
starting_after
Type
string
|
Optional
optional
Description
Use a refund id for pagination. This parameter returns refunds listed after the specified id, useful for navigating to subsequent pages in large datasets.
Example: If the last refund id you accessed was rf_61pMpAZQ5Br, use starting_after=rf_61pMpAZQ5Br to view refunds following it.
Name
ending_before
Type
string
|
Optional
optional
Description
A refund id for pagination, returning refunds listed before the specified id. Ideal for accessing earlier pages in the list.
To view refunds preceding rf_61pMpAZQ5Br, include ending_before=rf_61pMpAZQ5Br in your request.

Request

GET

/v1/refunds

curl -G https://api.taptree.org/v1/refunds \
  -H "Authorization: Bearer {token}" \
  -d starting_after="rf_61pMpAZQ5Br" \
  -d limit=20

Example response

{
  "has_more": true,
  "data": [
    {
      "object": "refund",
      "id": "rf_61pMpAZQ5Br",
      "payment_id": "pay_TRzHhx5eZJ",
      "org_id": "org_5A8hsNqGGyW",
      "acceptor_id": "acceptor_Aa54Z3THuFj",
      "created_at": "2021-01-01T00:00:00.000Z",
      "mode": "test",
      "status": "refunded",
      "description": "Defective goods",
      "webhook_url": "https://example.com/webhook/endpoint",
      "amount": {
        "value": "15.00",
        "currency": "eur"
      },
      "metadata": {},
      "links": {
        "api": {
          "href": "https://api.taptree.org/v1/refunds/rf_61pMpAZQ5Br",
          "type": "application/json"
        },
        "checkout": {
          "href": "https://checkout.taptree.org/rf_61pMpAZQ5Br",
          "type": "text/html"
        },
        "dashboard": {
          "href": "https://my.taptree.org/org_5A8hsNqGGyW/refunds/rf_61pMpAZQ5Br",
          "type": "text/html"
        }
      }
    },
    {
      "object": "refund",
      "id": "rf_22pAbAx15Bb"
      // ...
    }
    // More refunds if available
  ]
}