Documentation menu

TransactKit-Litev1.0.0

TransactKit-Lite API reference

Reference every TransactKit-Lite configuration, Customer, Checkout, Payment, Refund, and webhook endpoint from the v1.0.0 source.

Updated

Access and error boundary

The v1.0.0 boilerplate does not authenticate or authorize Customer, Checkout, Payment, or Refund endpoints. The access labels below describe the source as shipped, not a safe public production policy. The host application must protect them and enforce resource ownership and refund authorization.

Validation and integration errors use application/problem+json. Common mappings include 400 for validation or invalid values, 404 for missing local or Stripe resources, 409 for payment lifecycle conflicts, 429 for Stripe rate limits, 502 for Stripe API failures, and 503 for missing configuration, rejected Stripe credentials/permissions, or connection failures.

Configuration

GET/api/configurationPublic

Reports configuration presence as booleans without exposing either secret.

Successful response

json
{
  "stripeApiConfigured": true,
  "webhookConfigured": true
}

Customers

Customer operations call Stripe directly and do not create a local Customer entity.

POST/api/customersUnauthenticated as shipped

Creates a Stripe Customer and returns an application-owned response DTO.

Parameters

  • email — required, valid email, maximum 254 characters.
  • name — optional, maximum 255 characters.
  • description — optional, maximum 500 characters.
  • metadata — optional, up to 50 entries; keys up to 40 and values up to 500 characters.

Request

json
{
  "email": "buyer@example.com",
  "name": "Example Buyer",
  "description": "Example customer",
  "metadata": { "source": "docs" }
}

Successful response

json
{
  "id": "cus_example",
  "email": "buyer@example.com",
  "name": "Example Buyer",
  "description": "Example customer",
  "metadata": { "source": "docs" }
}

Relevant errors

  • 400 for invalid request fields or Stripe-rejected values.
  • 503 when STRIPE_SECRET_KEY is absent or Stripe credentials, permissions, or connectivity fail.
  • 429 when Stripe rate-limits the request; 502 for Stripe API/server failures.

cURL

cURL
curl -X POST http://localhost:8080/api/customers \
  -H "Content-Type: application/json" \
  -d '{"email":"buyer@example.com","name":"Example Buyer"}'
GET/api/customers/{id}Unauthenticated as shipped

Retrieves the current Stripe Customer and maps it to the same response DTO.

Parameters

  • id — required Stripe Customer ID, maximum 255 characters.

Successful response

json
{
  "id": "cus_example",
  "email": "buyer@example.com",
  "name": "Example Buyer",
  "description": null,
  "metadata": {}
}

Relevant errors

  • 400 for a blank/invalid request value or Stripe-rejected identifier.
  • 404 when Stripe reports that the Customer does not exist.
  • 503/429/502 according to the Stripe error mapping.

Checkout

POST/api/checkout/sessionsUnauthenticated as shipped

Creates or reuses a hosted one-time Checkout attempt. A businessReference identifies the logical local Payment; attemptReference identifies this Checkout attempt.

Parameters

  • amount — required positive long in the currency's minor unit.
  • currency — required three-letter code; persisted and sent to Stripe in lowercase.
  • description — required, maximum 255 characters; becomes the Checkout line-item product name.
  • businessReference — required, maximum 100 characters and unique across local Payments.
  • attemptReference — required, maximum 100 characters.
  • customerEmail — optional valid email, maximum 254 characters.
  • stripeCustomerId — optional, maximum 255 characters; takes precedence over customerEmail.
  • metadata — optional, up to 48 caller entries; paymentId and businessReference are added by the service.

Request

json
{
  "amount": 2000,
  "currency": "usd",
  "description": "Order 1001",
  "businessReference": "order-1001",
  "attemptReference": "attempt-1",
  "customerEmail": "buyer@example.com",
  "metadata": { "cart": "cart-42" }
}

Successful response

json
{
  "paymentId": "00000000-0000-0000-0000-000000000001",
  "checkoutSessionId": "cs_test_example",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_example"
}

Relevant errors

  • 400 for validation failures.
  • 409 when a business reference is reused with a different amount/currency, a payment is settled, an attempt is still processing, or an expired/failed attempt reuses its attemptReference.
  • 503/429/502 according to the Stripe configuration and error mapping.

cURL

cURL
curl -X POST http://localhost:8080/api/checkout/sessions \
  -H "Content-Type: application/json" \
  -d '{"amount":2000,"currency":"usd","description":"Order 1001","businessReference":"order-1001","attemptReference":"attempt-1","customerEmail":"buyer@example.com"}'

