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

# Cards

# Card Payment Capture

This guide explains how to capture an authorized card payment. The capture request processes the actual charge against the customer's card after authentication.

## Overview

<Note>
  Before capturing a payment, ensure:

  1. You have a valid payment session ID from initialization
  2. Any required card data is encrypted following our [encryption guide](/payments/encryption-keys)
  3. You can handle authentication flows if needed
</Note>

## Endpoint

```bash theme={null}
POST /payment-sessions/{payment_id}
```

## Request Parameters

<ParamField body="card" type="object" required>
  Encrypted card payment details

  <Expandable title="Card Object">
    <ParamField body="card_number" type="string" required>
      Encrypted card number (PAN)
    </ParamField>

    <ParamField body="cvv" type="string" required>
      Encrypted CVV/CVC
    </ParamField>

    <ParamField body="expiry_month" type="integer" required>
      Card expiry month (1-12)
    </ParamField>

    <ParamField body="expiry_year" type="integer" required>
      Card expiry year (current or future)
    </ParamField>
  </Expandable>
</ParamField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.spendjuice.com/payment-sessions/{payment_id}" \
    -H "Authorization:  YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "card": {
        "card_number": "encrypted_card_number",
        "cvv": "encrypted_cvv", 
        "expiry_month": 1,
        "expiry_year": 39
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    `https://api.spendjuice.com/payment-sessions/${paymentId}`,
    {
      method: 'POST',
      headers: {
        'Authorization': ` ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        card: {
          card_number: encryptedCardNumber,
          cvv: encryptedCvv,
          expiry_month: 1,
          expiry_year: 39
        }
      })
    }
  );
  ```
</CodeGroup>

## Authentication Flows

Some card payments require additional authentication after capture:

### 3D Secure (3DS)

<Steps>
  <Step title="Capture Response">
    ```json theme={null}
    {
      "data": {
        "status": "authenticating",
        "auth_type": "3ds",
        "message": "3D Secure authentication required",
        "links": {
          "redirect_url": "https://3ds.issuer-bank.com/auth"
        }
      }
    }
    ```
  </Step>

  <Step title="3DS Verification">
    Redirect customer to provided URL to complete 3DS
  </Step>

  <Step title="Wait for Completion">
    Monitor webhooks or status endpoint for final result
  </Step>
</Steps>

### One-Time Password (OTP)

<Steps>
  <Step title="Capture Response">
    ```json theme={null}
    {
      "data": {
        "status": "authenticating",
        "auth_type": "otp",
        "message": "OTP sent to registered phone number"
      }
    }
    ```
  </Step>

  <Step title="Submit OTP">
    ```bash theme={null}
    POST /payment-sessions/{payment_id}/authorize
    {
      "otp": "123456"
    }
    ```
  </Step>
</Steps>

### PIN Verification

<Steps>
  <Step title="Capture Response">
    ```json theme={null}
    {
      "data": {
        "status": "authenticating",
        "auth_type": "pin",
        "message": "Enter card PIN"
      }
    }
    ```
  </Step>

  <Step title="Submit PIN">
    ```bash theme={null}
    POST /payment-sessions/{payment_id}/authorize
    {
      "pin": "1234"
    }
    ```
  </Step>
</Steps>

## Error Handling

<ResponseField name="card_declined" type="error">
  Card declined by issuing bank

  * Status code: 402
  * Common reasons:
    * Insufficient funds
    * Invalid card
    * Suspicious activity
</ResponseField>

<ResponseField name="authentication_required" type="error">
  Additional authentication needed

  * Status code: 401
  * Next steps:
    * Handle 3DS redirect
    * Collect OTP/PIN
    * Retry with authentication
</ResponseField>

## Best Practices

1. **Authentication Flow**
   * Handle all authentication types (3DS, OTP, PIN)
   * Provide clear user feedback during auth
   * Implement proper timeouts and retries
   * Monitor auth completion via webhooks
2. **Error Handling**
   * Implement exponential backoff for retries
   * Show user-friendly error messages
   * Log errors with payment IDs
   * Handle timeouts gracefully
3. **Security**
   * Never log decrypted card data
   * Use HTTPS for all requests
   * Clear sensitive data after use
   * Monitor for unusual patterns

<Card title="Need Help?">
  * See [Error Handling Guide](/errors)
  * Review [Authentication](/authentication)
  * Contact [Support](mailto:support@juicyway.com)
</Card>