One-Time Payments

A one-time payment (OTP) is a secure, single-use checkout link that allows your customers to complete a purchase through Compago’s hosted payment page. This is ideal for non-recurring transactions, custom payment requests, or integrations where the payment flow is triggered externally.

What You Can Do

With one-time payments, you can:

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, and choose exactly which plans each payment offers
Set Custom Expiration Times: Configure payment link expiration from 10 minutes to 48 hours based on your needs

Use Cases

One-time payments are perfect for:

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

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

Prerequisites

Before creating one-time payments, ensure you have:

An active Compago account with API access
A valid API key, created at Configuraciones → Desarrollador in the dashboard of the environment you call (demo-app.compago.com for Demo, app.compago.com for Production). See Environments.
Your integration configured to use MXN currency

One-time payments currently support MXN (Mexican Peso) only. Transactions in other currencies will be rejected.

Creating a One-Time Payment

These examples call the production host. While you build, replace https://api-harmony.compago.com with https://demo-api-harmony.compago.com and use a key from the Demo dashboard. See Environments.

Endpoint

POST /api/one-time-payment

API reference: POST /one-time-payment

Authentication

Include your API key in the request headers:

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,
  "displayMode": "LINK",
  "billingInformation": {
    "email": "customer@example.com",
    "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

Field	Type	Required	Description
`amount`	number	Yes	Payment amount in MXN. Must meet the minimum amount configured for your account.
`currency`	string	Yes	Currency code. Must be `"MXN"`.
`description`	string	Yes	Description of the payment shown to the customer during checkout.
`externalId`	string	Yes	Your unique identifier for this payment. Must be unique per organization.
`redirectUrl`	string	Yes	URL where customers are redirected after payment. Compago appends `id` (payment ID) and `externalId` (your identifier) as query parameters. See Handling the Payment Callback.
`homepageUrl`	string	Yes	Your homepage URL, used if the customer cancels or wants to return to your site.
`ttlMinutes`	number	No	Optional time-to-live in minutes for the payment link. Minimum 10 minutes, maximum 2,880 minutes (48 hours). Defaults to 48 hours if not specified. See Custom Expiration Times.
`displayMode`	string	No	`"LINK"` (default) for full-page redirect or `"EMBEDDED"` for iframe. See Display Modes.
`buttonText`	string	No	Custom text for the checkout button (EMBEDDED mode only). 1–40 characters.
`buttonColor`	string	No	Custom hex color for the checkout button, e.g. `"#16A34A"` (EMBEDDED mode only).
`billingInformation`	object	No	Customer billing details (see below). Omit it and the customer fills these in on the checkout page. See Who provides the customer details.
`allowedTerms`	number[]	No	The installment plans the checkout offers: `1` is a single payment, and any larger number is that many months without interest (MSI). `[12]` fixes the payment to 12 MSI; omit it to offer every plan active on your account. See Choosing the installment plans.

Billing Information

The object as a whole is optional. When you do send it, these fields are all required.

Field	Type	Required	Description
`email`	string	Yes	Customer’s email address.
`firstName`	string	Yes	Customer’s first name.
`lastName`	string	Yes	Customer’s last name.
`phoneNumber`	string	Yes	Customer’s phone number (include country code, e.g., +521…).
`address`	object	Yes	Customer’s billing address (see below).

Address

Field	Type	Required	Description
`addressLine`	string	Yes	Street address including number and street name.
`city`	string	Yes	City name.
`state`	string	Yes	Mexican state code (e.g., `"CDMX"`, `"JAL"`, `"NLE"`). See supported states.
`zip`	string	Yes	Postal code.

Response

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

Use the returned redirectUrl to redirect your customer to Compago’s secure checkout page.

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": "customer@example.com",
      "firstName": "María",
      "lastName": "González",
      "phoneNumber": "+5215512345678",
      "address": {
        "addressLine": "Av. Insurgentes Sur 1234",
        "city": "Ciudad de México",
        "state": "CDMX",
        "zip": "03100"
      }
    }
  }'

