One-Time Payments

​

What You Can Do

• Generate Secure Payment Links: Create unique, time-limited checkout URLs for each transaction
• Accept Card Payments: Process credit and debit card payments through Compago’s PCI-compliant infrastructure
• Customize the Experience: Control where customers are redirected after payment completion
• Track Payments: Use your own external IDs to link Compago payments with your internal systems
• Offer Installment Plans: Support monthly installment payments (Meses Sin Intereses) when available
• Set Custom Expiration Times: Configure payment link expiration from 10 minutes to 48 hours based on your needs

​

Use Cases

• Invoicing: Send payment links to customers via email or messaging
• Custom Integrations: Trigger payments from CRM, ERP, or internal tools
• eCommerce: Accept payments for online stores and marketplaces
• Service Businesses: Request deposits or full payments for appointments or bookings
• Point of Sale: Create payment links for in-person transactions (when integrated with terminal apps)

​

How It Works

1. Create: Your backend calls the Compago API to create a payment link, providing the amount, customer details, and redirect URLs
2. Receive: Compago returns a secure checkout URL where your customer will complete the payment
3. Redirect: Send your customer to the checkout URL where they enter their payment details
4. Process: Compago processes the payment securely through its payment infrastructure
5. Callback: After successful payment, Compago redirects the customer back to your redirectUrl with query parameters id and externalId appended
6. Verify: On your callback page, extract the payment id from the URL and fetch the final payment status using the GET endpoint
7. Fulfill: Update your internal systems (mark order as paid, send confirmation email, etc.)

​

Prerequisites

• An active Compago account with API access
• A valid API key (generate one at Configuraciones → Desarrollador in your Compago Dashboard)
• Your integration configured to use MXN currency

​

Creating a One-Time Payment

​

Endpoint

POST /api/one-time-payment

​

Authentication

x-api-key: YOUR_API_KEY
Content-Type: application/json

​

Request Body

{
  "amount": 1200,
  "currency": "MXN",
  "description": "Order #12345 - Blue Widget",
  "externalId": "order_12345_payment_1",
  "redirectUrl": "https://yourstore.com/order/12345/confirmation",
  "homepageUrl": "https://yourstore.com",
  "ttlMinutes": 1440,
  "billingInformation": {
    "email": "[email protected]",
    "firstName": "María",
    "lastName": "González",
    "phoneNumber": "+5215512345678",
    "address": {
      "addressLine": "Av. Insurgentes Sur 1234",
      "city": "Ciudad de México",
      "state": "CDMX",
      "zip": "03100"
    }
  }
}

​

Field Descriptions

​

Billing Information

​

Address

​

Response

{
  "redirectUrl": "https://app.compago.com/checkout/otp/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}

​

Example with cURL

curl -X POST https://api.harmony.compago.com/api/one-time-payment \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1200,
    "currency": "MXN",
    "description": "Order #12345",
    "externalId": "order_12345_payment_1",
    "redirectUrl": "https://yourstore.com/order/12345/confirmation",
    "homepageUrl": "https://yourstore.com",
    "ttlMinutes": 1440,
    "billingInformation": {
      "email": "[email protected]",
      "firstName": "María",
      "lastName": "González",
      "phoneNumber": "+5215512345678",
      "address": {
        "addressLine": "Av. Insurgentes Sur 1234",
        "city": "Ciudad de México",
        "state": "CDMX",
        "zip": "03100"
      }
    }
  }'

​

Handling the Payment Callback

• id: The Compago one-time payment ID
• externalId: The external ID you provided when creating the payment

​

How the Redirect Works

{
  "redirectUrl": "https://yourstore.com/order/confirmation",
  "externalId": "order_12345_payment_1"
  // ... other fields
}

https://yourstore.com/order/confirmation?id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&externalId=order_12345_payment_1

​

Implementation Example

// Your callback route handler
app.get('/order/confirmation', async (req, res) => {
  // 1. Extract query parameters
  const { id, externalId } = req.query;

  if (!id || !externalId) {
    return res.status(400).send('Missing payment parameters');
  }

  // 2. Fetch the payment status from Compago
  const response = await fetch(
    `https://api.harmony.compago.com/api/one-time-payment/${id}`,
    {
      headers: {
        'x-api-key': process.env.COMPAGO_API_KEY
      }
    }
  );

  const payment = await response.json();

  // 3. Update your internal systems
  await updateOrderStatus(externalId, 'paid');
  await sendConfirmationEmail(externalId);

  // 4. Show success page to customer
  res.render('order-success', {
    orderId: externalId,
    amount: payment.amount
  });
});

​

Best Practices for Callback Handling

// ❌ WRONG - Don't verify
app.get('/order/confirmation', async (req, res) => {
  await markOrderAsPaid(req.query.externalId);
  res.send('Thank you for your payment!');
});

// ✅ CORRECT - Always verify for security
app.get('/order/confirmation', async (req, res) => {
  const payment = await fetchPaymentStatus(req.query.id);
  await markOrderAsPaid(req.query.externalId);
  res.render('order-success', {
    orderId: req.query.externalId,
    amount: payment.amount
  });
});

const { id, externalId } = req.query;

if (!id || !externalId) {
  return res.redirect('/orders'); // or show error page
}

