# Transacción

![](/files/-MQinRbGBBp1ultGbv4p)

{% hint style="success" %}
**Producción:** [**https://api.payvalida.com/v4/merchant/transaction**](https://api.payvalida.com/v4/merchant/transaction)
{% endhint %}

{% hint style="success" %}
**Sandbox:** [**https://api-test.payvalida.com/v4/merchant/transaction**](https://api-test.payvalida.com/v4/merchant/transaction)
{% endhint %}

### Parámetros en formato JSON en el cuerpo de la petición POST.

{% tabs %}
{% tab title="Parámetros" %}

<table data-full-width="true"><thead><tr><th>Campo</th><th>Requerido</th><th>Tipo </th><th>Descripción     </th></tr></thead><tbody><tr><td>merchantId</td><td>sí</td><td>Alfanumérico</td><td> Nombre identificador del comercio.</td></tr><tr><td>order</td><td>sí</td><td>Alfanumérico</td><td>Identificación de la orden generada por el comercio. Es el número asignado por el comercio, no el número asignado por Payvalida.</td></tr><tr><td>checksum</td><td>sí</td><td>Alfanumérico</td><td>Checksum formado de la siguiente manera: SHA512(merchantId + order + fixed_hash)</td></tr><tr><td>cvv</td><td>sí</td><td>numérico</td><td>Código de seguridad de la tarjeta de crédito/débito. <strong>Este parámetro debe enviarse la primera vez que se hace una transacción con la tarjeta de crédito/débito, y es opcional enviarlo en caso de usar un token.</strong> Si se recibe el parámetro, se usará; en caso contrario se hará la transacción como recurrente.</td></tr><tr><td>fechaExpiracion</td><td>sí</td><td>Alfanumérico</td><td>Fecha de expiración de la tarjeta de crédito/débito en formato <strong>MM/AA. Este parámetro es requerido si la transacción no es mediante token; e ignorado si la transacción se hace con un token,</strong> en cuyo caso se usará la información almacenada correspondiente a la tarjeta del token.</td></tr><tr><td>cuotas</td><td>sí</td><td>numérico</td><td>Cantidad de cuotas en las que se realizará el pago. Este campo debe ser mayor o igual a 1.</td></tr><tr><td>tipoDI</td><td>sí</td><td>Alfabético</td><td><a href="https://docs.payvalida.com/api-tarjeta/v/master/tipos-de-identificacion">Tipo de documento de identificación</a> de la persona que realiza la transacción.</td></tr><tr><td>di</td><td>sí</td><td>Alfanumérico</td><td>Número de documento de identificación de la persona que realiza la transacción.</td></tr><tr><td>token</td><td>no</td><td>Alfanumérico</td><td>Token de una tarjeta de crédito/débito. Usado cuando se quiere hacer uso de una tarjeta de crédito/débito previamente tokenizada (parámetro «tokenizar» de este mismo servicio).</td></tr><tr><td>numeroTarjeta</td><td>no</td><td>Alfanumérico</td><td>Número de la tarjeta de crédito/débito. <strong>Este parámetro es requerido si la transacción no es mediante token; e ignorado si la transacción se hace con un token,</strong> en cuyo caso se usará la información almacenada correspondiente a la tarjeta del token.</td></tr><tr><td>nombreTitular</td><td>no</td><td>Alfanumérico</td><td>Nombre del titular de la tarjeta de crédito/débito sin apellidos. Este parámetro es requerido si la transacción no es mediante token; e ignorado si la transacción se hace con un token, en cuyo caso se usará la información almacenada correspondiente a la tarjeta del token.</td></tr><tr><td>apellidosTitular</td><td>no</td><td>Alfanumérico</td><td>Apellidos del titular de la tarjeta de crédito/débito. Este parámetro es requerido si la transacción no es mediante token; e ignorado si la transacción se hace con un token, en cuyo caso se usará la información almacenada correspondiente a la tarjeta del token.</td></tr><tr><td>franquicia</td><td>no</td><td>Alfabético</td><td><a href="/pages/-MQjFT2QwazzQa2SGgq5">Define la franquicia de la tarjeta de crédito/débito</a>. <strong>Si se omite este campo y la transacción no es con token, se infiere la franquicia del número de la TC. Este campo es ignorado si la transacción se hace con un token</strong>, en cuyo caso se usará la información almacenada correspondiente a la tarjeta del token.</td></tr><tr><td>tokenizar</td><td>no</td><td>boolean</td><td>Indica si se quiere tokenizar la tarjeta de crédito/débito. Este parámetro es ignorado si la transacción se hace con un token.</td></tr><tr><td>correo</td><td>sí</td><td>Alfanumérico</td><td>Dirección de correo electrónico de la persona que realiza la transacción.</td></tr><tr><td>telefono</td><td>sí</td><td>Alfanumérico</td><td>Número telefónico de la persona que realiza la transacción.</td></tr><tr><td>ip</td><td>si</td><td>Alfanumérico</td><td>Dirección IP del dispositivo origen de la transacción, del usuario final.</td></tr><tr><td>line1</td><td>sí</td><td>Alfanumérico</td><td>Linea 1 asociada a la dirección de facturación del usuario.</td></tr><tr><td>line2</td><td>sí</td><td>Alfanumérico</td><td>Linea 2 asociada a la dirección de facturación del usuario.</td></tr><tr><td>line3</td><td>no</td><td>Alfanumérico</td><td>Linea 3 asociada a la dirección de facturación del usuario.</td></tr><tr><td>country</td><td>sí</td><td>Alfanumérico</td><td>Pais del usuario.</td></tr><tr><td>city</td><td>sí</td><td>Alfanumérico</td><td>Ciudad del usuario.</td></tr><tr><td>state</td><td>sí</td><td>Alfanumérico</td><td>Estado o departamento del usuario</td></tr><tr><td>postCode</td><td>sí</td><td>Alfanumérico</td><td>Código postal de usuario.</td></tr><tr><td>xid</td><td>no (solo para transacciones autenticadas previamente con 3DS)</td><td>Alfanumérico</td><td>Identificador único generado por el banco emisor de la tarjeta para representar la solicitud de autenticación 3D Secure. Este campo debe ser igual a 36. Más información<a href="https://www.emvco.com/emv-technologies/3-d-secure/"> https://www.emvco.com/emv-technologies/3-d-secure/</a></td></tr><tr><td>eci</td><td>no (solo para transacciones autenticadas previamente con 3D Secure)</td><td>Númerico</td><td><p>ECI (Electronic Commerce Indicator) Código de dos dígitos que devuelven las redes de procesamiento de tarjetas de crédito y los bancos emisores para notificar a un comerciante de comercio electrónico la autenticación del titular de la tarjeta y la situación del banco emisor del titular de la tarjeta en el marco de 3D Secure. Cada red de tarjetas de crédito tiene un tipo específico de marco ECI utilizado. Más información<a href="https://www.emvco.com/emv-technologies/3-d-secure/"> https://www.emvco.com/emv-technologies/3-d-secure/</a></p><p><br></p></td></tr><tr><td>cavv</td><td>no (solo para transacciones autenticadas previamente con 3D Secure)</td><td>Alfanumérico</td><td><p>CAVV(Cardholder Authentication Verification Value) Criptograma único generado para cada transacción autenticada 3D Secure y vinculado al importe de la transacción y al beneficiario. El CAVV se transmite al comerciante y se envía junto con la solicitud de autorización para demostrar que se ha producido la autenticación. Más información<a href="https://www.emvco.com/emv-technologies/3-d-secure/"> https://www.emvco.com/emv-technologies/3-d-secure/</a></p><p><br></p></td></tr><tr><td>protocolVersion</td><td>no (solo para transacciones autenticadas previamente con 3D Secure)</td><td>Númerico</td><td>Versión del protocolo 3D Secure que acepta el emisor. Más información<a href="https://www.emvco.com/emv-technologies/3-d-secure/"> https://www.emvco.com/emv-technologies/3-d-secure/</a></td></tr></tbody></table>
{% endtab %}

{% tab title="Request (sin tokenizar)" %}

```json5
// Transacción con tarjeta de crédito. No se tokenizará.

{
  "merchantId": "mi_comercio",
  "order": "1234567890",
  "checksum": "90037d4ae7d310c1c4c50ce630c54af850587533a900099cde381ac68aa8af1cc959b9820e77a48fb403c460a8630729bc37e2a9d47be9e3e846982fa7c56de0",
  "valor": 70500,
  "cuotas": 1,
  "tipoDI": "CC",
  "di": "1234567890",
  "cvv": 123,
  "numeroTarjeta": "53123456789083",
  "fechaExpiracion": "12/21",
  "nombreTitular": "Juan",
  "apellidosTitular": "Pérez",
  "correo": "email@email.com",
  "ip": "1.1.1.1"
}
```

{% endtab %}

{% tab title="Request (tokenizando)" %}

```json5
// Transacción con tarjeta de crédito. Se tokenizará.

{
  "merchantId": "mi_comercio",
  "order": "1234567890",
  "checksum": "90037d4ae7d310c1c4c50ce630c54af850587533a900099cde381ac68aa8af1cc959b9820e77a48fb403c460a8630729bc37e2a9d47be9e3e846982fa7c56de0",
  "valor": 70500,
  "cuotas": 1,
  "tipoDI": "CC",
  "di": "1234567890",
  "cvv": 123,
  "numeroTarjeta": "53123456789083",
  "fechaExpiracion": "12/21",
  "nombreTitular": "Juan",
  "apellidosTitular": "Pérez",
  "correo": "email@email.com",
  "tokenizar": true,
  "ip": "1.1.1.1"
}
```

{% endtab %}

{% tab title="Request (con token)" %}

```json5
// Transacción con token. El token fue originado de una transacción con TC previamente tokenizada.

{
  "merchantId": "mi_comercio",
  "order": "1234567890",
  "checksum": "90037d4ae7d310c1c4c50ce630c54af850587533a900099cde381ac68aa8af1cc959b9820e77a48fb403c460a8630729bc37e2a9d47be9e3e846982fa7c56de0",
  "valor": 70500,
  "cuotas": 1,
  "tipoDI": "CC",
  "di": "1234567890",
  "cvv": 123, // Requerido para franquicias diferentes a Mastercard
  "token": "12345678901234",
  "correo": "email@email.com",
  "ip": "1.1.1.1"
}
```

{% endtab %}

{% tab title="Request (validaciones adicionales)" %}

```json5
/* 
    Transacción con validaciones adicionales. Tener en cuenta si 
    se desea tokenizar o no, enviando el campo tokenizar.
*/
{
  "merchantId": "mi_comercio",
  "order": "1234567890",
  "checksum": "90037d4ae7d310c1c4c50ce630c54af850587533a900099cde381ac68aa8af1cc959b9820e77a48fb403c460a8630729bc37e2a9d47be9e3e846982fa7c56de0",
  "valor": 70500,
  "cuotas": 1,
  "tipoDI": "CC",
  "di": "1234567890",
  "cvv": 123,
  "numeroTarjeta": "53123456789083",
  "fechaExpiracion": "12/21",
  "nombreTitular": "Juan",
  "apellidosTitular": "Pérez",
  "correo":"mail@gmail.com",
  "telefono":"3002222222",
  "line1":"cll 65 # 28-97",
  "line2":"Apto segundo piso",
  "line3": "Bogota",
  "country": "Colombia",
  "city": "Bogota",
  "state":"Cundinamarca",
  "postCode": "050001",
  "ip":"1.1.1.1"
}
```

{% endtab %}

{% tab title="Request (con campos 3D Secure) " %}

```json
/*
Transacción con campos 3D secure. Tener en cuenta si
se desea tokenizar o no, enviando el campo tokenizar.
*/

{
"merchantId": "mi_comercio",
"order": "1234567890",
"checksum": "90037d4ae7d310c1c4c50ce630c54af850587533a900099cde381ac68aa8af1cc959b9820e77a48fb403c460a8630729bc37e2a9d47be9e3e846982fa7c56de0",
"valor": 70500,
"cuotas": 1,
"tipoDI": "CC",
"di": "1234567890",
"cvv": 123,
"numeroTarjeta": "53123456789083",
"fechaExpiracion": "12/21",
"nombreTitular": "Juan",
"apellidosTitular": "Pérez",
"correo": "email@email.com",
"ip": "1.1.1.1",
"xid": "1235s9dr-d1b3-vc80-19cf-wc41n2raP9b9",
"eci" :"02",
"cavv": "kCP0RU89KPTS18DlicJkBcBWHEu",
"protocolVersion": "2.1.0"
}

```

{% endtab %}

{% tab title="Response (ejemplo)" %}

```json5
{
  "result": "200",
  "data": {
    "token": "5388846254108783",
    "order": {
      "amount": "44000.00",
      "date": "2023-04-30",
      "tax": "0",
      "total": "44000.00",
      "number": "2405537"
    },
    "transaction": {
      "date": "2023-05-02",
      "responseCode": "APROBADA",
      "installments": "1",
      "accountType": "CREDITO",
      "cus": "2023-05-02_112233",
      "invoiceNumber": "112233",
      "franchise": "MasterCard",
      "response": "Aprobado",
      "cardNumber": "************8783",
      "numAprobacion": "112233",
      "idTransaccionAutorizador": "332211"
    },
    "commerce": {
      "url": "https://www.payvalida.com",
      "terminal": "abcdef",
      "name": "VALIDDA S.A.S",
      "code": "73",
      "email": "info@payvalida.com",
      "net": "REDEBAN"
    },
    "user": {}
  },
  "error": ""
}
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Advertencia: El contenido del parámetro token tiene prioridad sobre el resto de parámetros referentes a datos de tarjeta de crédito/débito; en caso que se envíe una transacción con token, los parámetros no asociados a token (franquicia, número de tarjeta, nombre del titular, apellido del titular) serán ignorados.
{% endhint %}

{% hint style="success" %}
El código result == 200 indica que la transacción fue enviada al procesador del banco, pero no necesariamente indica que fue aprobada. Para verificar la correcta transacción se debe verificar el campo **data.transaction.responseCode == "APROBADA"** (ver ejemplo de Response arriba). En caso de que se tokenice, el token se obtiene de **data.token** (ver ejemplo de Response arriba). En caso de error recibirá la descripción del error en el campo **error**.
{% endhint %}

&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payvalida.com/api-tarjeta/master/transaccion/transaccion-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.