Carebit API

Payments

Payments collected for Invoices and Patients.

Required API scopes: payments.createpayments.readrefunds.create

Endpoints

Scroll this page to read every Payments endpoint, or jump to one below.

get/v1/paymentsList Paymentspayments.read
post/v1/paymentsCreate a Paymentpayments.create
post/v1/payments/:id/refundsCreate a Refundrefunds.create

get/v1/payments

List Payments

Returns Payments in the authenticated Organization. Filter optionally by patient_id and by a paid_at window. Each Payment includes invoice_id, patient_id, and nested refunds.

Required API scopes: payments.read

Parameters

patient_id
query
string
Filter by a Patient with an active connection to the Organization.
paid_at_from
query
string
Inclusive lower bound for paid_at in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Payments with a null paid_at are omitted when this filter is set.
paid_at_to
query
string
Inclusive upper bound for paid_at in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Payments with a null paid_at are omitted when this filter is set.
limit
query
integer
The maximum number of items to return. Defaults to 25; the maximum is 100.
starting_after
query
string
Return items after this resource ID. You cannot use this with cursor.
cursor
query
string
The next_cursor value from the previous page. You cannot use this with starting_after.

Responses

200

Paginated list of Payment objects.

dataarrayrequired
- itemsobject
  - amountintegerrequired
    The Payment amount in minor currency units.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - currencystring | nullrequired
    The ISO 4217 currency code.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - internal_notesstring | nullrequired
    Internal notes recorded with the Payment.
  - invoice_idstring | null · uuidrequired
    The Invoice this Payment is allocated to, when one is assigned.
  - linksobjectrequired
    URLs to related resources.
    - patientstring | null · urirequired
      The full URL of a related resource.
  - objectanyrequired
    Discriminator value emitted at object.
  - paid_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - patient_idstring | null · uuidrequired
    The Patient associated with the Payment.
  - payment_method_idstring | null · uuidrequired
    The stored card PaymentMethod charged for this Payment, when one was used.
  - payment_method_typestring | nullrequired
    How the Payment was collected.
    Allowed values: bacs_debit | bank_transfer | card | card_external | cash | cheque | klarna | other | standing_order | null
  - payor_typestring | nullrequired
    The type of party who made the Payment.
    Allowed values: alternative_payor | insurance_company | location | patient | null
  - refundsarrayrequired
    Refunds issued against this Payment, if any. Ordered by created_at.
    - itemsobject
      - amountintegerrequired
        The refunded amount in minor currency units.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - currencystring | nullrequired
        The ISO 4217 currency code.
      - errorstring | nullrequired
        The failure message when the Refund did not complete.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - invoice_idstring | null · uuidrequired
        The Invoice associated with the refunded Payment, when one is assigned.
      - linksobjectrequired
        URLs to related resources.
        patientstring | null · urirequired
        The full URL of a related resource.
      - next_stepsstring | nullrequired
        Guidance for completing the Refund after a Stripe refund to the original payment method fails. Null unless status is failed and refund_source is payment_account.
      - notesstring | nullrequired
        Internal notes recorded with the Refund.
      - objectanyrequired
        Discriminator value emitted at object.
      - patient_idstring | null · uuidrequired
        The Patient associated with the Refund.
      - payment_idstring | null · uuidrequired
        The Payment this Refund was issued against.
      - reasonstring | nullrequired
        The reason the Refund was issued.
        Allowed values: other | other_party_will_pay | overcharged | overpaid | service_not_delivered | null
      - refund_sourcestring | nullrequired
        How the Refund is paid.
        Allowed values: bank_account | deduction_from_balance | payment_account | null
      - statusstring | nullrequired
        The Refund's current status.
        Allowed values: canceled | failed | processing | requires_action | succeeded | null
      - succeeded_atstring | null · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - statusstring | nullrequired
    The Payment's current status.
    Allowed values: awaiting_authentication | being_processed | canceled | disputed | failed | paid | partially_refunded | refunded | scheduled | unpaid | null
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "object": "list",
  "data":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000026",
      "object": "payment",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "invoice_id": "00000000-0000-4000-8000-000000000027",
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
      },
      "paid_at": "2026-01-01T09:00:00Z",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "payment_method_id": "00000000-0000-4000-8000-000000000036",
      "payment_method_type": "bacs_debit",
      "payor_type": "insurance_company",
      "refunds":  … ]
         … }
          "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
          "object": "refund",
          "amount": 25000,
          "created_at": "2026-01-01T09:00:00Z",
          "currency": "GBP",
          "error": "The destination payment account declined the refund.",
          "invoice_id": "00000000-0000-4000-8000-000000000027",
          "links":  … }
            "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
          },
          "next_steps": null,
          "notes": "Please confirm the appointment by email.",
          "patient_id": "00000000-0000-4000-8000-000000000004",
          "payment_id": "00000000-0000-4000-8000-000000000026",
          "reason": "other",
          "refund_source": "bank_account",
          "status": "canceled",
          "succeeded_at": "2026-01-01T09:00:00Z",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "status": "awaiting_authentication",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/payments"
}

