Transacción

Introducción

API encargada de transaccionar con tarjetas, ya sea con datos de tarjeta o tokens de tarjetas previamente tokenizadas.

Endpoint Principal

Sandbox: POST https://api-test.payvalida.com/cards/v2/transactions

Producción: POST https://api.payvalida.com/cards/v2/transactions

Headers requeridos

Content-Type: application/json
Accept: application/json

---

Request

Ejemplo de body

{
  "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": "[email protected]",
  "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.

• 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.

---

Ejemplo en CURL

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": "[email protected]",
    "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

{
  "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": "[email protected]",
      "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:

{
  "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