Skip to main content
POST
https://api.onepay.la/v1
/
payments
Crear cobro
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,
    "card_extra": true,
    "realtime": true,
    "pse": true,
    "transfiya": true
  }
}
'
{
  "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": "+573201112233",
  "email": "[email protected]",
  "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.

​
Ejemplos de uso

  • curl
  • JavaScript
  • Python
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": "+573201112233",
    "email": "[email protected]",
    "redirect_url": "https://app.onepay.la/thanks",
    "allows": {
      "cards": true,
      "accounts": true,
      "pse": true
    },
    "metadata": {
      "salesforce_id": "OP-554"
    }
  }'

​
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

{
  "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": "+573201112233",
  "email": "[email protected]",
  "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
}