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

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 redirectUrl for the checkout page
Redirect: Send your customer to the redirectUrl where they enter their payment details
Process: Compago processes the payment securely through its payment infrastructure
Return: After payment completion (successful or failed), the customer is redirected back to your redirectUrl
Verify: Check the payment status using the GET endpoint or through webhooks (if configured)

Prerequisites

Before creating one-time payments, ensure you have:

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

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

Creating a One-Time Payment

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

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 sent after completing payment (success or failure).
`homepageUrl`	string	Yes	Your homepage URL, used if the customer cancels or wants to return to your site.
`billingInformation`	object	Yes	Customer billing details (see below).

Billing Information

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/abc123-def456-ghi789"
}

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",
    "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"
      }
    }
  }'

Important Business Rules

Payment Expiration

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

To create a new payment for the same transaction, generate a new one-time payment with a different externalId.

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 two statuses:

PENDING: Payment link is active and waiting for customer to complete payment
CONFIRMED: Customer has successfully completed the payment

Once a payment is marked as CONFIRMED, the one-time payment link can no longer be used.

Retrieving Payment Details

You can retrieve the status and details of a one-time payment using the GET endpoint.

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": "abc123-def456-ghi789",
  "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 15-minute 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
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]."
}

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 15-minute 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

Support

If you encounter issues with one-time payments:

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

Get Started

One-time payment

Odoo Integration

One-Time Payments

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

Important Business Rules

Payment Expiration

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

Get Started

One-time payment

Odoo Integration

​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

​Important Business Rules

​Payment Expiration

​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

Important Business Rules

Payment Expiration

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