> ## 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.

# Card Payment Initialization

> Learn how to initialize card payments securely via the Juicyway API

export const payment_method_0 = "card"

## Overview

Card payment initialization is the first step in processing a card payment. This endpoint creates a payment session that can be used to securely process credit and debit card transactions.

## Endpoint

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

## Request Parameters

<ParamField body="amount" type="integer" required>
  Payment amount in minor units (e.g., cents, kobo)

  * Minimum: 100

  * Must be positive integer

  * Example: 10000 = \$100.00 USD
</ParamField>

<ParamField body="currency" type="string" required>
  ISO currency code

  * Supported: NGN, USD, CAD, USDT, USDC

  * Must match payment method

  * Example: "USD"
</ParamField>

<ParamField body="customer" type="object" required>
  Customer information object

  <Expandable title="Customer Fields">
    <ParamField body="email" type="string" required>
      Valid email address
    </ParamField>

    <ParamField body="first_name" type="string" required>
      Customer's first name
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Customer's last name
    </ParamField>

    <ParamField body="phone_number" type="string" required>
      Phone number in E.164 format
    </ParamField>

    <ParamField body="billing_address" type="object" required>
      Billing address details
    </ParamField>

    <ParamField body="type" type="string" required>
      Must be of type `business` or `individual`
    </ParamField>

    <ParamField body="ip_address" type="string" required>
      Customer's ip address

      * Must be ipv4 e.g 127.0.0.1
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="description" type="string" required>
  Payment description

  * Maximum length: 200 characters

  * Will appear on statements
</ParamField>

<ParamField body="reference" type="string" required>
  Unique transaction reference

  * Must be unique per transaction

  * Maximum length: 50 characters
</ParamField>

<ParamField body="payment_method" type="object" required>
  Payment method details

  <ParamField body="type" type="string" required>
    * Must be of type: "{payment_method_0}"
  </ParamField>
</ParamField>

<ParamField body="order" type="object" required>
  Order information object

  <Expandable title="Order Fields">
    <ParamField body="identifier" type="string" required>
      Unique identifier
    </ParamField>

    <ParamField body="items" type="object[]" required>
      <Expandable title="Items Fields">
        <ParamField type="string" body="name" required />

        <ParamField type="string" body="type" required>
          type must be one of digital,physical
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Optional additional data

  * Nested objects allowed
</ParamField>

## Example Requests

<CodeGroup>
  ```json Basic Card Payment theme={null}
  {
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone_number": "+2348118873422",
      "billing_address": {
        "line1": "123 Main St",
        "line2": "Suite 456",
        "city": "Springfield",
        "state": "CA",
        "country": "US",
        "zip_code": "12345"
      },
      "ip_address": "127.0.0.1"
    },
    "description": "Premium Package Purchase",
    "currency": "USD",
    "amount": 100000,
    "payment_method": {
      "type": "card"
    },
    "reference": "ord_1234567890",
    "order": {
      "identifier": "ORD12345",
      "items": [
        {
          "name": "Premium Package",
          "type": "digital"
        }
      ]
    }
  }
  ```

  ```json International Card Payment theme={null}
  {
    "customer": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone_number": "+2348012345678",
      "billing_address": {
        "line1": "10 Victoria Island",
        "city": "Lagos",
        "state": "Lagos",
        "country": "NG",
        "zip_code": "23401"
      },
      "ip_address": "127.0.0.1"
    },
    "description": "International Purchase",
    "currency": "NGN",
    "amount": 500000,
    "payment_method": {
      "type": "card"
    },
    "reference": "ord_intl_12345",
    "order": {
      "identifier": "INTL12345",
      "items": [
        {
          "name": "International Package",
          "type": "digital"
        }
      ]
    },
  }
  ```
</CodeGroup>

## Test Cards

Use these test cards in your sandbox environment to simulate different payment scenarios:

<AccordionGroup>
  <Accordion title="Successful Payments">
    **VISA Test Card (NGN)**

    * Card Number: 4012000033330026
    * Expiry Date: 01/39
    * CVV: 100

    **Mastercard Test Card (USD)**

    * Card Number: 5123450000000008
    * Expiry Date: 12/25
    * CVV: 100
  </Accordion>

  <Accordion title="3DS Authentication Required">
    **VISA 3DS Test Card**

    * Card Number: 4761530000000008
    * Expiry Date: 05/25
    * CVV: 100
    * Test OTP: 123456

    **Mastercard 3DS Test Card**

    * Card Number: 5200000000001005
    * Expiry Date: 12/25
    * CVV: 100
    * Test OTP: 123456
  </Accordion>

  <Accordion title="Failed Transactions">
    **Insufficient Funds**

    * Card Number: 4000000000000010
    * Expiry Date: 01/25
    * CVV: 100

    **Declined Card**

    * Card Number: 4000000000000002
    * Expiry Date: 01/25
    * CVV: 100
  </Accordion>
