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:

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

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

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

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

• Use test API keys in development
• Test various payment scenarios
• Verify webhook handling
• Test error scenarios
• Implement end-to-end testing
• Simulate network issues

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

• Verify your API key is correct
• Check if all required fields are provided
• Ensure the country code is valid

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

Need Help?

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

• Telegram Support
• WhatsApp Community