Crear cobro

POST https://api.onepay.la/v1/payments

Crear cobro

cURL

curl --request POST \
  --url https://api.onepay.la/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency: <x-idempotency>' \
  --data '
{
  "amount": 123,
  "title": "<string>",
  "currency": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "reference": "<string>",
  "tax": 123,
  "external_id": "<string>",
  "description": "<string>",
  "document_url": "<string>",
  "expiration_date": "<string>",
  "schedule_at": "<string>",
  "metadata": {},
  "redirect_url": "<string>",
  "splits": [
    {
      "customer_id": "<string>",
      "account_id": "<string>",
      "split_type": "<string>",
      "split_value": "<string>",
      "description": "<string>",
      "schedule_at": "<string>",
      "process": "<string>",
      "to_company_wallet": true
    }
  ],
  "allows": {
    "cards": true,
    "accounts": true,
    "wallets": true,
    "card_extra": true,
    "realtime": true,
    "pse": true,
    "full_extra": true,
    "pse_debit": true,
    "breb": true
  }
}
'

200

{
  "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "amount": 1400000,
  "amount_label": "$1.400.000",
  "currency": "COP",
  "title": "Suscripción Premium",
  "description": null,
  "reference": "INV-2045",
  "status": "pending",
  "source": "outbound",
  "source_id": null,
  "customer": null,
  "phone": "[phone]",
  "email": "[e-mail]",
  "expiration_at": "2025-03-20T22:36:24.000000Z",
  "redirect_url": "https://app.onepay.la/thanks",
  "payment_link": "https://pagos.onepay.la/payment/9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "allows": {
    "cards": true,
    "accounts": true,
    "card_extra": false,
    "realtime": false,
    "pse": true,
    "transfiya": true
  },
  "metadata": {
    "salesforce_id": "OP-554"
  },
  "splits": [],
  "coupon": null,
  "created_at": "2025-03-05T22:36:24.000000Z",
  "is_expired": false
}

Crea un nuevo pago en tu cuenta.

Headers

x-idempotency · string · required

Token único para garantizar la idempotencia de la petición

Body

amount · number · required

Monto a cobrar cuando el cliente recibe el pago

title · string · required

Breve mensaje que se mostrará al usuario al realizar el pago

currency · string

Código de moneda ISO (COP, USD) por defecto COP

phone · string

Número de teléfono del cliente a enviar la solicitud de pago via whatsapp.

email · string

Campo opcional si quieres enviar una solicitud de pago via email

reference · string

Referencia de pago para que el usuario pueda interactuar con el portal de recaudo.

tax · number

Monto en la misma moneda con valor de impuestos, el valor predeterminado será del 19%

external_id · string

ID externo para relacionar el pago con un registro ya existente en tu sistema.

description · string

Descripción del pago

document_url · string

URL de un documento que se mostrará al usuario para que pueda realizar el pago.

expiration_date · date

Fecha de expiración del pago en formato YYYY-MM-DD HH:MM:SS

schedule_at · date

Fecha en la que el pago será enviado al usuario. YYYY-MM-DD.

metadata · object

Metadatos adicionales del pago en formato JSON

redirect_url · string

URL de redirección

splits · array

Los pagos divididos permiten distribuir automáticamente un único pago entre múltiples destinatarios según reglas preestablecidas, optimizando la gestión de fondos sin necesidad de cálculos manuales o costos adicionales.

customer_id · string · required

ID del cliente que recibirá el pago. Ver cómo crear un cliente.

account_id · string · required

ID de la cuenta bancaria registrada. Conoce cómo registrar cuentas.

split_type · string

Tipo de división: percentage o fixed

split_value · string · required

Valor del pago dividido si % o un monto

description · string · required

Descripción del pago para el cliente que recibirá el pago.

schedule_at · string

Fecha en la que el pago se le envía al cliente, si no existe una fecha se hará automáticamente. YYYY-MM-DD.

process · string · default: "ACH"

Que tipo de proceso se va a realizar, por defecto es ACH. [TURBO, ACH]

to_company_wallet · boolean · default: "false"

Indica si el pago se va a realizar en la wallet de otra empresa.

allows · object

