Quickstart - 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:

West Africa

Benin
Burkina Faso
Ivory Coast
Mali
Senegal
Togo

Central Africa

Cameroon
Congo
DR Congo
Gabon

Other Regions

Uganda
Zambia
International

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)
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

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"
  }
}'

Payment Flow

Create Payment Request
- Send payment details to our API
- Receive a payment URL in response
Redirect Customer
- Redirect your customer to the received payment URL
- The customer will see our secure payment page
Payment Processing
- Customer selects their preferred payment method
- Completes the payment on our secure platform
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

Make sure you’ve configured your callback URLs in the API Settings before processing payments.

Country Codes

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

BENIN
BURKINA FASO
CAMEROON
CONGO
COTE D'IVOIRE
GABON
INTERNATIONAL
MALI
RD CONGO
SENEGAL
TOGO
UGANDA
ZAMBIA

Best Practices

API Key Security

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

Environment Variables
// .env file
OPM_PUBLIC_KEY=pk_live_xxxxx
OPM_PRIVATE_KEY=sk_live_xxxxx

Meta Data Usage

Store additional information in the meta_data object to enhance your payment tracking:

// 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

Backend Implementation

Always implement payment requests through your backend:

// ❌ 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();
}

Input Validation

Always verify the price is positive
Ensure the country is supported
Validate buyer information
Sanitize all user inputs
Implement request rate limiting

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');
  }
}

Error Handling

Implement proper error handling and user feedback:

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);
}

Webhook Security

Validate webhook signatures using your private key
Process webhooks asynchronously
Implement retry mechanism for failed webhooks
Store webhook events for audit purposes

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);
}

Testing Strategy

Monitoring & Logging

Log all payment attempts
Monitor API response times
Track success/failure rates
Set up alerts for unusual activity
Implement transaction tracking

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
  });
}

Testing Tips

During development, use test cards and mobile money numbers available in our testing guide.

Common Issues

Payment URL Not Generated

Redirect Not Working

Need Help?

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

Get Started

​Payment Integration Guide

​Supported Countries

West Africa

Central Africa

Other Regions

​Creating a Payment

​Required Parameters

​Optional Parameters

​Example Request

​Payment Flow

​Country Codes

​Best Practices

Testing Tips

​Common Issues

​Need Help?

Payment Integration Guide

Supported Countries

Creating a Payment

Required Parameters

Optional Parameters

Example Request

Payment Flow

Country Codes

Best Practices

Common Issues

Need Help?