Integration Setup Guide

Complete guide to setting up your One2Pays integration and generating API credentials.

Overview

Before you can use the One2Pays API, you need to:

1. Create an integration in your merchant dashboard
2. Generate API credentials (API key and secret key)
3. Configure your integration settings
4. Test your integration

Step 1: Create an Integration

1. Log in to your Merchant Dashboard

2. Navigate to Integrations section

3. Click Create Integration or New Integration

4. Fill in the integration details:

   • Name: A descriptive name for your integration (e.g., "Production API", "Test Integration")
   • Environment: Choose test or production
   • Description (optional): Additional details about this integration

5. Click Create to create the integration

Step 2: Generate API Credentials

After creating an integration:

1. Navigate to your integration details page
2. Click Generate API Credentials or Create API Keys
3. You'll receive:
   • API Key: Starts with pk_test_... (test) or pk_live_... (production)
   • Secret Key: Starts with sk_test_... (test) or sk_live_... (production)

Step 3: Store Credentials Securely

Environment Variables (Recommended)

Store your credentials in environment variables:

.env file:

PAYMENT_API_KEY=pk_test_...
PAYMENT_API_SECRET=sk_test_...

Load in your application:

// Node.js
const API_KEY = process.env.PAYMENT_API_KEY!;
const API_SECRET = process.env.PAYMENT_API_SECRET!;

# Python
import os
API_KEY = os.environ['PAYMENT_API_KEY']
API_SECRET = os.environ['PAYMENT_API_SECRET']

Security Best Practices

• ✅ Use environment variables or secret management services
• ✅ Never commit credentials to version control
• ✅ Use different credentials for test and production
• ✅ Rotate credentials regularly
• ✅ Restrict access to credentials (principle of least privilege)
• ❌ Never hardcode credentials in your source code
• ❌ Never share credentials in public forums or documentation
• ❌ Never use production credentials in test environments

Step 4: Configure Integration Settings

Custom Redirect URL (Optional)

If you want to use a custom redirect URL instead of One2Pays's payment app:

1. Go to your integration settings
2. Add redirectUrl to integration metadata:

   {
     "redirectUrl": "https://your-app.com/payment/{paymentId}"
   }

The {paymentId} placeholder will be replaced with the actual payment ID.

Webhook Configuration

Webhooks are configured separately. See the Webhooks Guide for details.

Step 5: Test Your Integration

Test Authentication

Create a simple test to verify your credentials work:

import crypto from 'crypto';

const API_KEY = process.env.PAYMENT_API_KEY!;
const API_SECRET = process.env.PAYMENT_API_SECRET!;

async function testAuth() {
  const method = 'GET';
  const path = '/api/v1/payments?limit=1';
  const body = '';
  const timestamp = Date.now().toString();

  const message = `${timestamp}.${body}`;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(message)
    .digest('hex');

  const response = await fetch(`https://api.example.com${path}`, {
    method,
    headers: {
      'X-API-Key': API_KEY,
      'X-Timestamp': timestamp,
      'X-Signature': `sha256=${signature}`,
    },
  });

  const result = await response.json();

  if (result.success) {
    console.log('✅ Authentication successful!');
    console.log('Total payments:', result.data.total);
  } else {
    console.error('❌ Authentication failed:', result.error);
  }
}

testAuth();

Test Payment Creation

Create a test payment to verify everything works:

// Use test credentials and test bank account details
const testPayment = await createPayment({
  amount: '1000.00',
  currency: 'THB',
  referenceId: 'test-' + Date.now(),
  paymentMethod: 'promptpay',
  customerBankAccountName: 'Test Customer',
  customerBankAccountNumber: '1234567890',
  customerBankCode: '004',
  description: 'Test payment',
});

Environment Setup

Test Environment

• Base URL: <SandboxApiUrl />
• API Keys: Start with pk_test_... and sk_test_...
• Use for: Development, testing, integration verification
• No real money: Transactions are simulated

Production Environment

• Base URL: <ApiUrl />
• API Keys: Start with pk_live_... and sk_live_...
• Use for: Live transactions with real money
• Real money: All transactions are real

Troubleshooting

Invalid Credentials Error

Problem: Getting INVALID_CREDENTIALS error.

Solutions:

• Verify API key and secret key are correct
• Check that you're using the correct environment (test vs production)
• Ensure keys match the environment (test keys for test, production keys for production)
• Verify secret key wasn't regenerated (old keys become invalid)

Signature Verification Failed

Problem: Getting signature verification errors.

Solutions:

• Verify signature format: HMAC-SHA256(timestamp + "." + rawBody, secretKey)
• Check timestamp is in milliseconds (not seconds)
• Ensure raw body matches exactly (no extra whitespace)
• Verify secret key is correct (not API key)

Integration Not Active

Problem: Getting FORBIDDEN error with "Integration is not active".

Solutions:

• Check integration status in dashboard
• Ensure integration is set to "active" status
• Contact support if integration was deactivated

Next Steps

• Quickstart Guide - Create your first payment
• Authentication Reference - Detailed authentication guide
• API Reference - Complete API documentation