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

# Quickstart Guide

> Get up and running with Notch Pay in minutes

<Note>
  This guide will help you integrate Notch Pay into your application or website quickly. We'll walk through the basic steps to accept your first payment.
</Note>

<Card title="Prerequisites" icon="list-check" color="#16A34A">
  Before you begin, make sure you have:

  <CheckboxList>
    <Checkbox checked>
      A Notch Pay account (sign up at [business.notchpay.co](https://business.notchpay.co/register) if you don't have one)
    </Checkbox>

    <Checkbox checked>
      Your API keys (available in your dashboard under Settings > API Keys)
    </Checkbox>

    <Checkbox checked>
      Basic knowledge of HTTP requests and JSON
    </Checkbox>
  </CheckboxList>
</Card>

## Integration Steps

<Steps>
  <Step title="Get Your API Keys">
    <Tabs>
      <Tab title="From Dashboard">
        1. Log in to your [Notch Pay Business suite](https://business.notchpay.co)
        2. Navigate to Settings > API Keys
        3. Copy your API key (use your test key for development and testing)
      </Tab>

      <Tab title="Test vs Live">
        <Callout type="warning">
          Always use **test keys** during development and testing. Only switch to **live keys** when you're ready to process real transactions.
        </Callout>

        Test keys contains `test_` while live keys doesn't.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a Simple Payment">
    Let's create a basic payment using the Notch Pay API:

    <CodeGroup>
      ```javascript JavaScript theme={null}
      // Using fetch in JavaScript
      fetch('https://api.notchpay.co/payments', {
        method: 'POST',
        headers: {
          'Authorization': 'YOUR_PUBLIC_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          amount: 5000,
          currency: 'XAF',
          customer: {
            name: 'John Doe',
            email: 'john@example.com',
            phone: '+237600000000'
          },
          description: 'Payment for Order #123',
          callback: 'https://your-website.com/callback',
          reference: 'order_123'
        })
      })
      .then(response => response.json())
      .then(data => {
        // Redirect the customer to the payment page
        window.location.href = data.authorization_url;
      })
      .catch(error => console.error('Error:', error));
      ```

      ```php PHP theme={null}
      <?php
      $curl = curl_init();

      curl_setopt_array($curl, [
        CURLOPT_URL => "https://api.notchpay.co/payments",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
          "Authorization: YOUR_PUBLIC_KEY",
          "Content-Type: application/json"
        ],
        CURLOPT_POSTFIELDS => json_encode([
          "amount" => 5000,
          "currency" => "XAF",
          "customer" => [
            "name" => "John Doe",
            "email" => "john@example.com",
            "phone" => "+237600000000"
          ],
          "description" => "Payment for Order #123",
          "callback" => "https://your-website.com/callback",
          "reference" => "order_123"
        ])
      ]);

      $response = curl_exec($curl);
      $data = json_decode($response, true);
      curl_close($curl);

      // Redirect the customer to the payment page
      header("Location: " . $data["authorization_url"]);
      exit();
      ```

      ```python Python theme={null}
      import requests
      import json
      from flask import redirect

      url = "https://api.notchpay.co/payments"
      headers = {
          "Authorization": "YOUR_PUBLIC_KEY",
          "Content-Type": "application/json"
      }
      payload = {
          "amount": 5000,
          "currency": "XAF",
          "customer": {
              "name": "John Doe",
              "email": "john@example.com",
              "phone": "+237600000000"
          },
          "description": "Payment for Order #123",
          "callback": "https://your-website.com/callback",
          "reference": "order_123"
      }

      response = requests.post(url, headers=headers, json=payload)
      data = response.json()

      # Redirect the customer to the payment page
      return redirect(data["authorization_url"])
      ```
    </CodeGroup>

    <Accordion title="Payment Request Parameters">
      <ParamField body="amount" type="number" required>
        The amount to charge in the smallest currency unit (e.g., cents for USD, kobo for NGN)
      </ParamField>

      <ParamField body="currency" type="string" required>
        The three-letter ISO currency code (e.g., XAF, USD, EUR)
      </ParamField>

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

        <Expandable title="Customer Object">
          <ParamField body="name" type="string">
            Customer's full name
          </ParamField>

          <ParamField body="email" type="string" required>
            Customer's email address
          </ParamField>

          <ParamField body="phone" type="string">
            Customer's phone number (with country code)
          </ParamField>
        </Expandable>
      </ParamField>

      <ParamField body="description" type="string">
        Description of what the payment is for
      </ParamField>

      <ParamField body="callback" type="string" required>
        URL to redirect the customer after payment
      </ParamField>

      <ParamField body="reference" type="string">
        Your unique reference for this payment
      </ParamField>
    </Accordion>
  </Step>

  <Step title="Redirect to the Payment Page">
    After creating a payment, you'll receive a response with an `authorization_url`. Redirect your customer to this URL to complete the payment:

    <CodeGroup>
      ```javascript JavaScript theme={null}
      window.location.href = data.authorization_url;
      // Example: https://pay.notchpay.co/pay_123456789
      ```

      ```php PHP theme={null}
      header("Location: " . $data["authorization_url"]);
      exit();
      ```

      ```python Python theme={null}
      from flask import redirect
      return redirect(data["authorization_url"])
      ```
    </CodeGroup>

    <img src="https://mintcdn.com/notchpay/2ru8DkTwz6UpmfRk/images/screenshots/payment-page.png?fit=max&auto=format&n=2ru8DkTwz6UpmfRk&q=85&s=bdb70a7fa9f8190c5b537a80cf9ff3e3" alt="Notch Pay Collect Payment Page" width="464" height="668" data-path="images/screenshots/payment-page.png" />
  </Step>

  <Step title="Handle the Callback">
    When the payment is completed (or fails), Notch Pay will redirect the customer back to your `callback` URL with the payment status:

    <CodeGroup>
      ```javascript Node.js (Express) theme={null}
      // Example callback handler in Express.js
      app.get('/callback', (req, res) => {
        const reference = req.query.reference;

        // Verify the payment status
        fetch(`https://api.notchpay.co/payments/${reference}`, {
          headers: {
            'Authorization': 'YOUR_PUBLIC_KEY'
          }
        })
        .then(response => response.json())
        .then(data => {
          if (data.transaction.status === 'complete') {
            // Payment successful, update your database and show success page
            res.send('Payment successful!');
          } else {
            // Payment failed or is still pending
            res.send('Payment not completed.');
          }
        })
        .catch(error => {
          console.error('Error:', error);
          res.status(500).send('Error verifying payment');
        });
      });
      ```

      ```php PHP theme={null}
      <?php
      // Example callback handler in PHP
      $reference = $_GET['reference'];

      $curl = curl_init();
      curl_setopt_array($curl, [
        CURLOPT_URL => "https://api.notchpay.co/payments/{$reference}",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
          "Authorization: YOUR_PUBLIC_KEY"
        ]
      ]);

      $response = curl_exec($curl);
      $data = json_decode($response, true);
      curl_close($curl);

      if ($data['transaction']['status'] === 'complete') {
        // Payment successful, update your database and show success page
        echo 'Payment successful!';
      } else {
        // Payment failed or is still pending
        echo 'Payment not completed.';
      }
      ```

      ```python Python (Flask) theme={null}
      @app.route('/callback')
      def callback():
          reference = request.args.get('reference')

          headers = {
              "Authorization": "YOUR_PUBLIC_KEY"
          }

          response = requests.get(f"https://api.notchpay.co/payments/{reference}", headers=headers)
          data = response.json()

          if data['transaction']['status'] == 'complete':
              # Payment successful, update your database and show success page
              return 'Payment successful!'
          else:
              # Payment failed or is still pending
              return 'Payment not completed.'
      ```
    </CodeGroup>

    <Callout type="info">
      Always verify the payment status on your server before fulfilling orders or providing services to customers.
    </Callout>
  </Step>

  <Step title="Set Up Webhooks (Recommended)">
    <Callout type="warning">
      Callbacks can fail if users close their browsers before being redirected. Webhooks provide a more reliable way to receive payment notifications.
    </Callout>

    For more reliable payment notifications, set up webhooks to receive real-time updates about payment status changes:

    <Steps>
      <Step title="Create Webhook Endpoint">
        Create an endpoint on your server to receive webhook events:

        <CodeGroup>
          ```javascript Node.js (Express) theme={null}
          // Example webhook handler in Express.js
          app.post('/webhooks', express.json(), (req, res) => {
            const event = req.body;

            // Verify webhook signature (recommended for security)
            // ...

            // Handle different event types
            switch (event.type) {
              case 'payment.complete':
                // Update order status to paid
                break;
              case 'payment.failed':
                // Handle failed payment
                break;
              // Handle other event types
            }

            // Acknowledge receipt of the webhook
            res.status(200).send('Webhook received');
          });
          ```

          ```php PHP theme={null}
          <?php
          // Example webhook handler in PHP
          $payload = file_get_contents('php://input');
          $event = json_decode($payload, true);

          // Verify webhook signature (recommended for security)
          // ...

          // Handle different event types
          switch ($event['type']) {
            case 'payment.complete':
              // Update order status to paid
              break;
            case 'payment.failed':
              // Handle failed payment
              break;
            // Handle other event types
          }

          // Acknowledge receipt of the webhook
          http_response_code(200);
          echo 'Webhook received';
          ```
        </CodeGroup>
      </Step>

      <Step title="Register Webhook URL">
        1. Go to your Dashboard > Settings > Webhooks
        2. Add a new webhook with your endpoint URL (e.g., `https://your-website.com/webhooks`)
        3. Select the events you want to receive (e.g., `payment.complete`, `payment.failed`)
      </Step>

      <Step title="Secure Your Webhooks">
        <Callout type="error">
          Always verify webhook signatures to ensure they're coming from Notch Pay and not from an attacker.
        </Callout>

        Check our [Webhook Security Guide](/get-started/webhooks/verify) for implementation details.
      </Step>
    </Steps>
  </Step>