Who provides the customer details

Compago needs the payer’s name, email and phone to process a card. There are two ways it gets them, and you choose per payment by including billingInformation or leaving it out. You already know the customer. Send billingInformation when you create the payment. The checkout page asks only for the card and lets the customer correct the phone number, so they type as little as possible. This is the right choice for invoicing, for an online store that already has an account, or for anywhere your system holds the customer record. You do not know the customer. Leave billingInformation out. The checkout page then asks the payer for their own name, email and phone alongside the card, exactly as a Compago payment link does. This is the right choice for a counter or a QR code handed to a walk-in, where asking a stranger to read out their email is slower than letting them type it themselves. Either way the details end up on the payment, so a charge created without them is fully attributed once it is paid. Nothing else about the integration changes.

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

Sending billingInformation remains fully supported and is unchanged. If your integration already sends it, you do not need to do anything.

A payment created without billingInformation reads back with billingInformation: null until it is paid. If your callback or reporting code reads the customer’s email off the payment, guard for that case.

Choosing the installment plans

By default the checkout offers every installment plan active on your account, and the customer picks one. Send allowedTerms to decide the financing yourself: the checkout offers only the plans you list, and the customer cannot choose any other. Each entry is a number of monthly installments, the same terms a payment carries once it is paid. 1 is a single payment, and any larger number is that many months without interest (MSI).

`allowedTerms`	What the customer sees
Omitted or `null`	Every plan active on your account, including plans activated later
`[12]`	Only 12 months without interest, already selected. There is no plan selector at all
`[3, 6]`	A choice between 3 and 6 months without interest. A single payment is not offered
`[1, 12]`	A choice between a single payment and 12 months without interest

{
  "amount": 12000,
  "currency": "MXN",
  "description": "Modular sofa",
  "externalId": "order_12345_payment_1",
  "redirectUrl": "https://yourstore.com/order/12345/confirmation",
  "homepageUrl": "https://yourstore.com",
  "allowedTerms": [12]
}

Rules for the list:

Every entry must be a whole number from 1 to 48, and the list cannot be empty. To offer every plan, leave the field out.
Every entry must be a plan active on your account when you create the payment. Otherwise the request is rejected with ALLOWED_TERMS_UNAVAILABLE, and the response lists both the terms that are not available and the ones that are.
Duplicates are removed and the list is stored sorted, so [12, 3, 12] is saved as [3, 12]. GET /developer/v1/one-time-payment/{id} returns it as allowedTerms.

Months without interest require a credit card. When a payment offers only installment plans, a customer paying with a debit card is asked to use a credit card instead.

The plans on your account can change after you create the payment, for example if a plan is deactivated. The checkout never replaces a plan you listed with one you did not: a plan that stops being available is simply no longer offered, and if none of your listed plans is still available the checkout shows that the payment cannot be completed. If a plan stops being available while the customer is paying, the charge is refused and nothing is taken from the card.

Display Modes

Compago supports two display modes for the one-time payment checkout experience.

LINK Mode (Default)

In LINK mode, you redirect the customer to the redirectUrl returned by the API. The customer completes the payment on a full-page Compago checkout page and is then redirected back to your redirectUrl with id and externalId query parameters. This is the simplest integration. Just redirect the customer:

// After creating the one-time payment
window.location.href = checkoutUrl;

EMBEDDED Mode

In EMBEDDED mode, you embed the checkout URL in an iframe on your own page. This keeps the customer on your site throughout the process. Customize the submit button using buttonText and buttonColor.

{
  "displayMode": "EMBEDDED",
  "buttonText": "Pay Now",
  "buttonColor": "#16A34A",
  "amount": 1200,
  "currency": "MXN",
  "description": "Order #12345",
  "externalId": "order_12345_payment_1",
  "redirectUrl": "https://yourstore.com/order/12345/confirmation",
  "homepageUrl": "https://yourstore.com",
  "billingInformation": { ... }
}

Embed the checkout URL in your page:

