> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Collection

> Collect payments from signers during the signing flow using Stripe integration.

## Overview

DocuTrust integrates with Stripe to collect payments as part of the signing workflow. Add a payment field to any template, and signers will be prompted to pay before completing their submission. Supports one-time charges with configurable amounts and currencies.

## Configure Stripe

Connect your Stripe account to enable payment collection.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/settings/payments/update_config" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "stripe_secret_key": "sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
      "stripe_publishable_key": "pk_live_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3",
      "currency": "usd",
      "webhook_secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "message": "Stripe configuration saved successfully",
    "configured": true,
    "currency": "usd",
    "livemode": true
  }
  ```
</ResponseExample>

## Check Configuration

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://spitshake.io/api/settings/payments/config" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "configured": true,
    "currency": "usd",
    "livemode": true,
    "publishable_key": "pk_live_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3"
  }
  ```

  ```json 200 — Not Configured theme={null}
  {
    "configured": false,
    "currency": null,
    "livemode": false,
    "publishable_key": null
  }
  ```
</ResponseExample>

## Create Payment Intent

When a signer reaches a payment field, create a Stripe PaymentIntent to begin the checkout process.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/payments/{submission_id}/create_intent" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "currency": "usd",
      "description": "NDA signing fee - Project Alpha",
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001",
      "metadata": {
        "template_name": "NDA Agreement",
        "submitter_email": "jane@example.com"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "payment_intent_id": "pi_3P4Q5R6S7T8U9V0W",
    "client_secret": "pi_3P4Q5R6S7T8U9V0W_secret_X1Y2Z3A4B5C6D7E8",
    "amount": 5000,
    "currency": "usd",
    "status": "requires_payment_method",
    "description": "NDA signing fee - Project Alpha",
    "created_at": "2026-04-08T15:00:00Z"
  }
  ```

  ```json 422 — Invalid Amount theme={null}
  {
    "error": "Amount must be a positive integer representing cents (e.g., 5000 for $50.00)."
  }
  ```
</ResponseExample>

## Confirm Payment

After the signer completes payment on the client side, confirm the payment was successful.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://spitshake.io/api/payments/{submission_id}/confirm" \
    -H "X-Auth-Token: YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "payment_intent_id": "pi_3P4Q5R6S7T8U9V0W",
      "field_uuid": "f1a2b3c4-d5e6-7890-abcd-000000000001"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "payment_intent_id": "pi_3P4Q5R6S7T8U9V0W",
    "amount": 5000,
    "currency": "usd",
    "status": "succeeded",
    "receipt_url": "https://pay.stripe.com/receipts/payment/CAcaFwoVYWNjdF8xT...",
    "confirmed_at": "2026-04-08T15:02:30Z"
  }
  ```

  ```json 402 — Payment Failed theme={null}
  {
    "success": false,
    "payment_intent_id": "pi_3P4Q5R6S7T8U9V0W",
    "amount": 5000,
    "currency": "usd",
    "status": "requires_payment_method",
    "error": "Your card was declined. Please try a different payment method.",
    "confirmed_at": null
  }
  ```
</ResponseExample>

### Stored Payment Data

After successful payment, the following object is saved to the submitter's `values` hash under the corresponding field UUID:

```json theme={null}
{
  "payment_intent_id": "pi_3P4Q5R6S7T8U9V0W",
  "amount": 5000,
  "currency": "usd",
  "status": "succeeded",
  "receipt_url": "https://pay.stripe.com/receipts/payment/CAcaFwoVYWNjdF8xT...",
  "paid_at": "2026-04-08T15:02:30Z"
}
```

## Get Payment Status

Check the status of a payment for a specific submission.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://spitshake.io/api/payments/{submission_id}/status?field_uuid=f1a2b3c4-d5e6-7890-abcd-000000000001" \
    -H "X-Auth-Token: YOUR_API_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — Paid theme={null}
  {
    "paid": true,
    "payment_intent_id": "pi_3P4Q5R6S7T8U9V0W",
    "amount": 5000,
    "currency": "usd",
    "status": "succeeded",
    "receipt_url": "https://pay.stripe.com/receipts/payment/CAcaFwoVYWNjdF8xT...",
    "paid_at": "2026-04-08T15:02:30Z"
  }
  ```

  ```json 200 — Not Paid theme={null}
  {
    "paid": false,
    "payment_intent_id": null,
    "amount": null,
    "currency": null,
    "status": null,
    "receipt_url": null,
    "paid_at": null
  }
  ```
</ResponseExample>

## Supported Currencies

Amounts are always specified in the smallest currency unit (e.g., cents for USD). Supported currencies include:

| Currency          | Code  | Smallest Unit | Example          |
| ----------------- | ----- | ------------- | ---------------- |
| US Dollar         | `usd` | cents         | `5000` = \$50.00 |
| Euro              | `eur` | cents         | `5000` = 50.00   |
| British Pound     | `gbp` | pence         | `5000` = 50.00   |
| Canadian Dollar   | `cad` | cents         | `5000` = \$50.00 |
| Australian Dollar | `aud` | cents         | `5000` = \$50.00 |
| Japanese Yen      | `jpy` | yen           | `5000` = 5,000   |

All currencies supported by Stripe are available. See [Stripe's currency documentation](https://stripe.com/docs/currencies) for the full list.