400

A time filter or pagination parameter is invalid.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401

The access token is missing, invalid, expired, or revoked.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403

The access token lacks the required scope, or the project is disabled.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404

The Patient was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429

Too many requests. Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Request

curl -X GET "https://api.carebit.co/v1/payments" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000026",
      "object": "payment",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "invoice_id": "00000000-0000-4000-8000-000000000027",
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
      },
      "paid_at": "2026-01-01T09:00:00Z",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "payment_method_id": "00000000-0000-4000-8000-000000000036",
      "payment_method_type": "bacs_debit",
      "payor_type": "insurance_company",
      "refunds":  … ]
         … }
          "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
          "object": "refund",
          "amount": 25000,
          "created_at": "2026-01-01T09:00:00Z",
          "currency": "GBP",
          "error": "The destination payment account declined the refund.",
          "invoice_id": "00000000-0000-4000-8000-000000000027",
          "links":  … }
            "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
          },
          "next_steps": null,
          "notes": "Please confirm the appointment by email.",
          "patient_id": "00000000-0000-4000-8000-000000000004",
          "payment_id": "00000000-0000-4000-8000-000000000026",
          "reason": "other",
          "refund_source": "bank_account",
          "status": "canceled",
          "succeeded_at": "2026-01-01T09:00:00Z",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "status": "awaiting_authentication",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/payments"
}

400 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

post/v1/payments

Create a Payment

Creates a card Payment for a Patient with an active connection to the Organization. Requires payments.create. Amounts are minor currency units. payor_type must be patient. The Patient must already have an active stored card PaymentMethod that this Organization can access. Supply payment_method_id to charge a specific card from GET /v1/patients/{id}/payment_methods. When payment_method_id is omitted, Carebit charges the Patient's default stored card. If the Patient has no stored card, the request fails. Send the Patient to patient_portal_add_payment_method_url on the Patient object so they can add a card in the Patient Portal. If Stripe requires extra authentication, Carebit emails the Patient a Patient Portal link to complete it. Other payment method types are not accepted.

Required API scopes: payments.create

Parameters

Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

amountintegerrequired
The Payment amount in minor currency units.
clinician_idstring | null · uuid
The optional Clinician associated with the Payment. Defaults to the Invoice's Clinician when invoice_id is set.
internal_notesstring | null
Internal notes recorded with the Payment.
invoice_idstring | null · uuid
The optional Invoice to allocate this Payment to. The Invoice must belong to the Patient.
patient_idstring · uuidrequired
The Patient with an active connection to the Organization.
payment_method_idstring | null · uuid
The stored card PaymentMethod to charge. The PaymentMethod must belong to the Patient and this Organization must have ResourcePermissions to access it. When omitted, Carebit charges the Patient's default stored card. List available cards with GET /v1/patients/{id}/payment_methods.
payment_method_typestringrequired
Must be card. Carebit charges a stored card PaymentMethod that this Organization can access. Supply payment_method_id to choose a specific card, or omit it to charge the default. The Patient must already have an active stored card. If they do not, send them to patient_portal_add_payment_method_url on the Patient object. Other payment method types are not accepted.
Allowed values: card
payor_typestring
The party who made the Payment. Currently only patient is supported.
Allowed values: patient

Responses

201

The requested Payment.

