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

Respuesta exitosa

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:

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

AnteriorTokenizaciónSiguienteEliminar token

Última actualización

¿Te fue útil?