> ## 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 tarjetas

> Endpoint para registrar una tarjeta de crédito o débito en el sistema de OnePay.

<Warning>
  Cambio de dominio para el endpoint de tarjetas: [https://cards.onepay.la/v1/cards](https://cards.onepay.la/v1/cards)
</Warning>

<Note>
  Este cambio se implementa mediante un proxy con el objetivo de mejorar la gestión de la política PCI DSS y garantizar un cumplimiento más seguro y eficiente de los estándares de seguridad en el manejo de datos de tarjetas.
</Note>

### 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="card_number" type="string" required placeholder="4242424242424242">
  Número de la tarjeta de crédito o débito.
</ParamField>

<ParamField body="expiration_year" type="string" required placeholder="28">
  Año de vencimiento en formato de 2 dígitos (ejemplo: `28`).
</ParamField>

<ParamField body="expiration_month" type="string" required placeholder="08">
  Mes de vencimiento en formato de 2 dígitos (ejemplo: `08`).
</ParamField>

<ParamField body="ccv" type="string" required placeholder="123">
  Código de seguridad de la tarjeta.
</ParamField>

<ParamField body="holder_name" type="string" required placeholder="Juan Pérez">
  Nombre completo del titular como aparece en la tarjeta.
</ParamField>

<ParamField body="customer_id" type="string" required placeholder="9dd4158b-0e45-42bc-b56f-a4c1f856814d">
  ID del cliente dueño de la tarjeta. [Crear cliente](/client/customers/create).
</ParamField>

<ParamField body="authorization" type="boolean" required placeholder="false">
  Indica si el usuario ha autorizado débitos automáticos para esta tarjeta.
</ParamField>

<ParamField body="authentication" type="object">
  Datos de autenticación 3D Secure. Envía este campo si realizaste la autenticación 3DS de forma externa.

  <Expandable title="Campos de authentication">
    <ParamField body="authentication.cavv" type="string" required>
      Cardholder Authentication Verification Value. Criptograma generado por el servidor 3DS.
    </ParamField>

    <ParamField body="authentication.eci" type="string" required>
      Electronic Commerce Indicator. Indica el resultado de la autenticación (ejemplo: `05`, `02`, `07`).
    </ParamField>

    <ParamField body="authentication.ds_trans_id" type="string">
      Directory Server Transaction ID. Identificador único de la transacción 3DS.
    </ParamField>

    <ParamField body="authentication.xid" type="string">
      Transaction ID de la autenticación (usado en 3DS 1.0).
    </ParamField>

    <ParamField body="authentication.version" type="string">
      Versión del protocolo 3DS utilizado (ejemplo: `2.2.0`).
    </ParamField>

    <ParamField body="authentication.status" type="string">
      Estado de la autenticación. Valores comunes: `Y` (autenticado), `A` (intento), `N` (fallido).
    </ParamField>
  </Expandable>
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
     "id":"9e01eeae-2868-4564-9d04-84d1d1d027d2",
     "brand":"Mastercard",
     "last_four":"8099",
     "card_name":"Juan Pérez",
     "expiration_date":"2026-09-30T00:00:00.000000Z",
     "customer_id":"9df8018b-6a28-4696-b7b2-63615f34a2f5",
     "created_at":"2025-01-19T18:29:25.000000Z",
     "type":"credit_card",
     "country":"CO",
     "cvc_check":true,
     "verified":true,
     "title":"Mastercard • 8099",
     "method_type":"credit_card",
     "action":{
        "action":"NULL",
        "next":null
     }
  }
  ```

  ```json 422 theme={null}
  {
     "message":"El campo customer id es obligatorio. (y 6 errores m\u00e1s)",
     "code":10001,
     "code_name":"validation_error",
     "errors":{
        "customer_id":[
           "El campo customer id es obligatorio."
        ],
        "card_number":[
           "El campo card number es obligatorio."
        ],
        "expiration_year":[
           "El campo expiration year es obligatorio."
        ],
        "expiration_month":[
           "El campo expiration month es obligatorio."
        ],
        "ccv":[
           "El campo ccv es obligatorio."
        ],
        "holder_name":[
           "El campo holder name es obligatorio."
        ],
        "authorization":[
           "El campo authorization 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>

<RequestExample>
  ```bash cURL theme={null}
  curl https://cards.onepay.la/v1/cards \
    -X POST \
    -H "Authorization: Bearer pk_test_xxx" \
    -H "Content-Type: application/json" \
    -H "x-idempotency: card-001" \
    -d '{
      "card_number": "4242424242424242",
      "expiration_year": "28",
      "expiration_month": "12",
      "ccv": "123",
      "holder_name": "JUAN PEREZ",
      "customer_id": "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "authorization": true,
      "authentication": {
        "cavv": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
        "eci": "05",
        "ds_trans_id": "f25084f0-5b16-4c0a-ae5d-b24808571000",
        "version": "2.2.0",
        "status": "Y"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://cards.onepay.la/v1/cards', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_test_xxx',
      'Content-Type': 'application/json',
      'x-idempotency': 'card-001'
    },
    body: JSON.stringify({
      card_number: '4242424242424242',
      expiration_year: '28',
      expiration_month: '12',
      ccv: '123',
      holder_name: 'JUAN PEREZ',
      customer_id: '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
      authorization: true,
      authentication: {
        cavv: 'AAABBEg0VhI0VniQEjRWAAAAAAA=',
        eci: '05',
        ds_trans_id: 'f25084f0-5b16-4c0a-ae5d-b24808571000',
        version: '2.2.0',
        status: 'Y'
      }
    })
  });

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

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://cards.onepay.la/v1/cards',
      headers={
          'Authorization': 'Bearer pk_test_xxx',
          'Content-Type': 'application/json',
          'x-idempotency': 'card-001'
      },
      json={
          'card_number': '4242424242424242',
          'expiration_year': '28',
          'expiration_month': '12',
          'ccv': '123',
          'holder_name': 'JUAN PEREZ',
          'customer_id': '9dd4158b-0e45-42bc-b56f-a4c1f856814d',
          'authorization': True,
          'authentication': {
              'cavv': 'AAABBEg0VhI0VniQEjRWAAAAAAA=',
              'eci': '05',
              'ds_trans_id': 'f25084f0-5b16-4c0a-ae5d-b24808571000',
              'version': '2.2.0',
              'status': 'Y'
          }
      }
  )

  card = response.json()
  ```

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

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://cards.onepay.la/v1/cards",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer pk_test_xxx",
      "Content-Type: application/json",
      "x-idempotency: card-001"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "card_number" => "4242424242424242",
      "expiration_year" => "28",
      "expiration_month" => "12",
      "ccv" => "123",
      "holder_name" => "JUAN PEREZ",
      "customer_id" => "9dd4158b-0e45-42bc-b56f-a4c1f856814d",
      "authorization" => true,
      "authentication" => [
        "cavv" => "AAABBEg0VhI0VniQEjRWAAAAAAA=",
        "eci" => "05",
        "ds_trans_id" => "f25084f0-5b16-4c0a-ae5d-b24808571000",
        "version" => "2.2.0",
        "status" => "Y"
      ]
    ])
  ]);

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