amountintegerrequired
The Payment amount in minor currency units.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
currencystring | nullrequired
The ISO 4217 currency code.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
internal_notesstring | nullrequired
Internal notes recorded with the Payment.
invoice_idstring | null · uuidrequired
The Invoice this Payment is allocated to, when one is assigned.
linksobjectrequired
URLs to related resources.
- patientstring | null · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
paid_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
patient_idstring | null · uuidrequired
The Patient associated with the Payment.
payment_method_idstring | null · uuidrequired
The stored card PaymentMethod charged for this Payment, when one was used.
payment_method_typestring | nullrequired
How the Payment was collected.
Allowed values: bacs_debit | bank_transfer | card | card_external | cash | cheque | klarna | other | standing_order | null
payor_typestring | nullrequired
The type of party who made the Payment.
Allowed values: alternative_payor | insurance_company | location | patient | null
refundsarrayrequired
Refunds issued against this Payment, if any. Ordered by created_at.
- itemsobject
  - amountintegerrequired
    The refunded amount in minor currency units.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - currencystring | nullrequired
    The ISO 4217 currency code.
  - errorstring | nullrequired
    The failure message when the Refund did not complete.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - invoice_idstring | null · uuidrequired
    The Invoice associated with the refunded Payment, when one is assigned.
  - linksobjectrequired
    URLs to related resources.
    - patientstring | null · urirequired
      The full URL of a related resource.
  - next_stepsstring | nullrequired
    Guidance for completing the Refund after a Stripe refund to the original payment method fails. Null unless status is failed and refund_source is payment_account.
  - notesstring | nullrequired
    Internal notes recorded with the Refund.
  - objectanyrequired
    Discriminator value emitted at object.
  - patient_idstring | null · uuidrequired
    The Patient associated with the Refund.
  - payment_idstring | null · uuidrequired
    The Payment this Refund was issued against.
  - reasonstring | nullrequired
    The reason the Refund was issued.
    Allowed values: other | other_party_will_pay | overcharged | overpaid | service_not_delivered | null
  - refund_sourcestring | nullrequired
    How the Refund is paid.
    Allowed values: bank_account | deduction_from_balance | payment_account | null
  - statusstring | nullrequired
    The Refund's current status.
    Allowed values: canceled | failed | processing | requires_action | succeeded | null
  - succeeded_atstring | null · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
statusstring | nullrequired
The Payment's current status.
Allowed values: awaiting_authentication | being_processed | canceled | disputed | failed | paid | partially_refunded | refunded | scheduled | unpaid | null
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "00000000-0000-4000-8000-000000000026",
  "object": "payment",
  "amount": 25000,
  "created_at": "2026-01-01T09:00:00Z",
  "currency": "GBP",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "invoice_id": "00000000-0000-4000-8000-000000000027",
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "paid_at": "2026-01-01T09:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payment_method_id": "00000000-0000-4000-8000-000000000036",
  "payment_method_type": "bacs_debit",
  "payor_type": "insurance_company",
  "refunds":  … ]
     … }
      "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
      "object": "refund",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "error": "The destination payment account declined the refund.",
      "invoice_id": "00000000-0000-4000-8000-000000000027",
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
      },
      "next_steps": null,
      "notes": "Please confirm the appointment by email.",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "payment_id": "00000000-0000-4000-8000-000000000026",
      "reason": "other",
      "refund_source": "bank_account",
      "status": "canceled",
      "succeeded_at": "2026-01-01T09:00:00Z",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "status": "awaiting_authentication",
  "updated_at": "2026-01-01T09:00:00Z"
}

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401

The access token is missing, invalid, expired, or revoked.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403

The access token lacks the required scope, or the project is disabled.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404

The Patient, Invoice, Clinician, or PaymentMethod was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

409

A concurrent request holds the idempotency lease (idempotency_conflict). Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

422

The Payment cannot be created. The Patient must already have an active stored card PaymentMethod that this Organization can access. List PaymentMethods with GET /v1/patients/{id}/payment_methods, or use patient_portal_add_payment_method_url on the Patient object to collect one. Other payment method types are not accepted. The Invoice must belong to the Patient and must be able to accept a Payment.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429

Too many requests. Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Request

curl -X POST "https://api.carebit.co/v1/payments" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 25000,
  "invoice_id": "00000000-0000-4000-8000-000000000027",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payment_method_id": "00000000-0000-4000-8000-000000000036",
  "payment_method_type": "card"
}'

201 response

{
  "id": "00000000-0000-4000-8000-000000000026",
  "object": "payment",
  "amount": 25000,
  "created_at": "2026-01-01T09:00:00Z",
  "currency": "GBP",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "invoice_id": "00000000-0000-4000-8000-000000000027",
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "paid_at": "2026-01-01T09:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payment_method_id": "00000000-0000-4000-8000-000000000036",
  "payment_method_type": "bacs_debit",
  "payor_type": "insurance_company",
  "refunds":  … ]
     … }
      "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
      "object": "refund",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "error": "The destination payment account declined the refund.",
      "invoice_id": "00000000-0000-4000-8000-000000000027",
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
      },
      "next_steps": null,
      "notes": "Please confirm the appointment by email.",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "payment_id": "00000000-0000-4000-8000-000000000026",
      "reason": "other",
      "refund_source": "bank_account",
      "status": "canceled",
      "succeeded_at": "2026-01-01T09:00:00Z",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "status": "awaiting_authentication",
  "updated_at": "2026-01-01T09:00:00Z"
}