Payments

Payment status values are PENDING, PAID, FAILED, PARTIALLY_REFUNDED, and REFUNDED. Checkout status values are OPEN, COMPLETE, and EXPIRED.

GET/api/payments/{id}Unauthenticated as shipped

Returns the local Payment projection. This endpoint does not call Stripe.

Parameters

  • id — local Payment UUID returned by Checkout.

Successful response

json
{
  "id": "00000000-0000-0000-0000-000000000001",
  "businessReference": "order-1001",
  "stripeCustomerId": "cus_example",
  "stripeCheckoutSessionId": "cs_test_example",
  "stripePaymentIntentId": "pi_example",
  "checkoutAttemptReference": "attempt-1",
  "checkoutStatus": "COMPLETE",
  "amount": 2000,
  "refundedAmount": 0,
  "currency": "usd",
  "status": "PAID",
  "createdAt": "2026-09-22T10:00:00Z",
  "updatedAt": "2026-09-22T10:01:00Z"
}

Relevant errors

  • 400 for an invalid UUID.
  • 404 when the local Payment does not exist.

Refunds

POST/api/payments/{id}/refundUnauthenticated as shipped

Creates a Stripe Refund against the Payment's stored PaymentIntent, upserts the local RefundRecord, and recalculates cumulative successful refunds.

Parameters

  • id — local Payment UUID.
  • amount — optional positive minor-unit amount; omit it to refund the full remaining balance.
  • reason — optional DUPLICATE, FRAUDULENT, or REQUESTED_BY_CUSTOMER.
  • reference — required, maximum 100 characters; used in metadata and the Stripe idempotency key.
  • metadata — optional, up to 48 entries; businessReference and refundReference are added.

Request

json
{
  "amount": 500,
  "reason": "REQUESTED_BY_CUSTOMER",
  "reference": "refund-order-1001-1",
  "metadata": { "source": "support" }
}

Successful response

json
{
  "id": "re_example",
  "paymentId": "00000000-0000-0000-0000-000000000001",
  "paymentIntentId": "pi_example",
  "amount": 500,
  "currency": "usd",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "metadata": {
    "businessReference": "order-1001",
    "refundReference": "refund-order-1001-1",
    "source": "support"
  }
}

Relevant errors

  • 400 when amount exceeds the unrefunded balance or validation fails.
  • 404 when the local Payment does not exist.
  • 409 when the Payment has no PaymentIntent or is not PAID/PARTIALLY_REFUNDED.
  • 503/429/502 according to the Stripe configuration and error mapping.

cURL

cURL
curl -X POST http://localhost:8080/api/payments/00000000-0000-0000-0000-000000000001/refund \
  -H "Content-Type: application/json" \
  -d '{"amount":500,"reason":"REQUESTED_BY_CUSTOMER","reference":"refund-order-1001-1"}'
GET/api/refunds/{id}Unauthenticated as shipped

Retrieves current Refund state from Stripe. paymentId is populated only when a local RefundRecord already associates the Stripe Refund with a local Payment.

Parameters

  • id — required Stripe Refund ID, maximum 255 characters.

Successful response

json
{
  "id": "re_example",
  "paymentId": "00000000-0000-0000-0000-000000000001",
  "paymentIntentId": "pi_example",
  "amount": 500,
  "currency": "usd",
  "status": "succeeded",
  "reason": "requested_by_customer",
  "metadata": {}
}

Relevant errors

  • 400/404 for Stripe-rejected or missing Refund IDs.
  • 503/429/502 according to the Stripe error mapping.

Webhook

POST/api/stripe/webhookPublic Stripe delivery endpoint

Verifies the exact raw JSON body with Stripe-Signature, claims the Stripe event ID, and synchronizes supported Checkout or Refund projections.

Headers

  • Content-Type: application/json
  • Stripe-Signature: <Stripe-generated signature>

Request

json
<exact raw Stripe event JSON>

Successful response

json
{
  "eventId": "evt_example",
  "eventType": "checkout.session.completed",
  "status": "PROCESSED",
  "duplicate": false
}

Relevant errors

  • 400 for a missing/invalid signature, malformed event JSON, or incompatible request.
  • 503 when STRIPE_WEBHOOK_SECRET is absent.
  • A supported processing failure is returned as an error and its durable event claim is marked FAILED for retry.
Complete webhook behavior