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

# Quickstart

> Learn how to create and process payments with Open Market API

## Payment Integration Guide

This guide will walk you through the process of integrating payments into your application using Open Market API.

### Supported Countries

Open Market supports payments in the following countries:

<CardGroup cols="3">
  <Card title="West Africa">
    * Benin
    * Burkina Faso
    * Ivory Coast
    * Mali
    * Senegal
    * Togo
  </Card>

  <Card title="Central Africa">
    * Cameroon
    * Congo
    * DR Congo
    * Gabon
  </Card>

  <Card title="Other Regions">
    * Uganda
    * Zambia
    * International
  </Card>
</CardGroup>

### Creating a Payment

To create a payment, you'll need to make a POST request to our payment endpoint with the required information.

#### Required Parameters

| Parameter      | Type   | Description                                                                                             |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| product\_name  | string | Name of the product or service being sold                                                               |
| price          | number | Price in the local currency                                                                             |
| description    | string | Description of the product or transaction                                                               |
| buyer\_name    | string | Customer's full name                                                                                    |
| buyer\_country | string | Customer's country ([see supported countries](#supported-countries))                                    |
| reference      | string | Your unique transaction reference (6-24 alphanumeric characters, must contain both letters and numbers) |

#### Optional Parameters

| Parameter    | Type   | Description                                                             |
| ------------ | ------ | ----------------------------------------------------------------------- |
| meta\_data   | object | Additional data you want to store with the payment                      |
| success\_url | string | URL to redirect after successful payment (must be valid HTTPS/HTTP URL) |
| failed\_url  | string | URL to redirect after failed payment (must be valid HTTPS/HTTP URL)     |

#### Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://gateway.op-markets.com/payment/create-payment-url/" \
  -H "api-key: your_public_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Premium Course",
    "price": 5000,
    "description": "Access to premium programming course",
    "buyer_name": "John Doe",
    "buyer_country": "BENIN",
    "reference": "ORDER123456",
    "success_url": "https://your-domain.com/success",
    "failed_url": "https://your-domain.com/failed",
    "meta_data": {
      "customer_id": "CUS_123",
      "order_id": "ORD_456"
    }
  }'
  ```

  ```javascript JavaScript theme={null}
  const payment = {
    product_name: "Premium Course",
    price: 5000,
    description: "Access to premium programming course",
    buyer_name: "John Doe",
    buyer_country: "BENIN",
    reference: "ORDER123456",
    success_url: "https://your-domain.com/success",
    failed_url: "https://your-domain.com/failed",
    meta_data: {
      customer_id: "CUS_123",
      order_id: "ORD_456"
    }
  };

  const response = await fetch('https://gateway.op-markets.com/payment/create-payment-url/', {
    method: 'POST',
    headers: {
      'api-key': 'your_public_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payment)
  });

  const data = await response.json();
  // Redirect user to payment page
  window.location.href = data.payment_url;
  ```

  ```python Python theme={null}
  import requests

  payment = {
      "product_name": "Premium Course",
      "price": 5000,
      "description": "Access to premium programming course",
      "buyer_name": "John Doe",
      "buyer_country": "BENIN",
      "reference": "ORDER123456",
      "success_url": "https://your-domain.com/success",
      "failed_url": "https://your-domain.com/failed",
      "meta_data": {
          "customer_id": "CUS_123",
          "order_id": "ORD_456"
      }
  }

  headers = {
      "api-key": "your_public_key_here",
      "Content-Type": "application/json"
  }

  response = requests.post(
      "https://gateway.op-markets.com/payment/create-payment-url/",
      json=payment,
      headers=headers
  )

  payment_url = response.json()["payment_url"]
  # Redirect user to payment page
  ```

  ```php PHP theme={null}
  <?php
  <?php
  $payment = array(
      "product_name" => "Premium Course",
      "price" => 5000,
      "description" => "Access to premium programming course",
      "buyer_name" => "John Doe",
      "buyer_country" => "BENIN",
      "reference" => "ORDER123456",
      "success_url" => "https://your-domain.com/success",
      "failed_url" => "https://your-domain.com/failed",
      "meta_data" => array(
          "customer_id" => "CUS_123",
          "order_id" => "ORD_456"
      )
  );

  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, "https://gateway.op-markets.com/payment/create-payment-url/");
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payment));
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
      "api-key: your_public_key_here",
      "Content-Type: application/json"
  ));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

  $response = curl_exec($ch);
  curl_close($ch);

  $payment_url = json_decode($response, true)["payment_url"];
  // Redirect user to payment page
  header("Location: " . $payment_url);
  ?>
  ```
</CodeGroup>

### Payment Flow

1. **Create Payment Request**
   * Send payment details to our API
   * Receive a payment URL in response
2. **Redirect Customer**
   * Redirect your customer to the received payment URL
   * The customer will see our secure payment page
3. **Payment Processing**
   * Customer selects their preferred payment method
   * Completes the payment on our secure platform
4. **Payment Confirmation**
   * After successful payment, customer is redirected to your success URL
   * Our system sends a webhook notification to your callback URL
   * Failed payments are redirected to your failure URL

<Note>
  Make sure you've configured your callback URLs in the [API Settings](https://entreprise.op-markets.com/api) before processing payments.
</Note>

### Country Codes

When specifying the `buyer_country`, use one of these exact values:

```plaintext theme={null}
BENIN
BURKINA FASO
CAMEROON
CONGO
COTE D'IVOIRE
GABON
INTERNATIONAL
MALI
RD CONGO
SENEGAL
TOGO
UGANDA
ZAMBIA
```

### Best Practices

<AccordionGroup>
  <Accordion title="API Key Security" icon="shield-check">
    * Store API keys in environment variables
    * Never expose API keys in frontend code
    * Use different keys for development and production
    * Rotate keys periodically
    * Implement IP whitelisting when possible

    ```javascript Environment Variables theme={null}
    // .env file
    OPM_PUBLIC_KEY=pk_live_xxxxx
    OPM_PRIVATE_KEY=sk_live_xxxxx
    ```
  </Accordion>

  <Accordion title="Meta Data Usage" icon="database">
    Store additional information in the meta\_data object to enhance your payment tracking:

    ```javascript theme={null}
    // E-commerce Order
    meta_data: {
      order_id: "ORD_123",
      customer_id: "CUS_456", 
      shipping_address: "123 Main St",
      products: ["SKU_001", "SKU_002"],
      coupon_code: "SUMMER20"
    }

    // Course Enrollment
    meta_data: {
      course_id: "COURSE_789",
      student_id: "STU_101",
      enrollment_date: "2024-01-15",
      course_type: "premium",
      referral_code: "REF123"
    }

    // Subscription Payment
    meta_data: {
      subscription_id: "SUB_456",
      plan_type: "annual",
      renewal_date: "2025-01-15",
      features: ["feature1", "feature2"],
      previous_plan: "monthly"
    }
    ```

    Benefits of using meta\_data:

    * Enhanced transaction tracking
    * Easier payment reconciliation
    * Better customer support handling
    * Detailed reporting capabilities
    * Simplified order management
    * Custom analytics integration
  </Accordion>

  <Accordion title="Backend Implementation" icon="server">
    Always implement payment requests through your backend:

    ```javascript theme={null}
    // ❌ Avoid exposing API key in frontend
    const apiKey = "pk_live_xxxxx"; // Never do this

    // ✅ Make API calls through your backend
    async function createPayment(data) {
      const response = await fetch('/api/payments/create', {
        method: 'POST',
        body: JSON.stringify(data)
      });
      return response.json();
    }
    ```
  </Accordion>

  <Accordion title="Input Validation" icon="check-circle">
    * Always verify the price is positive
    * Ensure the country is supported
    * Validate buyer information
    * Sanitize all user inputs
    * Implement request rate limiting

    ```javascript theme={null}
    function validatePayment(data) {
      if (data.price <= 0) throw new Error('Invalid price');
      if (!SUPPORTED_COUNTRIES.includes(data.buyer_country)) {
        throw new Error('Country not supported');
      }
      if (!data.buyer_name?.trim()) {
        throw new Error('Buyer name required');
      }
    }
    ```
  </Accordion>

  <Accordion title="Error Handling" icon="exclamation-triangle">
    Implement proper error handling and user feedback:

    ```javascript theme={null}
    try {
      const response = await createPayment(paymentDetails);
      if (response.payment_url) {
        window.location.href = response.payment_url;
      }
    } catch (error) {
      console.error('Payment creation failed:', error);
      showUserFriendlyError(error);
    }
    ```
  </Accordion>

  <Accordion title="Webhook Security" icon="lock">
    * Validate webhook signatures using your private key
    * Process webhooks asynchronously
    * Implement retry mechanism for failed webhooks
    * Store webhook events for audit purposes

    ```javascript theme={null}
    async function handleWebhook(request) {
      const signature = request.headers['opm-signature'];
      if (!verifySignature(request.body, signature)) {
        throw new Error('Invalid signature');
      }
      // Process webhook asynchronously
      await processWebhookEvent(request.body);
    }
    ```
  </Accordion>

  <Accordion title="Testing Strategy" icon="flask">
    * Use test API keys in development
    * Test various payment scenarios
    * Verify webhook handling
    * Test error scenarios
    * Implement end-to-end testing
    * Simulate network issues
  </Accordion>

  <Accordion title="Monitoring & Logging" icon="chart-line">
    * Log all payment attempts
    * Monitor API response times
    * Track success/failure rates
    * Set up alerts for unusual activity
    * Implement transaction tracking

    ```javascript theme={null}
    async function logPaymentAttempt(paymentData, result) {
      await logger.info('Payment attempt', {
        timestamp: new Date(),
        paymentId: paymentData.id,
        status: result.status,
        amount: paymentData.price,
        country: paymentData.buyer_country
      });
    }
    ```
  </Accordion>
</AccordionGroup>

<Card title="Testing Tips" icon="flask">
  During development, use test cards and mobile money numbers available in our [testing guide](/development).
</Card>

### Common Issues

<AccordionGroup>
  <Accordion title="Payment URL Not Generated">
    * Verify your API key is correct
    * Check if all required fields are provided
    * Ensure the country code is valid
  </Accordion>

  <Accordion title="Redirect Not Working">
    * Verify the payment URL is valid
    * Check if you're using proper redirect method
    * Ensure no client-side JavaScript is blocking the redirect
  </Accordion>
</AccordionGroup>

### Need Help?

If you encounter any issues or need assistance, our support team is available through:

* [Telegram Support](https://t.me/+EXvTAEWr_u1jMzZ)
* [WhatsApp Community](https://chat.whatsapp.com/Hwvz0kLG2HsHRinEKTA7yX)