Refunds

Refunds are payments that have been either fully or partially returned to the card owner. On this page, we'll dive into the different refund endpoints you can use to manage refunds programmatically. We'll look at how to query and create refunds.

The refund model

The refund model contains all the information about your refund, including the payment refunded, amount and reason.

Monetary values are in the smallest currency unit. e.g. £1.50 would be represented as 150.

Properties

Name
id
Type
string
Description
Unique identifier for the refund.
Name
amount
Type
integer
Description
The amount refunded to the card. This can be up to the total amount of the original payment.
Name
created_at
Type
timestamp
Description
Timestamp of when the refund was created.
Name
pot
Type
string
Description
The unique identifier of the pot that the refund was made from.
Name
payment
Type
string
Description
The unique identifier of the payment that was refunded.
Name
customer
Type
string
Description
The unique identifier of the customer that made the original payment.
Name
reason
Type
hash
Description
Provides details on the reason for the refund
Name
reason.code
Type
enum
Description
The code for the reason why the payment was refunded. Can be either customer_requested,...
Name
reason.comment
Type
string
Description
An expanded reason for the refund.
Name
status
Type
enum
Description
The status of the refund. The statuses are new, processing, complete.
Name
metadata
Type
hash
Description
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
Name
failure_details
Type
hash
Description
Details on why the payment failed
Name
failure_details.code
Type
string
Description
Payment failure code.
Name
failure_details.message
Type
string
Description
An explanation on why the payment failed.

GET/v1/refunds

List all refunds

This endpoint allows you to retrieve a paginated list of all your refunds. By default, a maximum of ten refunds are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of pots returned.
Name
page
Type
integer
Description
The page you wish to fetch.
Name
customer
Type
string
Description
The unique identifier of the customer that you wish to retrieve payments for.
Name
pot
Type
string
Description
The unique identifier of the pot that you wish to retrieve payments for.

Request

GET

/v1/refunds

curl -G https://api.collctiv.com/v1/refunds \
  -H "Authorization: Bearer {token}" \
  -d limit=3

Response

{
  "has_more": false,
  "data": [
    {
      "id": "522d1dcc-344c-4373-9523-8cf4bd8be008",
      "amount": 2100,
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "payment": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "reason": {
        "code": "customer_requested",
        "comment": "The customer requested a refund via customer services."
      },
      "status": "complete",
      "metadata": {},
    },
    {
      "id": "3b241101-e2bb-4255-8caf-4136c566a962"
      // ...
    }
  ]
}

POST/v1/refunds

Create a refund

This endpoint allows you to create a new refund.

Required attributes

Name
amount
Type
integer
Description
The amount to be refunded. Not more than the amount on the payment
Name
payment
Type
string
Description
The unique identifier of the payment to be refunded.
Name
reason.code
Type
enum
Description
The code for the reason why the payment was refunded. Can be either customer_requested,...

Optional attributes

Name
reason.comment
Type
string
Description
An expanded reason for the refund.

Request

POST

/v1/refunds

curl -X POST https://api.collctiv.com/v1/refunds \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"amount":1000, "payment": "999fe8d5-1615-414b-83fc-2740b3c4a899", "reason": {"code":"customer_requested"}}'

Response

{
   "id": "522d1dcc-344c-4373-9523-8cf4bd8be008",
      "amount": 1000,
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "payment": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "reason": {
        "code": "customer_requested",
        "comment": ""
      },
      "status": "new",
      "metadata": {},
}

GET/v1/refund/:id

Retrieve a refund

This endpoint allows you to retrieve a refund by providing the refund id. Refer to the list at the top of this page to see which properties are included with refund objects.

Request

GET

/v1/refunds/999fe8d5-1615-414b-83fc-2740b3c4a899

curl https://api.collctiv.com/v1/refunds/999fe8d5-1615-414b-83fc-2740b3c4a899 \
  -H "Authorization: Bearer {token}"

Response

{
    "id": "522d1dcc-344c-4373-9523-8cf4bd8be008",
      "amount": 2100,
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "payment": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "reason": {
        "code": "customer_requested",
        "comment": "The customer requested a refund via customer services."
      },
      "status": "complete",
      "metadata": {},
}