</Steps>

## Next Steps

<Callout type="success">
  Congratulations! You've successfully integrated Notch Pay for basic payment processing.
</Callout>

Here are some next steps to enhance your integration:

<CardGroup cols={2}>
  <Card title="Explore Payment Methods" icon="credit-card" href="/accept-payments">
    Offer more payment options to your customers
  </Card>

  <Card title="Customer Management" icon="users" href="/customers">
    Save customer information for future payments
  </Card>

  <Card title="Webhook Setup" icon="bell" href="/get-started/webhooks">
    Set up reliable payment notifications
  </Card>

  <Card title="Testing" icon="vial" href="/get-started/testing">
    Test your integration thoroughly before going live
  </Card>
</CardGroup>

## Sample Applications

Check out these sample applications to see Notch Pay in action:

<CardGroup cols={3}>
  <Card title="JavaScript/Node.js" icon="js" href="https://github.com/notchafrica/notchpay-node-example">
    Example Node.js integration
  </Card>

  <Card title="PHP" icon="php" href="https://github.com/notchafrica/notchpay-php-example">
    Example PHP integration
  </Card>

  <Card title="Python" icon="python" href="https://github.com/notchafrica/notchpay-python-example">
    Example Python integration
  </Card>
</CardGroup>

## Need Help?

<Accordion title="Support Resources">
  <CardGroup cols={1}>
    <Card title="API Reference" icon="book" href="/api-reference">
      Detailed endpoint documentation
    </Card>

    <Card title="Support Team" icon="headset" href="mailto:hello@notchpay.co">
      Contact our support team for assistance
    </Card>

    <Card title="Developer Community" icon="users" href="https://community.notchpay.co">
      Connect with other developers
    </Card>
  </CardGroup>
</Accordion>