Crear cargo - OnePay Documentación

curl https://api.onepay.la/v1/charges \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: charge-card-001" \
  -d '{
    "title": "Mensualidad Enero 2025",
    "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "amount": 85000,
    "card_id": "9e01eeae-2868-4564-9d04-84d1d1d027d2",
    "installments": 3,
    "currency": "COP",
    "external_id": "invoice-2025-001"
  }'

{
  "id": "9e02966f-2ddf-4ee7-a391-5b5b7653e232",
  "title": "Test Charge",
  "amount": 1000,
  "amount_label": "$1.000",
  "source": "charge",
  "status": "declined",
  "currency": "COP",
  "payment_method_type": "Account",
  "payment_method_id": "4dc959d0-d96a-377a-823e-5e05cfde896f",
  "created_at": "2025-01-20T02:18:29.000000Z",
  "paid_at": null,
  "remarks": {
    "code": "INTERNAL_ERROR",
    "description": "Error interno. Comunícate con soporte para resolver el problema."
  },
  "is_test": true,
  "network_id": null,
  "external_id": "invoice-2025-001",
  "method": {
    "id": "4dc959d0-d96a-377a-823e-5e05cfde896f",
    "title": "Dr.",
    "subtype": "SAVINGS",
    "status": "PENDING",
    "authorization": true,
    "customer_id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
    "re_enroll": false,
    "external_id": null,
    "bank_id": "9e02966e-8d60-49b0-ad66-372bf73c4a54",
    "bank": {
      "id": "9e02966e-8d60-49b0-ad66-372bf73c4a54",
      "name": "Hoeger PLC",
      "logo": null
    }
  },
  "customer": {
    "id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
    "first_name": "Florencio",
    "last_name": "Conroy",
    "email": "",
    "phone": "+12518057105",
    "document_type": "CC",
    "document_number": "930232",
    "created_at": "2025-01-20T02:18:29.000000Z",
    "is_test": true
  },
  "splits": [
    {
      "id": "9e02966f-3204-4e50-9fb7-b8bc0214a93b",
      "customer_id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
      "split_type": "percentage",
      "split_value": 300,
      "description": "Test Split",
      "created_at": "2025-01-20T02:18:29.000000Z",
      "scheduled_at": null,
      "account_id": "4dc959d0-d96a-377a-823e-5e05cfde896f"
    }
  ]
}

POST

charges

curl https://api.onepay.la/v1/charges \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: charge-card-001" \
  -d '{
    "title": "Mensualidad Enero 2025",
    "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "amount": 85000,
    "card_id": "9e01eeae-2868-4564-9d04-84d1d1d027d2",
    "installments": 3,
    "currency": "COP",
    "external_id": "invoice-2025-001"
  }'

{
  "id": "9e02966f-2ddf-4ee7-a391-5b5b7653e232",
  "title": "Test Charge",
  "amount": 1000,
  "amount_label": "$1.000",
  "source": "charge",
  "status": "declined",
  "currency": "COP",
  "payment_method_type": "Account",
  "payment_method_id": "4dc959d0-d96a-377a-823e-5e05cfde896f",
  "created_at": "2025-01-20T02:18:29.000000Z",
  "paid_at": null,
  "remarks": {
    "code": "INTERNAL_ERROR",
    "description": "Error interno. Comunícate con soporte para resolver el problema."
  },
  "is_test": true,
  "network_id": null,
  "external_id": "invoice-2025-001",
  "method": {
    "id": "4dc959d0-d96a-377a-823e-5e05cfde896f",
    "title": "Dr.",
    "subtype": "SAVINGS",
    "status": "PENDING",
    "authorization": true,
    "customer_id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
    "re_enroll": false,
    "external_id": null,
    "bank_id": "9e02966e-8d60-49b0-ad66-372bf73c4a54",
    "bank": {
      "id": "9e02966e-8d60-49b0-ad66-372bf73c4a54",
      "name": "Hoeger PLC",
      "logo": null
    }
  },
  "customer": {
    "id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
    "first_name": "Florencio",
    "last_name": "Conroy",
    "email": "",
    "phone": "+12518057105",
    "document_type": "CC",
    "document_number": "930232",
    "created_at": "2025-01-20T02:18:29.000000Z",
    "is_test": true
  },
  "splits": [
    {
      "id": "9e02966f-3204-4e50-9fb7-b8bc0214a93b",
      "customer_id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
      "split_type": "percentage",
      "split_value": 300,
      "description": "Test Split",
      "created_at": "2025-01-20T02:18:29.000000Z",
      "scheduled_at": null,
      "account_id": "4dc959d0-d96a-377a-823e-5e05cfde896f"
    }
  ]
}

Headers

x-idempotency

string

required

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

Body

title

string

required

Descripción del cargo en el estado de cuenta del banco

customer_id

string

required

ID del cliente que asumirá el cargo. Crear cliente.

amount

number

required

Monto del cargo en centavos.

