> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear cargo

> Endpoint para crear un cargo en el sistema de OnePay.

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="title" type="string" required>
  Descripción del cargo en el estado de cuenta del banco
</ParamField>

<ParamField body="customer_id" type="string" required placeholder="9dd4158b-0e45-42bc-b56f-a4c1f856814d">
  ID del cliente que asumirá el cargo. [Crear cliente](/client/customers/create).
</ParamField>

<ParamField body="amount" type="number" required placeholder="100000">
  Monto del cargo en centavos.
</ParamField>

<ParamField body="account_id" type="string" placeholder="9d0ac58c-2226-4f1c-b305-15e6dc3b47f6">
  ID de la cuenta bancaria registrada. [Ver creación de cuentas](/client/accounts/create). Requerido si `card_id` está vacío.
</ParamField>

<ParamField body="card_id" type="string" placeholder="bb02b2fd-154c-4c90-9fdf-cec3a0b25cf5">
  ID de la tarjeta tokenizada. [Conoce cómo registrar tarjetas](/client/cards/create). Requerido si `account_id` está vacío.
</ParamField>

<ParamField body="installments" type="integer" placeholder="1">
  Número de cuotas para el cargo. Opcional (útil para flujos VIP).
  Valores permitidos: `1` a `36`.
  Valor por defecto: `1`.
</ParamField>

<ParamField body="currency" type="string" placeholder="COP">
  Moneda del cargo
</ParamField>

<ParamField body="redirect_url" type="string" placeholder="https://onepay.la">
  URL de redirección
</ParamField>

<ParamField body="external_id" type="string" placeholder="invoice-123">
  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`

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

<ParamField body="splits" type="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.

  <Expandable title="Campos de splits[]">
    <ParamField body="splits[].customer_id" type="string" required>
      ID del cliente beneficiario del split. [Ver clientes](/client/customers/create).
    </ParamField>

    <ParamField body="splits[].split_type" type="string" required>
      Tipo de distribución:

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

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

    <ParamField body="splits[].split_value" type="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
    </ParamField>

    <ParamField body="splits[].description" type="string">
      Descripción interna del split.
    </ParamField>

    <ParamField body="splits[].account_id" type="string">
      ID de la cuenta bancaria donde se recibirá el split. Si no se especifica, se usa la cuenta principal del cliente.
    </ParamField>

    <ParamField body="splits[].scheduled_at" type="string">
      Fecha programada para realizar el split (`YYYY-MM-DD HH:mm:ss`). Si es `null`, se ejecuta de inmediato.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="test_scenario" type="string">
  Escenario de prueba para el cargo \[Opcional].
  [Ver escenarios de prueba](/client/charges/scenarios)
</ParamField>

<Note>
  **Métodos de pago permitidos**

  El 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.
</Note>

<RequestExample>
  ```bash cURL - Cargo con tarjeta theme={null}
  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"
    }'
  ```

  ```bash cURL - Cargo con cuenta bancaria theme={null}
  curl https://api.onepay.la/v1/charges \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -H "x-idempotency: charge-account-001" \
    -d '{
      "title": "Cuota mensual",
      "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "amount": 200000,
      "account_id": "84cc072e-90e8-33cf-9305-098095fed32f",
      "currency": "COP",
      "external_id": "subscription-456"
    }'
  ```

  ```javascript JavaScript - Cargo con tarjeta theme={null}
  const response = await fetch('https://api.onepay.la/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json',
      'x-idempotency': 'charge-card-001'
    },
    body: JSON.stringify({
      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'
    })
  });

  const charge = await response.json();
  ```

  ```javascript JavaScript - Cargo con cuenta bancaria theme={null}
  const response = await fetch('https://api.onepay.la/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json',
      'x-idempotency': 'charge-account-001'
    },
    body: JSON.stringify({
      title: 'Cuota mensual',
      customer_id: '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
      amount: 200000,
      account_id: '84cc072e-90e8-33cf-9305-098095fed32f',
      currency: 'COP',
      external_id: 'subscription-456'
    })
  });

  const charge = await response.json();
  ```

  ```python Python - Cargo con tarjeta theme={null}
  import requests

  response = requests.post(
      'https://api.onepay.la/v1/charges',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'Content-Type': 'application/json',
          'x-idempotency': 'charge-card-001'
      },
      json={
          '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'
      }
  )

  charge = response.json()
  ```

  ```python Python - Cargo con cuenta bancaria theme={null}
  import requests

  response = requests.post(
      'https://api.onepay.la/v1/charges',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'Content-Type': 'application/json',
          'x-idempotency': 'charge-account-001'
      },
      json={
          'title': 'Cuota mensual',
          'customer_id': '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
          'amount': 200000,
          'account_id': '84cc072e-90e8-33cf-9305-098095fed32f',
          'currency': 'COP',
          'external_id': 'subscription-456'
      }
  )

  charge = response.json()
  ```

  ```php PHP - Cargo con tarjeta theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/charges",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_test_xxx",
      "Content-Type: application/json",
      "x-idempotency: charge-card-001"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "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"
    ])
  ]);

  $response = curl_exec($curl);
  $charge = json_decode($response, true);
  ?>
  ```

  ```php PHP - Cargo con cuenta bancaria theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/charges",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_test_xxx",
      "Content-Type: application/json",
      "x-idempotency: charge-account-001"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "title" => "Cuota mensual",
      "customer_id" => "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "amount" => 200000,
      "account_id" => "84cc072e-90e8-33cf-9305-098095fed32f",
      "currency" => "COP",
      "external_id" => "subscription-456"
    ])
  ]);

  $response = curl_exec($curl);
  $charge = json_decode($response, true);
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
      }
    ]
  }
  ```

  ```json 422 theme={null}
  {
     "message":"El campo cantidad es obligatorio. (y 2 errores más)",
     "code":10001,
     "code_name":"validation_error",
     "errors":{
        "amount":[
           "El campo cantidad es obligatorio."
        ],
        "title":[
           "El campo título es obligatorio."
        ],
        "customer_id":[
           "El campo customer id es obligatorio."
        ]
     }
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>