Payments

Payments provide all the information you need about the funds received into a pot. On this page, we'll dive into the different payment endpoints you can use to manage payments programmatically. We'll look at how to query, create, and update payments.

The payment model

The payment model contains all the information about your payments, including who made the payment, summary payment details and currency.

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 payment.
Name
amount
Type
integer
Description
The amount contributred into the pot including any tip.
Name
created_at
Type
timestamp
Description
Timestamp of when the payment was created.
Name
pot
Type
string
Description
The unique identifier of the pot that the payment was made into.
Name
billing_details
Type
hash
Description
The name and email of the person who made the payment.
Name
billing_details.name
Type
string
Description
The name of the person that made the payment.
Name
billing_details.email
Type
string
Description
The emaill address of the person that made the payment.
Name
customer
Type
string
Description
The unique identifier of the customer that owns the pot the payment was made into.
Name
status
Type
enum
Description
The status of the payment. The statuses are authorised, paid, refunded, fully_refunded, partially_refunded, failed.
Name
currency
Type
string
Description
The currency the payment was received in.
Name
note
Type
string
Description
The message left on the payment.
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
amount_details
Type
hash
Description
A breakdown of the payment, including tip and fees.
Name
amount_details.contribution
Type
integer
Description
The amount the contributor wants to add to contribute to the pot.
Name
amount_details.processing_fee
Type
integer
Description
The service fee charged to process the payment
Name
amount_details.net
Type
integer
Description
The total amount minus tip and service fee.
Name
descriptor
Type
string
Description
The string shown on a contributors card statement. 20 characters maximum.
Name
payment_method_details
Type
hash
Description
Details of the card used to make the payment.
Name
payment_method_details.country
Type
string
Description
The country the card originates
Name
payment_method_details.exp_month
Type
integer
Description
The month that the card expires
Name
payment_method_details.exp_year
Type
integer
Description
The year that the card expires
Name
payment_method_details.last4
Type
string
Description
The last 4 digits of the card number
Name
payment_method_details.provider
Type
string
Description
The card network providing the payment. e.g visa, mastercard.
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/payments

List all payments

This endpoint allows you to retrieve a paginated list of all your pots. By default, a maximum of ten pots 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/payments

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

Response

{
  "has_more": false,
  "data": [
    {
      "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "amount": 2100,
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "billing_details": {
        "name": "Steve Connors",
        "email": "steve.connors@example.com"
      },
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "status": "paid",
      "currency": "gbp",
      "note": "Thanks so much for organising",
      "metadata": {},
      "amount_details": {
        "contribution": 2000,
        "fee": 100,
        "net": 1900
      },
      "descriptor": "MyCo-Wedding Pot",
      "payment_method_details": {
        "country": "GB",
        "exp_month": 4,
        "exp_year": 2024,
        "last4": "1234",
        "provider": "visa"
      }
    },
    {
      "id": "3b241101-e2bb-4255-8caf-4136c566a962"
      // ...
    }
  ]
}

GET/v1/payments/:id

Retrieve a payment

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

Request

GET

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

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

Response

{
     "id": "999fe8d5-1615-414b-83fc-2740b3c4a899",
      "amount": 2100,
      "created_at": 692233200,
      "pot": "d4748db4-7863-4fa0-9a77-3cd329d5e652",
      "billing_details": {
        "name": "Steve Connors",
        "email": "steve.connors@example.com"
      },
      "customer": "117b2b86-4b21-4a67-8592-c267a7ba7997",
      "status": "paid",
      "currency": "gbp",
      "note": "Thanks so much for organising",
      "metadata": {},
      "amount_details": {
        "contribution": 2000,
        "fee": 100,
        "net": 1900
      },
      "descriptor": "MyCo-Wedding Pot",
      "payment_method_details": {
        "country": "GB",
        "exp_month": 4,
        "exp_year": 2024,
        "last4": "1234",
        "provider": "visa"
      }
}