account_id

string

ID de la cuenta bancaria registrada. Ver creación de cuentas. Requerido si card_id está vacío.

card_id

string

ID de la tarjeta tokenizada. Conoce cómo registrar tarjetas. Requerido si account_id está vacío.

installments

integer

Número de cuotas para el cargo. Opcional (útil para flujos VIP). Valores permitidos: 1 a 36. Valor por defecto: 1.

currency

string

Moneda del cargo

redirect_url

string

URL de redirección

external_id

string

ID único de tu sistema para correlacionar el cargo con tus registros internos. Este campo te permite rastrear el cargo cuando lleguen los eventos de webhook.

Longitud: 1 a 100 caracteres
Opcional: Si no se proporciona, el campo será null
Aparece en: Response de creación y eventos de webhook bajo charge_details.external_id

Este campo es útil para asociar el cargo con tu ID de factura, orden, o cualquier otro identificador de tu sistema.

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.

Show Campos de splits[]

splits[].customer_id

string

required

ID del cliente beneficiario del split. Ver clientes.

splits[].split_type

string

required

Tipo de distribución:

percentage — Porcentaje del monto total (en centésimas: 1000 = 10%)
fixed — Monto fijo en centavos

Si el total de splits supera el 100% del monto o excede el monto total, la operación será rechazada.

splits[].split_value

integer

required

Valor del split según el tipo:

Si split_type es percentage: valor en centésimas (500 = 5%, 10000 = 100%)
Si split_type es fixed: monto en centavos

splits[].description

string

Descripción interna del split.

splits[].account_id

string

ID de la cuenta bancaria donde se recibirá el split. Si no se especifica, se usa la cuenta principal del cliente.

splits[].scheduled_at

string

Fecha programada para realizar el split (YYYY-MM-DD HH:mm:ss). Si es null, se ejecuta de inmediato.

test_scenario

string

Escenario de prueba para el cargo [Opcional]. Ver escenarios de prueba

Métodos de pago permitidosEl método de pago disponible depende de la configuración de tu cuenta. Comunícate con el equipo de soporte para habilitar métodos adicionales.

Método	Campo requerido	Descripción
Cuenta bancaria (ACH)	`account_id`	Débito directo desde cuenta bancaria registrada
Tarjeta de crédito/débito	`card_id`	Cargo a tarjeta tokenizada

Solo uno de los dos (account_id o card_id) debe estar presente en la petición.

curl https://api.onepay.la/v1/charges \
  -X POST \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "x-idempotency: charge-card-001" \
  -d '{
    "title": "Mensualidad Enero 2025",
    "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
    "amount": 85000,
    "card_id": "9e01eeae-2868-4564-9d04-84d1d1d027d2",
    "installments": 3,
    "currency": "COP",
    "external_id": "invoice-2025-001"
  }'

{
  "id": "9e02966f-2ddf-4ee7-a391-5b5b7653e232",
  "title": "Test Charge",
  "amount": 1000,
  "amount_label": "$1.000",
  "source": "charge",
  "status": "declined",
  "currency": "COP",
  "payment_method_type": "Account",
  "payment_method_id": "4dc959d0-d96a-377a-823e-5e05cfde896f",
  "created_at": "2025-01-20T02:18:29.000000Z",
  "paid_at": null,
  "remarks": {
    "code": "INTERNAL_ERROR",
    "description": "Error interno. Comunícate con soporte para resolver el problema."
  },
  "is_test": true,
  "network_id": null,
  "external_id": "invoice-2025-001",
  "method": {
    "id": "4dc959d0-d96a-377a-823e-5e05cfde896f",
    "title": "Dr.",
    "subtype": "SAVINGS",
    "status": "PENDING",
    "authorization": true,
    "customer_id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
    "re_enroll": false,
    "external_id": null,
    "bank_id": "9e02966e-8d60-49b0-ad66-372bf73c4a54",
    "bank": {
      "id": "9e02966e-8d60-49b0-ad66-372bf73c4a54",
      "name": "Hoeger PLC",
      "logo": null
    }
  },
  "customer": {
    "id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
    "first_name": "Florencio",
    "last_name": "Conroy",
    "email": "",
    "phone": "+12518057105",
    "document_type": "CC",
    "document_number": "930232",
    "created_at": "2025-01-20T02:18:29.000000Z",
    "is_test": true
  },
  "splits": [
    {
      "id": "9e02966f-3204-4e50-9fb7-b8bc0214a93b",
      "customer_id": "9e02966e-8beb-4e02-ba0c-bea875a07b22",
      "split_type": "percentage",
      "split_value": 300,
      "description": "Test Split",
      "created_at": "2025-01-20T02:18:29.000000Z",
      "scheduled_at": null,
      "account_id": "4dc959d0-d96a-377a-823e-5e05cfde896f"
    }
  ]
}

Detalle cargo

Crear un link de pago (PSE)

​Headers

​Body

Headers

Body