Configuración de métodos de pago permitidos.

Show properties

cards · boolean · default: true

Permite pagos con tarjetas.

accounts · boolean · default: true

Permite pagos con cuentas bancarias.

wallets · boolean · default: true

Permite pagos con billeteras digitales.

card_extra · boolean · default: false

El usuario pagador debe de asumir un costo extra en la transacción aprox. 2.65%

realtime · boolean · default: false

Permite pagos en tiempo real.

pse · boolean · default: true

Permite pagos a través de PSE.

full_extra · boolean · default: false

El usuario pagador asume el costo completo de la transacción.

pse_debit · boolean · default: false

Permite débitos automáticos a través de PSE.

breb · boolean · default: true

Permite pagos a través de BREB (transferencias bancarias).

Ejemplos de uso

curl

curl https://api.onepay.la/v1/payments \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: payment-123" \
  -d '{
    "amount": 1400000,
    "currency": "COP",
    "title": "Suscripción Premium",
    "reference": "INV-2045",
    "phone": "[phone]",
    "email": "[e-mail]",
    "redirect_url": "https://app.onepay.la/thanks",
    "allows": {
      "cards": true,
      "accounts": true,
      "pse": true
    },
    "metadata": {
      "salesforce_id": "OP-554"
    }
  }'

JavaScript

import fetch from 'node-fetch';

const body = {
  amount: 1400000,
  currency: 'COP',
  title: 'Suscripción Premium',
  reference: 'INV-2045',
  phone: '[phone]',
  email: '[e-mail]',
  redirect_url: 'https://app.onepay.la/thanks',
  allows: {
    cards: true,
    accounts: true,
    pse: true
  },
  metadata: {
    salesforce_id: 'OP-554'
  }
};

await fetch('https://api.onepay.la/v1/payments', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_xxx',
    'Content-Type': 'application/json',
    'x-idempotency': 'payment-123'
  },
  body: JSON.stringify(body)
});

Python

import requests

payload = {
    "amount": 1400000,
    "currency": "COP",
    "title": "Suscripción Premium",
    "reference": "INV-2045",
    "phone": "[phone]",
    "email": "[e-mail]",
    "redirect_url": "https://app.onepay.la/thanks",
    "allows": {
        "cards": True,
        "accounts": True,
        "pse": True
    },
    "metadata": {
        "salesforce_id": "OP-554"
    }
}

response = requests.post(
    "https://api.onepay.la/v1/payments",
    headers={
        "Authorization": "Bearer sk_test_xxx",
        "x-idempotency": "payment-123"
    },
    json=payload,
    timeout=15
)
response.raise_for_status()
print(response.json())

Response

id · string

Identificador único del pago

amount · number

Monto del pago en centavos

currency · string

Código de moneda ISO

status · string

Estado del pago:

• pending - Pendiente
• processing - Procesando
• succeeded - Exitoso
• failed - Fallido

customer_id · string

ID del cliente que realizó el pago

payment_method · string

Método de pago utilizado

description · string

Descripción del pago

metadata · object

Metadatos adicionales del pago

created_at · string

Fecha y hora de creación en formato ISO 8601

Ejemplo de respuesta

200

{
  "id": "9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "amount": 1400000,
  "amount_label": "$1.400.000",
  "currency": "COP",
  "title": "Suscripción Premium",
  "description": null,
  "reference": "INV-2045",
  "status": "pending",
  "source": "outbound",
  "source_id": null,
  "customer": null,
  "phone": "[phone]",
  "email": "[e-mail]",
  "expiration_at": "2025-03-20T22:36:24.000000Z",
  "redirect_url": "https://app.onepay.la/thanks",
  "payment_link": "https://pagos.onepay.la/payment/9e5ccd4a-d2f0-49dd-87fc-a0da752bd166",
  "allows": {
    "cards": true,
    "accounts": true,
    "card_extra": false,
    "realtime": false,
    "pse": true,
    "transfiya": true
  },
  "metadata": {
    "salesforce_id": "OP-554"
  },
  "splits": [],
  "coupon": null,
  "created_at": "2025-03-05T22:36:24.000000Z",
  "is_expired": false
}