400 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

409 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

422 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

post/v1/payments/:id/refunds

Create a Refund

Creates a Refund against a card Payment. Requires refunds.create. Amounts are minor currency units. reason is required. Carebit returns the funds to the original card through Stripe and the Refund starts as processing. If Stripe rejects the Refund, Carebit emits refund.failed with the error message and next steps.

Required API scopes: refunds.create

Parameters

id
path · required
string
-
Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

amountintegerrequired
The amount to refund in minor currency units. Must not exceed the Payment's remaining refundable amount.
notesstring | null
Internal notes recorded with the Refund.
notify_payorboolean
Whether to notify the payor when the Refund succeeds. Defaults to true.
reasonstringrequired
The reason the Refund is being issued.
Allowed values: other | other_party_will_pay | overcharged | overpaid | service_not_delivered

Responses

201

The requested Refund.

amountintegerrequired
The refunded amount in minor currency units.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
currencystring | nullrequired
The ISO 4217 currency code.
errorstring | nullrequired
The failure message when the Refund did not complete.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
invoice_idstring | null · uuidrequired
The Invoice associated with the refunded Payment, when one is assigned.
linksobjectrequired
URLs to related resources.
- patientstring | null · urirequired
  The full URL of a related resource.
next_stepsstring | nullrequired
Guidance for completing the Refund after a Stripe refund to the original payment method fails. Null unless status is failed and refund_source is payment_account.
notesstring | nullrequired
Internal notes recorded with the Refund.
objectanyrequired
Discriminator value emitted at object.
patient_idstring | null · uuidrequired
The Patient associated with the Refund.
payment_idstring | null · uuidrequired
The Payment this Refund was issued against.
reasonstring | nullrequired
The reason the Refund was issued.
Allowed values: other | other_party_will_pay | overcharged | overpaid | service_not_delivered | null
refund_sourcestring | nullrequired
How the Refund is paid.
Allowed values: bank_account | deduction_from_balance | payment_account | null
statusstring | nullrequired
The Refund's current status.
Allowed values: canceled | failed | processing | requires_action | succeeded | null
succeeded_atstring | null · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
  "object": "refund",
  "amount": 25000,
  "created_at": "2026-01-01T09:00:00Z",
  "currency": "GBP",
  "error": "The destination payment account declined the refund.",
  "invoice_id": "00000000-0000-4000-8000-000000000027",
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "next_steps": null,
  "notes": "Please confirm the appointment by email.",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payment_id": "00000000-0000-4000-8000-000000000026",
  "reason": "other",
  "refund_source": "bank_account",
  "status": "canceled",
  "succeeded_at": "2026-01-01T09:00:00Z",
  "updated_at": "2026-01-01T09:00:00Z"
}

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401

The access token is missing, invalid, expired, or revoked.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403

The access token lacks the required scope, or the project is disabled.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404

The Payment was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

409

A concurrent request holds the idempotency lease (idempotency_conflict). Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

422

The Refund cannot be created. The Payment must be a paid or partially_refunded card Payment, and amount must not exceed the remaining refundable amount.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429

Too many requests. Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Request

curl -X POST "https://api.carebit.co/v1/payments/00000000-0000-4000-8000-000000000026/refunds" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 25000,
  "notes": "Refund for a canceled consultation.",
  "reason": "service_not_delivered"
}'

201 response

{
  "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
  "object": "refund",
  "amount": 25000,
  "created_at": "2026-01-01T09:00:00Z",
  "currency": "GBP",
  "error": "The destination payment account declined the refund.",
  "invoice_id": "00000000-0000-4000-8000-000000000027",
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "next_steps": null,
  "notes": "Please confirm the appointment by email.",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payment_id": "00000000-0000-4000-8000-000000000026",
  "reason": "other",
  "refund_source": "bank_account",
  "status": "canceled",
  "succeeded_at": "2026-01-01T09:00:00Z",
  "updated_at": "2026-01-01T09:00:00Z"
}

400 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

401 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

403 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

404 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

409 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

422 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

429 response

{
  "error":  … }
    "code": "resource_missing",
    "errors":  … ]
       … }
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}

Prefer plain text? Append ?format=md or send Accept: text/markdown to receive this page as raw Markdown.