> For the complete documentation index, see [llms.txt](https://docs.payvalida.com/api-tarjeta/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payvalida.com/api-tarjeta/master/transaccion/transaccion.md). # Transacción ### Introducción API encargada de transaccionar con tarjetas, ya sea con datos de tarjeta o tokens de tarjetas previamente tokenizadas. ### Endpoint Principal {% hint style="success" %} **Sandbox**: POST `https://api-test.payvalida.com/cards/v2/transactions` {% endhint %} {% hint style="success" %} **Producción**: POST `https://api.payvalida.com/cards/v2/transactions` {% endhint %} ### Headers requeridos ```http Content-Type: application/json Accept: application/json ``` *** ### Request #### Ejemplo de body ```json { "merchantId": "payvalida_commerce", "orderAuthorizationId": "order123456", "checksum": "a1b2c3...", "token": "jwt-token", "cardNumber": "4111111111111111", "expirationMonth": "12", "expirationYear": "26", "cvv": "123", "installments": 1, "name": "Juan", "lastname": "Pérez", "typeDI": "CC", "di": "123456789", "email": "juan.perez@example.com", "phoneNumber": "3001234567", "ip": "190.1.1.1", "billAddrLine1": "Cra 10 # 20-30", "billAddrLine2": "Apto 301", "billAddrLine3": "", "billAddrCity": "Bogotá", "billAddrState": "Cundinamarca", "billAddrCountry": "CO", "billAddrPostCode": "110111", "franchise": "20", "eci": "05", "xid": "e8b59b443f2d46e89fd68e5a0a7f0427", "cavv": "MTIzNDU2Nzg5MDEyMzQ1Ng==", "protocolVersion": "2.1.0", "withCvv": true, "recurrent": false, "firstRecurrentPurchase": false, "kountSessionId": "6BC9872CDE1541AABB89B67925A472C2", "dsTransID": "3DSTXID123", "threeDsStatus": "Y", "requestOrigin": "API", "cardToken": "tok_abcdef" } ``` | Campo | Tipo | Requerido | Descripción | | ------------------------ | ------- | --------- | -------------------------------------------------------------------------- | | `merchantId` | string | Sí | Identificador del comercio asignado por Payválida. | | `orderAuthorizationId` | string | Sí | Identificador único de la orden asignado por el comercio. | | `checksum` | string | Sí | SHA512(merchantId + order + fixed\_hash). | | `cardNumber` | string | Cond. | Número de la tarjeta. Requerido si no se usa `cardToken`. | | `expirationMonth` | string | Cond. | Mes de expiración de la tarjeta (MM). | | `expirationYear` | string | Cond. | Año de expiración de la tarjeta (YY). | | `cvv` | string | Cond. | Código de seguridad. Requerido si se indica `withCvv: true`. | | `installments` | int | Sí | Cantidad de cuotas del pago. | | `token` | string | No | Token de tarjeta previamente generado. | | `cardToken` | string | No | Token interno de tarjeta de Payválida. | | `name` | string | No | Nombre del titular de la tarjeta. | | `lastname` | string | No | Apellidos del titular de la tarjeta. | | `typeDI` | string | Sí | Tipo de documento (CC, CE, NIT, etc.). | | `di` | string | Sí | Número de documento de identidad. | | `email` | string | Sí | Correo electrónico del usuario. | | `phoneNumber` | string | Sí | Número telefónico del usuario. | | `ip` | string | Sí | Dirección IP desde donde se origina la transacción. | | `billAddrLine1` | string | Sí | Línea 1 de la dirección del usuario. | | `billAddrLine2` | string | Sí | Línea 2 de la dirección del usuario. | | `billAddrLine3` | string | No | Línea 3 de la dirección del usuario. | | `billAddrCity` | string | Sí | Ciudad del usuario. | | `billAddrState` | string | Sí | Departamento del usuario. | | `billAddrCountry` | string | Sí | País del usuario. | | `billAddrPostCode` | string | Sí | Código postal del usuario. | | `franchise` | string | No | Franquicia de la tarjeta (20, 30, 40, 50). | | `eci` | string | No | Código ECI usado en autenticación 3DS. | | `xid` | string | No | Identificador de autenticación 3DS (36 caracteres). | | `cavv` | string | No | Valor de autenticación del titular (CAVV). | | `protocolVersion` | string | No | Versión del protocolo 3DS (ej. 2.1.0). | | `withCvv` | boolean | No | Indica si la transacción incluye CVV. | | `recurrent` | boolean | No | Indica si la transacción es recurrente. | | `firstRecurrentPurchase` | boolean | No | Indica si es la primera compra recurrente. | | `kountSessionId` | string | No | ID de sesión de Kount (UUIDv4 sin guiones y en mayúsculas, 32 caracteres). | | `dsTransID` | string | No | Identificador de transacción 3DS. | | `threeDsStatus` | string | No | Estado de autenticación 3DS. | | `requestOrigin` | string | Sí | Siempre debe enviarse como `API`. | | `transactionType` | string | No | MIT o CIT, por defecto MIT. | | `ThreeDsAuthMethod` | string | No | Numérico longitud 2: 01, 02, 03, etc. | {% hint style="info" %} * Los campos referentes a datos del cliente y facturación son necesarios para cumplir con normativas de seguridad y antifraude, aunque no todos son obligatorios para todas las transacciones. * Los campos referentes a los datos de tarjeta son necesarios cuando no se desea transaccionar con un token de tarjeta. * El endpoint implementa validaciones antifraude y puede rechazar transacciones por motivos de seguridad. * El ruteo a diferentes proveedores es automático según la configuración del comercio y la franquicia. * Los mensajes de error pueden variar según el proveedor y el motivo del rechazo. {% endhint %} *** ### Ejemplo en CURL ```bash curl -X POST "https://api-test.payvalida.com/cards/v2/transactions" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "merchantId": "payvalida_commerce", "orderAuthorizationId": "order123456", "checksum": "a1b2c3...", "cardNumber": "4111111111111111", "expirationMonth": "12", "expirationYear": "26", "cvv": "123", "installments": 1, "name": "Juan", "lastname": "Pérez", "typeDI": "CC", "di": "123456789", "email": "juan.perez@example.com", "phoneNumber": "3001234567", "ip": "190.1.1.1", "billAddrLine1": "Cra 10 # 20-30", "billAddrLine2": "Apto 301", "billAddrCity": "Bogotá", "billAddrState": "Cundinamarca", "billAddrCountry": "CO", "billAddrPostCode": "110111", "franchise": "20", "requestOrigin": "API" }' ``` *** ### Respuesta exitosa ```json { "CODE": "0000", "DESC": "OK", "DATA": { "order": { "amount": "75900.0", "date": "2025-07-28T17:06:01-05:00", "vat": "12118.49", "total": "75900.0", "reference": "90974601634", "currency": "COP" }, "transaction": { "date": "2025-07-28T17:06:01-05:00", "responseCode": "APPROVED", "installments": "1", "accountType": "CREDIT", "cus": "2025-07-28T17:06:01-05:00_1753740359986713", "invoiceNumber": "530197", "franchise": "VISA", "response": "APPROVED", "cardNumber": "491626******4071", "approvalNumber": "530197", "authorizerTransactionId": "281706902795", "address": { "billAddrLine1": "Calle 40A #42-35", "billAddrLine2": "Apartamento", "billAddrLine3": "Rionegro", "billAddrCity": "Rionegro", "billAddrCountry": "Colombia", "billAddrState": "Antioquia", "billAddrPostCode": "110111" } }, "merchant": { "url": "https://pagos.antatel.com/", "id": "antioqueadetelecomunicaciones", "name": "ANTA (COL)", "code": "32450", "email": "contacto@antatel.co", "net": "CREDIBANCO" }, "user": { "documentType": "CC", "document": "1047491420", "name": "Vladimir Bustos", "transactionIp": "186.97.165.10" } } } ``` #### Campos de la respuesta | Campo | Tipo | Descripción | | ------------------------------------- | ------ | -------------------------------------- | | `order.amount` | string | Monto total de la orden. | | `order.vat` | string | Valor del IVA calculado. | | `order.total` | string | Total a pagar. | | `order.date` | string | Fecha de la orden. | | `order.reference` | string | Referencia de la orden. | | `order.currency` | string | Moneda de la orden. | | `transaction.date` | string | Fecha de la transacción. | | `transaction.responseCode` | string | Código de respuesta de la transacción. | | `transaction.response` | string | Texto de respuesta de la transacción. | | `transaction.installments` | string | Número de cuotas. | | `transaction.accountType` | string | Tipo de cuenta usada. | | `transaction.cus` | string | Código único de seguimiento. | | `transaction.invoiceNumber` | string | Número de factura. | | `transaction.franchise` | string | Franquicia de la tarjeta. | | `transaction.cardNumber` | string | Número de tarjeta enmascarado. | | `transaction.approvalNumber` | string | Número de aprobación. | | `transaction.authorizerTransactionId` | string | ID del autorizador. | | `transaction.address.*` | string | Información de dirección del usuario. | | `merchant.id` | string | ID del comercio. | | `merchant.name` | string | Nombre del comercio. | | `merchant.code` | string | Código del comercio. | | `merchant.url` | string | URL del comercio. | | `merchant.email` | string | Correo del comercio. | | `merchant.net` | string | Red procesadora. | | `user.documentType` | string | Tipo de documento del usuario. | | `user.document` | string | Número de documento del usuario. | | `user.name` | string | Nombre del usuario. | | `user.transactionIp` | string | IP de origen de la transacción. | *** ### Posibles errores Todos los errores comparten la siguiente estructura de respuesta: ```json { "CODE": "0001", "DESC": "invalid request", "DATA": {same as ok response ...} } ``` **Códigos de error** | Nombre del Error | CODE | DESC | HTTP Code | | ---------------------------- | ---- | ---------------------------------------------------------- | --------- | | `InvalidRequest` | 0001 | invalid request | 400 | | `InternalError` | 0002 | internal error | 500 | | `PaymentAuthorizationFailed` | 0003 | payment authorization failed | 403 | | `RoutingNotImplemented` | 0004 | routing for the received payment not supported | 502 | | `AntifraudFailed` | 0005 | it is not possible to continue the processing payment | 403 | | `OrderLocked` | 0006 | it is not possible to process the request, try again later | 409 | | `CashinConsultFailed` | 0007 | the reference is not registered or is invalid | 400 | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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.md?ask= ``` 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.