<div style="width: 100%; max-width: 600px; margin: 0 auto;">
  <iframe
    src="https://app.compago.com/checkout/otp/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
    width="100%"
    height="760"
    frameborder="0"
    allow="payment"
    style="border: none; border-radius: 8px;"
  ></iframe>
</div>

These dimensions are sized to comfortably contain the standard 3DS challenge window the buyer’s bank may render during payment authorization. Smaller envelopes risk clipping the bank’s verification dialog.

In EMBEDDED mode, the iframe handles the entire payment flow. Listen for iframe events to react to loading, success, and error states in real time. The iframe never self-redirects — your parent page decides what to render after a successful payment.

Iframe Events (EMBEDDED Mode)

In EMBEDDED mode, the checkout iframe sends postMessage events to the parent window so you can react without waiting for a redirect.

Events Reference

Event Type	Payload	When Fired
`COMPAGO_ONE_TIME_PAYMENT_LOADING`	`{ type }`	Checkout iframe loads
`COMPAGO_ONE_TIME_PAYMENT_SUCCESS`	`{ type, data: { paymentId, oneTimePaymentId, amount, currency } }`	Payment completed successfully
`COMPAGO_ONE_TIME_PAYMENT_ERROR`	`{ type, error: { code, message } }`	Payment failed, link expired, or already processed

Listening for Events

window.addEventListener('message', (event) => {
  // Filter to only Compago one-time payment events
  if (!event.data?.type?.startsWith('COMPAGO_ONE_TIME_PAYMENT_')) {
    return;
  }

  switch (event.data.type) {
    case 'COMPAGO_ONE_TIME_PAYMENT_LOADING':
      console.log('Checkout is loading...');
      break;

    case 'COMPAGO_ONE_TIME_PAYMENT_SUCCESS':
      console.log('Payment completed!', event.data.data);
      // { paymentId, oneTimePaymentId, amount, currency }
      const { paymentId, oneTimePaymentId } = event.data.data;
      // Verify via API, then fulfill the order
      verifyAndFulfill(paymentId, oneTimePaymentId);
      break;

    case 'COMPAGO_ONE_TIME_PAYMENT_ERROR':
      console.error('Checkout error:', event.data.error);
      // { code, message }
      showErrorMessage(event.data.error.message);
      break;
  }
});

type CompagoOtpEvent =
  | { type: 'COMPAGO_ONE_TIME_PAYMENT_LOADING' }
  | {
      type: 'COMPAGO_ONE_TIME_PAYMENT_SUCCESS';
      data: {
        paymentId: string;
        oneTimePaymentId: string;
        amount: number;
        currency: string;
      };
    }
  | {
      type: 'COMPAGO_ONE_TIME_PAYMENT_ERROR';
      error: { code: string; message: string };
    };

window.addEventListener('message', (event: MessageEvent) => {
  const data = event.data as CompagoOtpEvent;

  if (!data?.type?.startsWith('COMPAGO_ONE_TIME_PAYMENT_')) {
    return;
  }

  switch (data.type) {
    case 'COMPAGO_ONE_TIME_PAYMENT_LOADING':
      console.log('Checkout is loading...');
      break;

    case 'COMPAGO_ONE_TIME_PAYMENT_SUCCESS':
      console.log('Payment completed!', data.data);
      verifyAndFulfill(data.data.paymentId, data.data.oneTimePaymentId);
      break;

    case 'COMPAGO_ONE_TIME_PAYMENT_ERROR':
      console.error('Checkout error:', data.error);
      showErrorMessage(data.error.message);
      break;
  }
});

Error Codes

The error.code field on COMPAGO_ONE_TIME_PAYMENT_ERROR events lets you distinguish failure modes:

