> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.aura-app.ai/llms.txt > Use this file to discover all available pages before exploring further. # Record payment > Record a payment from any source (Stripe, WOP, manual, etc.). Send an `Idempotency-Key` header when retrying the same create request. A completed retry returns the existing payment. A request still being processed returns 409. Use a new key for a different payment. **Use Cases:** - Record payments from external payment processors - Manual payment entry for offline transactions - Sync payments from partner platforms **Required fields:** - `lead_id` - Associated lead UUID - `amount` - Amount in dollars, stored to two decimal places - `payment_date` - ISO 8601 date - `status` - Payment status - `source` - Payment source identifier Record a payment from any source (Stripe, WOP, manual, etc.). Send an `Idempotency-Key` header when retrying the same create request. A completed retry returns the existing payment. A request still being processed returns 409. Use a new key for a different payment. **Use Cases:** * Record payments from external payment processors * Manual payment entry for offline transactions * Sync payments from partner platforms **Required fields:** * `lead_id` - Associated lead UUID * `amount` - Amount in dollars, stored to two decimal places * `payment_date` - ISO 8601 date * `status` - Payment status * `source` - Payment source identifier ## OpenAPI ````yaml openapi.json POST /v1/payments openapi: 3.1.0 info: contact: email: support@aura-app.ai name: Aura Support description: >- # Aura Partner Integrations API > **Alpha Release** - This API is under active development. Endpoints, request/response schemas, and behaviors may change without prior notice. We recommend pinning to specific response fields you need and handling unknown fields gracefully. Enterprise REST API for external partner integrations including commission platforms, external mobile apps, and client booking widgets. ## MCP Connector Aura also exposes a **Model Context Protocol** server at `/mcp` so AI assistants (Claude, ChatGPT) can answer questions about a user's own sales data. If you are building an assistant integration rather than a server-to-server one, that is almost certainly the surface you want — it is task-shaped ("prep me for my next call") rather than resource-shaped, and it handles auth per-user. Read-only. OAuth 2.1 + PKCE, with Clerk as the authorization server; discover it from `/.well-known/oauth-protected-resource`. Setup guide: https://docs.api.aura-app.ai/mcp-connector ## Authentication Authenticated endpoints support two authentication methods: **1. API Key (for partners and integrations):** ``` Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx ``` Get your API key from the Aura dashboard at Settings > API Keys. **2. Clerk JWT (for mobile and web apps):** ``` Authorization: Bearer ``` Use Clerk's authentication SDK to obtain a JWT token with org claims. ## Rate Limiting - **Per API Key:** 100 requests/minute - **Per Organization:** 1000 requests/minute Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests allowed - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when limit resets These counters are held per serving instance, so under concurrency the effective ceiling is higher than the number above and the headers describe one instance's view rather than a global total. Treat a 429 as backpressure to obey and pace your client to the documented rate — but do not rely on us to reject your 101st request, and do not derive a global remaining-quota figure from the headers. The limit may become globally enforced without notice, so a client that stays within it will not be affected when that happens. ## Pagination List endpoints support cursor-based pagination: - `limit`: Number of results per page (default: 50, max: 100) - `cursor`: Opaque cursor for next page ## Error Handling All errors follow a standard format: ```json { "success": false, "error": "Error message", "code": "ERROR_CODE" } ``` Common HTTP status codes: - **400** Bad Request - Invalid input (`VALIDATION_ERROR`) - **401** Unauthorized - Missing or invalid API key (`AUTHENTICATION_ERROR`) - **402** Payment Required - The key is valid, but the organization's subscription is not active (`PAYMENT_REQUIRED`). Every authenticated endpoint can return this. Retrying will not help until the account's payment method is updated in Aura; surface it to the account owner rather than treating it as an auth failure. - **403** Forbidden - Insufficient permissions (`AUTHORIZATION_ERROR`) - **404** Not Found - Resource not found (`NOT_FOUND`) - **409** Conflict - Resource state prevents the operation (`CONFLICT`) - **413** Payload Too Large - Request body exceeds 256KB (`PAYLOAD_TOO_LARGE`) - **429** Too Many Requests - Rate limit exceeded (`RATE_LIMIT_EXCEEDED`) - **500** Internal Server Error - Server error (`INTERNAL_ERROR`) ## Webhooks Subscribe to real-time events using the Webhooks API. All webhook payloads are signed with HMAC-SHA256 for security verification. Delivery is at-least-once. Every payload carries an `idempotency_key` that is stable across retries of the same event, so you can enforce exactly-once with a `(subscription_id, idempotency_key)` unique constraint on your side. For full documentation, visit [docs.aura-app.ai/api](https://docs.aura-app.ai/api) license: name: Proprietary title: Aura Partner Integrations API version: 1.0.0-alpha servers: - description: Production url: https://api.aura-app.ai - description: Staging url: https://staging-api.aura-app.ai - description: Local Development url: http://localhost:3001 security: - bearerAuth: [] tags: - description: Lead management operations name: Leads - description: Call booking and management name: Calls - description: Booking link configuration (read-only) name: Booking Links - description: Product catalog (read-only) name: Products - description: Payment tracking (read-only) name: Payments - description: Public booking creation name: Bookings - description: Real-time event subscriptions and webhook management name: Webhooks - description: >- Team member information for commission attribution. **Alpha** - schema may change without notice. name: Team (Alpha) - description: >- Dashboard analytics, lead source attribution, and objection analysis. **Alpha** - schema may change without notice. name: Analytics (Alpha) - description: System endpoints (health checks) name: System paths: /v1/payments: post: tags: - Payments summary: Record payment description: >- Record a payment from any source (Stripe, WOP, manual, etc.). Send an `Idempotency-Key` header when retrying the same create request. A completed retry returns the existing payment. A request still being processed returns 409. Use a new key for a different payment. **Use Cases:** - Record payments from external payment processors - Manual payment entry for offline transactions - Sync payments from partner platforms **Required fields:** - `lead_id` - Associated lead UUID - `amount` - Amount in dollars, stored to two decimal places - `payment_date` - ISO 8601 date - `status` - Payment status - `source` - Payment source identifier parameters: - description: >- Optional retry key scoped to your organization. Reuse the same key and request body when retrying one create. Use a new key for a different create. A completed request returns the existing resource; a request still in progress returns 409. in: header name: Idempotency-Key required: false schema: description: >- Optional retry key scoped to your organization. Reuse the same key and request body when retrying one create. Use a new key for a different create. A completed request returns the existing resource; a request still in progress returns 409. example: 8f3a1c2e-3b9d-4f5a-9c7e-1a2b3c4d5e6f type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePaymentBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/PaymentSuccessResponse' description: Successfully recorded payment '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid or missing API key '402': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The organization's subscription is not active headers: X-Request-Id: description: Request identifier for support schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The API key does not have the required scope headers: X-Request-Id: description: Request identifier for support schema: type: string '408': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- The request exceeded its processing time limit. Check the outcome before retrying a write headers: X-Request-Id: description: Request identifier for support schema: type: string '413': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The request body exceeds 256KB headers: X-Request-Id: description: Request identifier for support schema: type: string '429': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: Rate limit exceeded. Wait before retrying headers: Retry-After: description: Seconds to wait before retrying schema: type: string X-RateLimit-Limit: description: Requests allowed in the current window schema: type: string X-RateLimit-Remaining: description: Requests remaining in the current window schema: type: string X-RateLimit-Reset: description: Window reset as a Unix timestamp schema: type: string X-Request-Id: description: Request identifier for support schema: type: string '500': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- Unexpected server failure. Include the request identifier when contacting support headers: X-Request-Id: description: Request identifier for support schema: type: string security: - bearerAuth: [] components: schemas: CreatePaymentBody: properties: amount: description: >- Payment amount in dollars, stored to two decimal places. For example, 5000.00 means five thousand dollars. The database rounds additional decimal places. Create, update, and payment reads use the same unit. example: 5000 exclusiveMinimum: true minimum: 0 type: number call_id: description: Call ID this payment is linked to type: string currency: default: USD description: >- Supported currency code, such as USD. Defaults to USD when omitted. Whitespace and letter case are normalized. example: USD type: string external_id: description: External payment/transaction ID example: pi_3abc123 type: string lead_id: description: Lead ID this payment is from example: 550e8400-e29b-41d4-a716-446655440000 type: string payment_date: description: ISO 8601 payment date example: '2026-01-17T08:00:00Z' format: date-time type: string product_id: description: Product ID this payment is for type: string source: description: Payment source (e.g., "stripe", "wop", "manual") example: manual type: string status: description: Payment status enum: - pending - succeeded - failed - refunded example: succeeded type: string required: - lead_id - amount - payment_date - status - source type: object PaymentSuccessResponse: properties: data: $ref: '#/components/schemas/Payment' success: enum: - true type: boolean required: - success - data type: object ErrorResponse: properties: code: description: Error code for programmatic handling example: NOT_FOUND type: string error: description: Human-readable error message example: Lead not found type: string requestId: description: Request ID for support debugging example: req_abc123 type: string success: enum: - false type: boolean required: - success - error - code type: object MiddlewareErrorResponse: properties: code: type: string error: type: string requestId: type: string success: enum: - false type: boolean required: - success - error - code type: object Payment: properties: amount: description: Payment amount (in dollars with decimals) example: 5000 type: number call_id: description: Associated call ID nullable: true type: string created_at: description: Creation timestamp format: date-time type: string currency: description: Currency code example: usd type: string customer_email: description: Customer email nullable: true type: string customer_name: description: Customer name nullable: true type: string id: description: Unique identifier example: 550e8400-e29b-41d4-a716-446655440000 type: string lead_id: description: Associated lead ID nullable: true type: string match_candidates: $ref: '#/components/schemas/PaymentMatchCandidates' match_confidence: description: Match confidence score 0.00-1.00 nullable: true type: number matched_by: description: How the payment was matched (email_exact, email+amount, etc.) nullable: true type: string matched_product_id: description: Matched Aura product ID nullable: true type: string organization_id: description: Organization ID type: string payment_date: description: Payment date format: date-time type: string provider: description: Payment provider (e.g., stripe) example: stripe type: string provider_customer_id: description: Customer ID assigned by the payment provider. Null when unavailable. nullable: true type: string provider_payment_id: description: Payment ID from provider example: pi_xxxxx type: string provider_refund_id: description: >- Latest provider refund ID, or a stable source-event identity when the provider supplies none. Ablefy uses ablefy_revoke: followed by its order ID. Null when unavailable. nullable: true type: string refund_reason: description: Refund reason from Stripe nullable: true type: string refund_status: description: Refund status (partial, full, or null) nullable: true type: string refunded_amount: description: Total refunded amount nullable: true type: number refunded_at: description: Timestamp of most recent refund format: date-time nullable: true type: string status: description: Payment status (succeeded, pending, failed, refunded) example: succeeded type: string stripe_charge_id: description: Stripe charge ID (ch_*) nullable: true type: string stripe_customer_id: deprecated: true description: >- Deprecated alias of provider_customer_id. Contains the same provider-neutral value. nullable: true type: string stripe_product_id: description: Stripe Product ID (prod_*) nullable: true type: string stripe_refund_id: deprecated: true description: >- Deprecated alias of provider_refund_id. Contains the same provider-neutral value. nullable: true type: string stripe_subscription_id: description: Stripe subscription ID (sub_*) nullable: true type: string verification_status: description: Payment verification status (unverified, confirmed, unmatched) example: confirmed nullable: true type: string verified_at: description: When the payment was verified format: date-time nullable: true type: string required: - id - organization_id - provider - provider_payment_id - amount - currency - status - customer_email - customer_name - lead_id - call_id - payment_date - created_at - verification_status - verified_at - stripe_charge_id - provider_customer_id - stripe_customer_id - stripe_subscription_id - matched_by - match_confidence - match_candidates - refund_status - refunded_amount - refunded_at - provider_refund_id - stripe_refund_id - refund_reason - stripe_product_id - matched_product_id type: object PaymentMatchCandidates: description: >- Top candidates the matching pipeline considered for this payment, ordered by score (highest first). Null when the payment was deterministically matched. See the PaymentMatchCandidate schema for the per-candidate shape. items: $ref: '#/components/schemas/PaymentMatchCandidate' nullable: true type: array PaymentMatchCandidate: anyOf: - $ref: '#/components/schemas/LeadMatchCandidate' - $ref: '#/components/schemas/CallMatchCandidate' LeadMatchCandidate: additionalProperties: nullable: true properties: confidence: description: Match confidence 0-1. Higher is a better match. example: 0.7 type: number email: description: Candidate lead's email, as matched against. nullable: true type: string lead_id: description: Candidate lead ID. type: string name: description: Candidate lead's full name. nullable: true type: string reason: description: How the candidate was found, e.g. 'email_exact', 'name_fuzzy'. example: email_exact type: string required: - lead_id - email - name - confidence - reason type: object CallMatchCandidate: additionalProperties: nullable: true properties: call_id: description: Candidate call ID. type: string confidence: description: Match confidence 0-1. type: number expected_deal_value: description: Expected deal value on the call, in dollars. nullable: true type: number lead_email: description: The lead's email. type: string lead_id: description: The call's lead. type: string match_reasons: description: Signals that made this call a candidate. items: type: string type: array product_id: description: Product discussed on the call. nullable: true type: string scheduled_at: description: When the call was booked. type: string required: - call_id - lead_id - lead_email - scheduled_at - product_id - expected_deal_value - confidence - match_reasons type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.