</AccordionGroup>

## Response Examples

<CodeGroup>
  ```json 201 Success - Payment Session Created theme={null}
  {
    "data": {
      "auth_type": "3ds",
      "expires_at": "2024-03-01T08:43:08.110470Z",
      "links": {},
      "message": "Created",
      "payment": {
        "amount": 100000,
        "cancellation_reason": null,
        "currency": "USD",
        "customer": {
          "billing_address": {
            "city": "Springfield",
            "country": "US",
            "line1": "123 Main St",
            "line2": "Suite 456",
            "state": "CA",
            "zip_code": "12345"
          },
          "email": "john.doe@example.com",
          "first_name": "John",
          "id": "cust_1234567890",
          "last_name": "Doe",
          "phone_number": "+2348118873422"
        },
        "date": "2024-02-29T20:43:08.344264Z",
        "description": "Premium Package Purchase",
        "id": "pay_1234567890",
        "order": {
          "identifier": "ORD12345",
          "items": [
            {
              "name": "Premium Package",
              "type": "digital"
            }
          ]
        }
        "mode": "live",
        "payment_method": {
          "type": "card"
        },
        "reference": "ord_1234567890",
        "status": "pending"
      },
      "status": "pending"
    }
  }
  ```

  ```json 400 Invalid Request theme={null}
  {
    "error": {
      "code": "invalid_request",
      "message": "The request was invalid",
      "details": {
        "amount": ["Amount must be at least 100000"]
      }
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "error": {
      "code": "validation_error",
      "message": "The request contains invalid parameters",
      "details": {
        "currency": ["Currency must be one of: NGN, USD, CAD"]
      }
    }
  }
  ```
</CodeGroup>

## Authentication Flows

Some card payments may require additional authentication steps. The response will indicate the required authentication type:

<Steps>
  <Step title="3D Secure Authentication">
    If 3DS is required, you'll receive:

    ```json theme={null}
    {
      "data": {
        "auth_type": "3ds",
        "message": "3DS authentication required",
        "links": {
          "redirect_url": "https://3ds.payment-processor.com/auth"
        }
      }
    }
    ```

    Redirect the customer to complete 3DS verification, then:

    1. Listen for webhook notification, or
    2. Poll payment status endpoint
  </Step>

  <Step title="OTP Validation">
    For OTP authentication:

    ```json theme={null}
    {
      "data": {
        "auth_type": "otp",
        "message": "Please enter OTP to complete transaction"
      }
    }
    ```

    Submit OTP via:

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

  <Step title="PIN Verification">
    For PIN authentication:

    ```json theme={null}
    {
      "data": {
        "auth_type": "pin",
        "message": "Please enter card PIN"
      }
    }
    ```

    Submit PIN via:

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

## Security Requirements

<AccordionGroup>
  <Accordion title="Data Encryption">
    * All card data must be encrypted before transmission
    * Use our [encryption guide](/payments/encryption-keys) for implementation
    * Never log or store raw card details
  </Accordion>

  <Accordion title="PCI Compliance">
    * Use our secure payment fields when collecting card data
    * Follow PCI DSS requirements if handling card data
    * Implement proper data sanitization
  </Accordion>

  <Accordion title="API Authentication">
    * Use HTTPS for all API calls
    * Include proper authorization headers
    * Rotate API keys regularly
  </Accordion>
</AccordionGroup>

## Error Handling

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

  * Status code: 402
  * Possible reasons:
    * Insufficient funds
    * Suspicious activity
    * Expired card
</ResponseField>

<ResponseField name="invalid_card" type="error">
  Invalid card details provided

  * Status code: 400
  * Check:
    * Card number
    * Expiry date
    * CVV
</ResponseField>

<ResponseField name="authentication_failed" type="error">
  Failed authentication (3DS/OTP/PIN)

  * Status code: 401
  * Verify credentials and retry
</ResponseField>

<Warning>
  Common error scenarios to handle:

  * Invalid currency code
  * Amount below minimum
  * Missing customer information
  * Invalid phone/email format
  * Incorrect billing address
  * Network timeouts
</Warning>

## Next Steps

After successful initialization:

1. Handle any required authentication
2. [Capture the payment](/payments/capture-payment/cards)
3. Listen for [webhook notifications](/webhooks)

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