Code	When
`ONE_TIME_PAYMENT_NOT_FOUND`	The id is unknown or the link was deleted
`ONE_TIME_PAYMENT_EXPIRED`	`expiresAt` has passed
`ONE_TIME_PAYMENT_ALREADY_PROCESSED`	Status is `CONFIRMED` or `CANCELLED`
`UNSUPPORTED_CARD_BRAND`	Customer used a non-VISA/Mastercard
`CARD_EXPIRED`	Customer’s card is expired
`DEBIT_CARD_NOT_ALLOWED_FOR_INSTALLMENTS`	Customer used a debit card on a months-without-interest plan
`PAYMENT_PLAN_NOT_APPLICABLE`	None of the plans in `allowedTerms` is currently available, or the plan the customer chose stopped being available
`THREEDS_AUTH_FAILED`	3DS challenge failed or was aborted
`PAYMENT_PROCESSING_FAILED`	Bank-level decline or processor error
`PAYMENT_TIMEOUT`	Step-up / processor timeout
`UNEXPECTED_ERROR`	Fallback for any other failure

Validate that event.data.type starts with COMPAGO_ONE_TIME_PAYMENT_ before processing. This filters out unrelated postMessage events from other scripts or browser extensions.

Even when using iframe events, always verify the payment status via the API before fulfilling the order. The COMPAGO_ONE_TIME_PAYMENT_SUCCESS event confirms the checkout completed, but your backend should call GET /api/one-time-payment/{id} to confirm the status is CONFIRMED.

Handling the Payment Callback

When a customer successfully completes a payment, Compago redirects them back to your redirectUrl with two query parameters automatically appended:

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

This allows you to identify which payment completed and take appropriate action in your system.

How the Redirect Works

If you created a payment with:

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

And Compago returns payment ID aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee, then after the customer completes payment, they’ll be redirected to:

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

Implementation Example

Here’s how to handle the callback in your application:

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

from flask import Flask, request, render_template
import requests
import os

app = Flask(__name__)

@app.route('/order/confirmation')
def payment_callback():
    # 1. Extract query parameters
    payment_id = request.args.get('id')
    external_id = request.args.get('externalId')

    if not payment_id or not external_id:
        return 'Missing payment parameters', 400

    # 2. Fetch the payment status from Compago
    response = requests.get(
        f'https://api-harmony.compago.com/api/one-time-payment/{payment_id}',
        headers={'x-api-key': os.environ['COMPAGO_API_KEY']}
    )

    payment = response.json()

    # 3. Update your internal systems
    update_order_status(external_id, 'paid')
    send_confirmation_email(external_id)

    # 4. Show success page to customer
    return render_template('order_success.html',
        order_id=external_id,
        amount=payment['amount']
    )

<?php
// Your callback page: /order/confirmation.php

// 1. Extract query parameters
$paymentId = $_GET['id'] ?? null;
$externalId = $_GET['externalId'] ?? null;

if (!$paymentId || !$externalId) {
    http_response_code(400);
    die('Missing payment parameters');
}

// 2. Fetch the payment status from Compago
$ch = curl_init("https://api-harmony.compago.com/api/one-time-payment/{$paymentId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: ' . getenv('COMPAGO_API_KEY')
]);

$response = curl_exec($ch);
$payment = json_decode($response, true);
curl_close($ch);

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

// 4. Show success page to customer
include 'order_success.php';
?>

class OrdersController < ApplicationController
  def confirmation
    # 1. Extract query parameters
    payment_id = params[:id]
    external_id = params[:externalId]

    if payment_id.blank? || external_id.blank?
      render plain: 'Missing payment parameters', status: :bad_request
      return
    end

    # 2. Fetch the payment status from Compago
    response = HTTParty.get(
      "https://api-harmony.compago.com/api/one-time-payment/#{payment_id}",
      headers: { 'x-api-key' => ENV['COMPAGO_API_KEY'] }
    )

    payment = response.parsed_response

    # 3. Update your internal systems
    update_order_status(external_id, 'paid')
    send_confirmation_email(external_id)

    # 4. Show success page to customer
    render :order_success, locals: {
      order_id: external_id,
      amount: payment['amount']
    }
  end
end

Best Practices for Callback Handling

Always Verify Payment Status

Never trust the redirect alone. Always fetch the payment details from Compago’s API to confirm the status. The redirect happens client-side and could be manipulated.

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

Handle Missing Query Parameters