// Check if order is already marked as paid
const order = await getOrder(externalId);
if (order.status === 'paid') {
  return res.render('already-processed');
}

// Only mark as paid if status changed
const payment = await fetchPaymentStatus(id);
if (payment.status === 'CONFIRMED' && order.status !== 'paid') {
  await markOrderAsPaid(externalId);
  await sendConfirmationEmail(externalId);
}

// ✅ CORRECT
redirectUrl: "https://yourstore.com/order/confirmation"

// ❌ WRONG - Insecure
redirectUrl: "http://yourstore.com/order/confirmation"

// If you create payment with:
redirectUrl: "https://yourstore.com/order/confirmation?lang=es"

// Customer will be redirected to:
// https://yourstore.com/order/confirmation?lang=es&id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&externalId=order_123

// Access all parameters normally:
const { lang, id, externalId } = req.query;

​

Security Considerations

1. Validate query parameters exist before processing
2. Fetch payment status from Compago API - Don’t trust the redirect alone
3. Verify the externalId matches your records - Ensure it corresponds to a real order in your system
4. Check payment status is CONFIRMED before fulfilling the order
5. Log all callback attempts for debugging and security monitoring
6. Use rate limiting on your callback endpoint to prevent abuse

​

Testing Your Callback Handler

1. Create a one-time payment using your test API key
2. Complete the payment in the Compago checkout page
3. Verify your callback page receives the id and externalId parameters
4. Confirm your system correctly fetches and processes the payment status
5. Test the failure case by creating a payment and letting it expire

https://yourstore.com/order/confirmation?id=test-payment-id&externalId=test-order-123

​

Important Business Rules

​

Payment Expiration

​

Custom Expiration Times

• Minimum: 10 minutes
• Maximum: 2,880 minutes (48 hours)
• Default: 2,880 minutes (48 hours) if not specified

{
  "ttlMinutes": 30,  // 30-minute window
  "description": "Flash Sale - Limited Stock!"
  // ... other fields
}

{
  // No ttlMinutes specified - defaults to 48 hours
  "description": "Invoice #12345"
  // ... other fields
}

{
  "ttlMinutes": 720,  // 12 hours
  "description": "Concert Ticket - Register by 8 PM tonight"
  // ... other fields
}

{
  "ttlMinutes": 2880,  // Full 48 hours
  "description": "Quote #QT-5678 - Valid until [date]"
  // ... other fields
}

• Balance security and convenience when setting expiration times
• Shorter TTLs (10-60 min) work well for in-person transactions or time-sensitive offers
• Longer TTLs (12-48 hours) are better for invoices and asynchronous payment flows
• Consider your customer’s payment behavior and typical checkout time
• Communicate the expiration time to customers (e.g., “Complete payment within 30 minutes”)

​

Minimum Amount

​

External ID Uniqueness

{
  "message": "One time payment with externalId order_12345_payment_1 already exists."
}

​

Currency Restriction

​

Payment Status

• PENDING: Payment link is active and waiting for customer to complete payment
• CONFIRMED: Customer has successfully completed the payment
• CANCELLED: Payment link has been cancelled and can no longer be used

​

Retrieving Payment Details

​

Endpoint

GET /api/one-time-payment/{id}

​

Response for Active Payments

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "PENDING",
  "amount": 1200,
  "currency": "MXN",
  "description": "Order #12345",
  "externalId": "order_12345_payment_1",
  "expiresAt": "2025-10-30T12:45:00Z",
  "expired": false,
  "homepageUrl": "https://yourstore.com",
  "redirectUrl": "https://yourstore.com/order/12345/confirmation",
  "organization": {
    "name": "Your Business Name",
    "business": {
      "websiteURL": "https://yourstore.com"
    }
  },
  "billingInformation": {
    "phoneNumber": "+5215512345678"
  }
}

​

Response for Completed or Expired Payments

{
  "status": "CONFIRMED",
  "homepageUrl": "https://yourstore.com",
  "expired": false,
  "organization": {
    "name": "Your Business Name",
    "business": {
      "websiteURL": "https://yourstore.com"
    }
  },
  "billingInformation": {
    "phoneNumber": "+5215512345678"
  }
}

​

Supported Mexican States

​

Error Handling

​

Common Errors

​

Example Error Response

{
  "message": "One time payment amount must be at least $[minimum_amount]."
}

​

Best Practices

1. Generate Unique External IDs: Use a combination of order ID and timestamp to ensure uniqueness
2. Handle Expiration: Implement logic to create new payment links if the 48-hour window expires
3. Validate Amounts: Ensure amounts meet your account’s minimum payment threshold before calling the API
4. Store Payment IDs: Save the returned one-time payment ID to track and verify payments later
5. Implement Webhooks: Use webhooks (if available) to receive real-time payment status updates
6. Test Thoroughly: Use the demo environment to test your integration before going live
7. Implement Robust Callback Handling: Always verify payment status in your redirectUrl callback by fetching the payment using the id query parameter. Never assume payment success based on the redirect alone. See Handling the Payment Callback.

​

Support

• Verify your API key is valid in Configuraciones → Desarrollador at app.compago.com
• Ensure all required fields are included in your request
• Check that amounts meet the minimum threshold
• Verify your organization settings are configured correctly
• Contact Compago support at [email protected] for assistance