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