Implement validation to handle cases where query parameters might be missing (user navigating directly to the URL, etc.).

const { id, externalId } = req.query;

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

Implement Idempotency

The callback URL might be accessed multiple times (user refreshing page, browser back button). Ensure your fulfillment logic is idempotent.

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

Use HTTPS for Callback URLs

Always use HTTPS URLs for your redirectUrl to ensure query parameters are transmitted securely.

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

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

Preserve Existing Query Parameters

If your redirectUrl already contains query parameters, Compago will append id and externalId to them. Design your callback handler to work with multiple parameters.

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

Never skip verification! The redirect URL is visible to the customer and could potentially be manipulated. Always fetch the payment status from Compago’s API using the id parameter before fulfilling the order.

Your callback implementation should:

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

Testing Your Callback Handler

To test your callback implementation:

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

You can also manually test by navigating to your callback URL with test parameters:

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

(Your code should handle this gracefully, likely returning a “payment not found” or similar error.)

Important Business Rules

Payment Expiration

One-time payment links expire 48 hours after creation by default. If a customer does not complete the payment within this time, the link becomes invalid and cannot be used.

You can customize the expiration time using the ttlMinutes parameter (see Custom Expiration Times below). If your OTP expired and you need to create a new payment for the same transaction, generate a new OTP using a different externalId.

Custom Expiration Times

You can set a custom expiration time for payment links using the optional ttlMinutes parameter. This allows you to create payment links that expire sooner or later based on your business needs. Configuration:

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

Common use cases:

Flash Sales (Short TTL)

For time-sensitive promotions or limited inventory:

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

Use short expiration times (10-60 minutes) to create urgency and ensure inventory isn’t held indefinitely.

Standard Invoices (Default TTL)

For typical invoice payments:

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

The default 48-hour window gives customers plenty of time to complete payment at their convenience.

Event Tickets (Custom TTL)

For event registrations with registration deadlines:

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

Match the TTL to your event registration deadline to automatically close registration.

Quote Acceptance (Extended TTL)

For quotes that customers need time to review:

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

Give customers the maximum time to review and approve quotes before they expire.

Best practices:

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

Each Compago account has a configured minimum payment amount. Requests with amounts below this threshold will be rejected with a 400 error. If you receive this error, ensure your payment amount meets your account’s minimum requirement.

External ID Uniqueness

The externalId must be unique within your organization. Attempting to create a payment with a duplicate externalId will result in a 400 error:

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

Use unique identifiers for each payment attempt. If a payment fails or expires, create a new one-time payment with a new externalId.

Currency Restriction

Currently, only MXN (Mexican Peso) is supported. Requests with other currencies will be rejected.

Payment Status

One-time payments have three statuses:

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

Once a payment is marked as CONFIRMED or CANCELLED, the one-time payment link can no longer be used. See the Cancel One-Time Payment guide to learn how to cancel pending payments.

Retrieving Payment Details

You can retrieve the status and details of a one-time payment using the GET endpoint. Common use case: After receiving a payment callback at your redirectUrl, use the id query parameter to fetch the payment status and verify completion before fulfilling the order. See Handling the Payment Callback for complete implementation examples.

Endpoint

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

API reference: GET /one-time-payment/{id}

Response for Active Payments

If the payment is still PENDING and has not expired, you’ll receive full payment details:

{
  "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

If the payment is no longer PENDING or has expired, the response will contain limited information:

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

The expired field indicates whether the payment link has passed its 48-hour expiration time, regardless of its status.

Supported Mexican States

Use the following state codes in the address.state field:

Code	State
`AGU`	Aguascalientes
`BCN`	Baja California
`BCS`	Baja California Sur
`CAM`	Campeche
`CHP`	Chiapas
`CHH`	Chihuahua
`CDMX`	Ciudad de México
`COA`	Coahuila
`COL`	Colima
`DUR`	Durango
`MEX`	Estado de México
`GUA`	Guanajuato
`GRO`	Guerrero
`HID`	Hidalgo
`JAL`	Jalisco
`MIC`	Michoacán
`MOR`	Morelos
`NAY`	Nayarit
`NLE`	Nuevo León
`OAX`	Oaxaca
`PUE`	Puebla
`QUE`	Querétaro
`ROO`	Quintana Roo
`SLP`	San Luis Potosí
`SIN`	Sinaloa
`SON`	Sonora
`TAB`	Tabasco
`TAM`	Tamaulipas
`TLA`	Tlaxcala
`VER`	Veracruz
`YUC`	Yucatán
`ZAC`	Zacatecas

Error Handling

Common Errors

Status Code	Error	Solution
400	Amount below minimum	Ensure amount meets your account’s minimum payment threshold
400	Duplicate externalId	Use a unique externalId for each payment
400	Currency not supported	Use `"MXN"` as the currency
400	`ALLOWED_TERMS_UNAVAILABLE`	Remove the terms listed in `unavailableTerms`, or omit `allowedTerms` to offer every plan on your account
401	Unauthorized	Check your API key is valid and included in headers
400	Missing organization context	Verify your organization settings are configured correctly

Example Error Response

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

An allowedTerms entry that is not active on your account also carries a code to branch on, and both lists:

{
  "message": "Terms 18 are not available for this account.",
  "code": "ALLOWED_TERMS_UNAVAILABLE",
  "unavailableTerms": [18],
  "availableTerms": [1, 3, 6, 12]
}

Best Practices

Generate Unique External IDs: Use a combination of order ID and timestamp to ensure uniqueness
Handle Expiration: Implement logic to create new payment links if the 48-hour window expires
Validate Amounts: Ensure amounts meet your account’s minimum payment threshold before calling the API
Store Payment IDs: Save the returned one-time payment ID to track and verify payments later
Implement Webhooks: Use webhooks (if available) to receive real-time payment status updates
Test Thoroughly: Use the demo environment to test your integration before going live
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

If you encounter issues with one-time payments:

Verify your API key is valid in Configuraciones → Desarrollador of the dashboard of the environment you call (Demo or Production), and that you call the host of that same environment
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 help@compago.com for assistance

​What You Can Do

​Use Cases

​How It Works

​Prerequisites

​Creating a One-Time Payment

​Endpoint

​Authentication

​Request Body

​Field Descriptions

​Billing Information

​Address

​Response

​Example with cURL

​Who provides the customer details

​Choosing the installment plans

​Display Modes

​LINK Mode (Default)

​EMBEDDED Mode

​Iframe Events (EMBEDDED Mode)

​Events Reference

​Listening for Events

​Error Codes

​Handling the Payment Callback

​How the Redirect Works

​Implementation Example

​Best Practices for Callback Handling

​Security Considerations

​Testing Your Callback Handler

​Important Business Rules

​Payment Expiration

​Custom Expiration Times

​Minimum Amount

​External ID Uniqueness

​Currency Restriction

​Payment Status

​Retrieving Payment Details

​Endpoint

​Response for Active Payments

​Response for Completed or Expired Payments

​Supported Mexican States

​Error Handling

​Common Errors

​Example Error Response

​Best Practices

​Support

What You Can Do

Use Cases

How It Works

Prerequisites

Creating a One-Time Payment

Endpoint

Authentication

Request Body

Field Descriptions

Billing Information

Address

Response

Example with cURL

Who provides the customer details

Choosing the installment plans

Display Modes

LINK Mode (Default)

EMBEDDED Mode

Iframe Events (EMBEDDED Mode)

Events Reference

Listening for Events

Error Codes

Handling the Payment Callback

How the Redirect Works

Implementation Example

Best Practices for Callback Handling

Security Considerations

Testing Your Callback Handler

Important Business Rules

Payment Expiration

Custom Expiration Times

Minimum Amount

External ID Uniqueness

Currency Restriction

Payment Status

Retrieving Payment Details

Endpoint

Response for Active Payments

Response for Completed or Expired Payments

Supported Mexican States

Error Handling

Common Errors

Example Error Response

Best Practices

Support