Payment And Subscription

This API is in beta testing and not fully tested/released. Follow the Welkin release note for full feature availability.

Add payment method

post

Attaches a Stripe payment method to a patient, creating a Stripe customer for the patient if one does not already exist, and creates a card SetupIntent for future off-session use. Requires the tenant to have the Stripe integration license enabled. Confirmed against welikan-payment-service (PaymentMethodController.attachPaymentMethod), routed via welikan-api-gateway-service with no field-level transformation.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Body

paymentMethodIdstringRequired

Stripe PaymentMethod ID (e.g. pm_...).

Example: pm_1NExampleStripeId

Responses

200

Payment method attached

application/json

paymentMethodIdstringOptional

400

Invalid request, or the Stripe API call failed (e.g. invalid or expired paymentMethodId).

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Caller lacks UPDATE permission on payment methods for this patient.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

post/{tenantName}/{instanceName}/payment/patients/{patientId}/payment-methods

POST /{tenantName}/{instanceName}/payment/patients/{patientId}/payment-methods HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "paymentMethodId": "pm_1NExampleStripeId"
}

{
  "paymentMethodId": "text"
}

Create subscription

post

This endpoint allows you to create a new subscription for payment within a specific tenant and instance.

Request Body

• name (string, required): The name of the subscription.
• billingPeriod (string, required): The billing period for the subscription.
• careMember (object, required): An object containing the ID of the care member.

  • id (string): The ID of the care member.
• patient (object, required): An object containing the ID of the patient.

  • id (string): The ID of the patient.
• paymentTypeInfo (object, required): An object containing the type of payment.

  • paymentType (string): The type of payment for the subscription.
• price (object, required): An object containing the amount and currency of the subscription.

  • amount (number): The amount of the subscription.
  • currency (string): The currency of the subscription.
• startDate (string, required): The start date of the subscription.
• numberOfCycles (number, required): The number of billing cycles for the subscription.

Response

Upon successful creation of the subscription, the response will contain the details of the newly created subscription.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

Body

namestringOptionalExample: Test Cancel Subscription Local

billingPeriodstringOptionalExample: MONTHLY

startDatestringOptionalExample: 2024-08-22T00:00:00.000Z

numberOfCyclesintegerOptionalExample: 6

Responses

201

Created subscription.

⚠️ Unverified: no create/POST implementation for subscriptions was found in the backend — only a GET-by-id client to an external payment-service exists. The response schema is inferred from that client; the request body shape is unconfirmed.

application/json

idstring · uuidOptional

namestring · nullableOptional

statusstringOptional

Commonly one of: NEW, ACTIVE, CANCELED, INCOMPLETE, INCOMPLETE_EXPIRED, PAST_DUE, PAUSED, TRIALING, UNPAID, COMPLETED, NOT_STARTED, RELEASED.

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

post/{tenantName}/{instanceName}/payment/subscriptions

POST /{tenantName}/{instanceName}/payment/subscriptions HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 329

{
  "name": "Test Cancel Subscription Local",
  "billingPeriod": "MONTHLY",
  "careMember": {
    "id": "087cfe51-f8e5-48e7-8bcc-7ccfa470bfc1"
  },
  "patient": {
    "id": "116c667f-2102-4c11-b28d-d71000ca34f2"
  },
  "paymentTypeInfo": {
    "paymentType": "AUTO_CHARGE"
  },
  "price": {
    "amount": 2500,
    "currency": "USD"
  },
  "startDate": "2024-08-22T00:00:00.000Z",
  "numberOfCycles": 6
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "status": "text",
  "pauseCollection": {
    "resumesAt": "2026-01-01T00:00:00.000Z"
  }
}