Setup

Overview

The /api/v1/payments/setup endpoint allows third-party applications to initiate setup intents for processing payments. This endpoint creates a setup intent with the specified amount and supported payment method types, returning a setup intent secret for client-side payment processing.

Base URLs

• Production: https://api.care360-next.carevalidate.com/api/v1/payments/setup
• Staging: https://api-staging.care360-next.carevalidate.com/api/v1/payments/setup

Method: POST

Authentication

Required Headers

cv-api-key: your-secret-api-key
Content-Type: application/json

The cv-api-key is your organization's secret API key provided by CareValidate.

Request Body

Parameter	Type	Required	Description
metadata	object	No	Optional metadata to be stored with the setup intent

Request Examples

Setup Intent

{
  "metadata": {   // optional
    "email": "testemail@example.com",   // optional
    "phone": "+1404567890"   // optional
  }
}

Response Format

Success Response

HTTP Status: 200 OK

{
  "success": true,
  "paymentSecret": "pi_3SG0o8GkkQS2eXzh0BKpSaq0_secret_CBrwqmT726jzfcnvCt0qBcS9e"
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the setup intent was created successfully
paymentSecret	string	Secret key for client-side payment processing

cURL Examples

Create Setup Intent

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/payments/setup" \
  -H "cv-api-key: YOUR_SECRET_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {   // optional
      "email": "testemail@example.com",   // optional
      "phone": "+1404567890"   // optional
    }
  }'

Create Setup Intent (Minimal)

curl -X POST "https://api.care360-next.carevalidate.com/api/v1/payments/setup" \
  -H "cv-api-key: YOUR_SECRET_KEY_HERE"

Error Responses

Authentication Errors

HTTP Status: 401 Unauthorized

{
  "status": 401,
  "error": "Invalid API key"
}

Internal Server Error

HTTP Status: 500 Internal Server Error

{
  "success": false,
  "message": "Internal server error"
}

Changelog

Version	Date	Changes
1.0	2026-02-03	Initial Payment Setup API documentation