Quickstart Guide

Get up and running with One2Pays in 5 minutes. This guide will walk you through creating your first payment.

Prerequisites

A One2Pays merchant account
Integration API credentials (API key and secret) from your merchant dashboard
Basic knowledge of HTTP requests and JSON

Step 1: Get Your API Credentials

Log in to your Merchant Dashboard
Navigate to Integrations section
Create a new integration or select an existing one
Generate API credentials (API key and secret key)
Copy your API Key and Secret Key

Keep your secret key secure!

Never expose it in client-side code or public repositories. Use environment variables or secure secret management.

Step 2: Create Your First Payment

Let's create a payment for 1000 THB (10.00 THB) using PromptPay:

import crypto from 'crypto';

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

async function createPayment() {
  const method = 'POST';
  const path = '/api/v1/payments';
  const body = JSON.stringify({
    amount: '1000.00',
    currency: 'THB',
    referenceId: `order-${Date.now()}`,
    paymentMethod: 'promptpay',
    customerBankAccountName: 'John Doe',
    customerBankAccountNumber: '1234567890',
    customerBankCode: '004',
    description: 'My first payment',
  });
  const timestamp = Date.now().toString(); // milliseconds

  // Create HMAC signature: HMAC-SHA256(timestamp + "." + rawBody, secretKey)
  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}`,
      'Content-Type': 'application/json',
    },
    body,
  });

  const result = await response.json();

  if (result.success) {
    console.log('Payment created:', result.data.id);
    console.log('Status:', result.data.status);
    console.log('Next action:', result.data.nextAction);

    // Handle nextAction
    if (result.data.nextAction?.type === 'use_payment_app') {
      // Redirect customer to payment app
      window.location.href = result.data.nextAction.paymentAppUrl;
    } else if (result.data.nextAction?.type === 'redirect') {
      // Redirect to custom URL
      window.location.href = result.data.nextAction.redirectUrl;
    }
  } else {
    console.error('Error:', result.error);
  }
}

createPayment();

Step 3: Handle the Response

After creating a payment, you'll receive a response with a nextAction field that tells you what to do next:

`use_payment_app`

Redirect the customer to One2Pays's payment app:

{
  "type": "use_payment_app",
  "paymentAppUrl": "https://pay.example.com/docs/pay/secure-token-here"
}

Action: Redirect the customer to paymentAppUrl.

`redirect`

Redirect to a custom URL (if your integration has a custom redirect URL configured):

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

Action: Redirect the customer to redirectUrl.

`display_bank_transfer_instructions`

Display bank transfer instructions:

{
  "type": "display_bank_transfer_instructions",
  "bankTransferInstructions": {
    "bankName": "Kasikorn Bank",
    "accountNumber": "1234567890",
    "accountName": "Example Company Ltd.",
    "amount": "1000.00",
    "reference": "ORDER-12345"
  }
}

Action: Display the bank transfer instructions to the customer.

Step 4: Check Payment Status

You can check the payment status by retrieving it:

async function getPayment(paymentId: string) {
  const method = 'GET';
  const path = `/api/v1/payments/${paymentId}`;
  const body = '';
  const timestamp = Date.now().toString(); // milliseconds

  // Create HMAC signature: HMAC-SHA256(timestamp + "." + rawBody, secretKey)
  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('Payment status:', result.data.status);
    console.log('Payment amount:', result.data.amount);
    return result.data;
  } else {
    console.error('Error:', result.error);
    throw new Error(result.error.message);
  }
}

// Check payment status
const payment = await getPayment('550e8400-e29b-41d4-a716-446655440000');

Next Steps

Learn about Payment Methods
Set up Webhooks for real-time notifications
Explore the API Reference
Check out Code Examples
Integration Setup Guide - Detailed integration setup

Troubleshooting

Common Issues

Invalid signature: Check that your API secret is correct and the signature format is timestamp + "." + rawBody (not method + path + body + timestamp)
Timestamp expired: Ensure timestamp is in milliseconds and within 5 minutes of current time
Payment not found: Ensure you're using the correct payment UUID (not a prefixed ID like pay_xxx)
Invalid amount: Amount must be a valid decimal string (e.g., "1000.00"), not an integer
Missing required fields: Ensure you include customerBankAccountName, customerBankAccountNumber, and customerBankCode

Need help? Check out our FAQ or contact support.

On this page