Saltar al contenido principal
Esta guía muestra cómo llamar a una API de terceros con datos reales de tarjeta a través del Yuno PCI Proxy. Si aún no lo has leído, empieza con la Descripción general de PCI Proxy.

Requisitos

  • Tu public-api-key y tu private-secret-key del Yuno Dashboard.
  • Una tarjeta almacenada en Yuno y su vaulted_token. Consulta Inscribir método de pago.
  • La API de destino que quieres llamar, accesible por HTTPS en el puerto 443 y registrada en tu lista de destinos permitidos.
Solo del lado del servidorLas solicitudes al proxy destokenizan en reversa los datos de tarjeta y solo deben hacerse desde tu backend. Nunca expongas tu private-secret-key en código del lado del cliente.
1

Construye la solicitud de destino

Escribe la solicitud exactamente como la espera la API de destino (la misma estructura de cuerpo y los mismos encabezados), pero coloca expresiones de vaulted token donde van los datos de la tarjeta:
Los campos de tarjeta que puedes referenciar son number, expiration_month, expiration_year y holder_name, y se resuelven a los datos de la tarjeta (PAN) almacenados. Si la tarjeta se inscribió con un código de seguridad, también puedes referenciar security_code, dentro de una ventana limitada (ver más abajo). Si la tarjeta tiene un token de red, también puedes referenciar network_token_number (el DPAN), network_token_expiration_month y network_token_expiration_year. Y network_transaction_id se resuelve al NTID de la tarjeta, la referencia del esquema para su transacción original, requerida por muchos procesadores para transacciones iniciadas por el comercio. Todos los campos se pueden combinar en la misma solicitud: envía a tu procesador lo que necesite, ya sea PAN, DPAN + NTID o una combinación. Los tokens de proveedor no se resuelven, y los criptogramas tampoco: un criptograma se genera por transacción, así que si tu destino requiere uno, obtenlo de Generar criptograma de token de red justo antes del reenvío e incluye el valor directamente en el cuerpo. Solicítalo con include_network_token: false si tu organización no está certificada PCI: la respuesta que contiene solo el criptograma no incluye datos equivalentes al PAN, y la expresión network_token_number resuelve el DPAN por ti en el momento del reenvío.Las expresiones funcionan en el cuerpo de la solicitud y en los valores de los encabezados. Todo lo que no sea una expresión se reenvía sin cambios.
El código de seguridad expira: por defecto 3 horas después de la inscripciónsecurity_code es el único campo con una vigencia limitada. El código de seguridad nunca se almacena: se conserva brevemente después de que tu cliente lo ingresa, y Yuno deja de entregarlo cuando esa ventana se cierra. Referéncialo solo para un cobro que ocurra poco después de la inscripción.Cuando no está disponible (expiró o nunca se capturó), el reenvío falla con EXPRESSION_RESOLUTION_FAILED indicando security_code, y no se hace ninguna sustitución parcial. Tus expresiones de PAN no se ven afectadas: un código de seguridad expirado te cuesta solo ese campo.Si tu destino requiere el CVV fuera de esa ventana, tu cliente debe proporcionarlo y tú lo incluyes directamente en el cuerpo; el proxy lo reenvía sin almacenarlo. Transmitir un código de seguridad sin tokenizar mantiene esa solicitud dentro de tu alcance PCI.

Almacenar un código de seguridad

Una tarjeta solo tiene un código de seguridad para inyectar si se proporcionó cuando se inscribió. Envíalo como card.security_code en Inscribir método de pago:
Si inscribes la tarjeta sin él, la tarjeta sigue siendo utilizable para todas las demás expresiones; solo security_code no estará disponible.

Comprobar cuánto queda de la ventana

Lee card_data.security_code_expires_in desde Consultar método de pago inscrito:
La respuesta de inscripción no incluye security_code_expires_in. Léelo desde el endpoint del método de pago indicado arriba cuando necesites saber en qué punto estás antes de construir un reenvío.
2

Envíala a través del proxy

Envía la solicitud a https://api.y.uno/v1/pci-proxy/forward con el destino en el encabezado yuno-proxy-destination-url:
El método HTTP que uses es el método que recibe el destino. Los encabezados que establezcas para el destino (como Authorization arriba) pasan sin cambios; los encabezados de credenciales propios de Yuno y todos los encabezados yuno-* se eliminan antes de reenviar.El encabezado yuno-account-id es opcional: inclúyelo cuando necesites limitar la solicitud a una cuenta específica. Como todos los encabezados yuno-*, se elimina antes de reenviar y nunca llega al destino. Limita qué destinos de la lista de permitidos están autorizados para la solicitud; no afecta la resolución de tokens, ya que los vaulted tokens siempre están limitados a tu organización.Este es un encabezado distinto de X-account-code, que usas para administrar destinos asociados a una cuenta en la lista de destinos permitidos; ambos llevan el mismo account_id. Un destino registrado con un account_id necesita esa cuenta también en el reenvío: incluye yuno-account-id o recibirás 403 DESTINATION_NOT_ALLOWED, igual que con un host no registrado.Coloca la URL de destino completa, incluyendo su ruta y cualquier query string, en yuno-proxy-destination-url (por ejemplo https://api.example-processor.com/charges/ch_123/capture?expand=true). No agregues una ruta ni un query string a la solicitud /v1/pci-proxy/forward en sí; un query string en la solicitud al proxy se rechaza, para que los datos del comercio nunca se registren en logs.
3

Lee la respuesta

El código de estado, los encabezados y el cuerpo del destino se te devuelven sin cambios, salvo que cualquier número de tarjeta que el destino devuelva se redacta primero (consulta Datos de tarjeta en las respuestas más abajo). Las redirecciones no se siguen: un 3xx del destino se te devuelve tal cual, para que tú decidas si seguirlo. El proxy agrega encabezados de diagnóstico:
4

Maneja los errores

Los errores producidos por el propio proxy usan el formato de error estándar de Yuno y nunca incluyen el encabezado yuno-proxy-destination-status:
Un 401 se devuelve antes de que tu solicitud llegue al proxy, por lo que no incluye el encabezado yuno-proxy-request-id; todas las demás respuestas sí lo incluyen.Cualquier 4xx/5xx acompañado de yuno-proxy-destination-status es un error propio del destino, que se te pasa para que lo manejes como si lo hubieras llamado directamente.

Tipos de contenido

El proxy es agnóstico al tipo de contenido. Reenvía el cuerpo textualmente, sin analizarlo ni convertirlo a JSON. La resolución de expresiones es una sustitución de texto sobre los bytes sin procesar del cuerpo, así que una expresión vaulted_token se reemplaza dondequiera que aparezca: JSON, XML, SOAP o pares clave-valor de formulario. Coloca las expresiones dentro de tu payload y envía el Content-Type que tu destino espera. JSON se muestra arriba. Los ejemplos siguientes cubren los otros formatos comunes. XML
SOAP: un envelope XML más el encabezado SOAPAction propio del destino, reenviado sin cambios:
Pares clave-valor de formulario (application/x-www-form-urlencoded):
Caracteres especiales en holder_nameComo la sustitución es literal, un holder_name que contenga marcado o caracteres delimitadores puede romper la estructura del payload en el destino:
  • XML / SOAP: un nombre con &, < o > (por ejemplo Doe & Sons) puede romper el formato correcto del documento. Los campos number, expiration_month y expiration_year son solo dígitos, por lo que no se ven afectados: el riesgo se limita a holder_name.
  • Pares clave-valor de formulario: un nombre con &, = o espacios puede romper la estructura clave/valor. Envía holder_name codificado como URL, o usa un payload JSON/XML si el nombre del titular puede contener caracteres especiales.

Datos de tarjeta en las respuestas

Si un destino devuelve un número de tarjeta en su respuesta, el proxy lo redacta antes de devolvértela, conservando solo los últimos cuatro dígitos, para que los números de tarjeta sin procesar nunca lleguen a tus sistemas. El número de redacciones se informa en el encabezado de respuesta yuno-proxy-response-redactions:
Un yuno-proxy-response-redactions distinto de cero es una señal de que tu destino está devolviendo datos de tarjeta que no deberías recibir. La redacción es el comportamiento por defecto. Yuno se puede configurar opcionalmente, como un ajuste a nivel de servicio y no por cuenta, para rechazar en su lugar cualquier respuesta que contenga datos de tarjeta con 502 RESPONSE_BLOCKED.

Autenticación en el destino

Una solicitud al proxy lleva dos conjuntos independientes de credenciales:
  • Tus credenciales de Yuno (public-api-key / private-secret-key) te autentican ante el proxy. Yuno las consume y nunca se reenvían.
  • Las credenciales propias del destino son las que esa API de terceros espere. Inclúyelas en la solicitud y se reenvían sin cambios: Yuno solo elimina sus propios encabezados.
Envía el encabezado de autenticación que requiera tu destino: no se limita a Authorization. El nombre del encabezado lo define la API del proveedor del destino, no Yuno; tómalo de la documentación de ese proveedor. Qué reenvía Yuno y qué elimina: Nombres comunes de encabezados de autenticación por proveedor (ejemplos: revisa siempre la documentación del destino):

Destinos con firma (firma de solicitudes HMAC)

Algunos destinos requieren que cada solicitud esté firmada (HMAC) sobre el cuerpo de la solicitud. No puedes calcular esa firma por adelantado: tendría que calcularse sobre el cuerpo resuelto, el que contiene el número de tarjeta real, que solo existe dentro del entorno seguro de Yuno. En su lugar, envía tus credenciales de firma en la propia solicitud y el proxy firma por ti, después de resolver tus expresiones: Los demás identificadores del destino son encabezados de destino normales que envías tú mismo, reenviados textualmente como siempre. Para dLocal (DLOCAL_HMAC):
Cada valor de yuno-proxy-auth identifica un esquema de firma completo y fijo (qué se firma, cómo y qué encabezados produce el proxy) que coincide con la especificación oficial de autenticación de ese destino. DLOCAL_HMAC implementa el esquema de firma de solicitudes de dLocal: La firma se calcula sobre los bytes exactos del cuerpo que recibe el destino, después de que tus expresiones {{vaulted_token…}} se resuelven, que es precisamente la razón por la que el proxy debe calcularla. Lo que recibe el destino:
No envíes X-Date ni Authorization tú mismo en un destino con firma: los valores del proxy los reemplazan (de todos modos, el destino rechazaría una firma que calculaste sobre un cuerpo que aún contiene los marcadores {{vaulted_token…}}). Todos tus demás encabezados pasan sin cambios. Un valor yuno-proxy-auth desconocido, un yuno-proxy-auth-secret-key ausente o una solicitud DLOCAL_HMAC sin los encabezados X-Login o X-Trans-Key se rechaza con 400 INVALID_REQUEST antes de contactar al destino. Un 401 del propio destino (credenciales incorrectas) llega como una respuesta del destino, con yuno-proxy-destination-status: 401.
El TLS mutuo se configura por destino, no en líneaLos destinos que requieren TLS mutuo (un certificado de cliente) no se admiten en línea: el certificado lo presenta Yuno durante el handshake TLS, no se envía en tu solicitud. En su lugar, regístralo una vez en el destino; consulta Autenticación del destino.

Tiempos de espera

Por defecto, el proxy espera hasta 30 segundos al destino. Modifícalo con el encabezado yuno-proxy-timeout (segundos, máximo 120):

Pruebas en sandbox

Usa https://api-sandbox.y.uno/v1/pci-proxy/forward con tus credenciales de sandbox y valores de vaulted_token de sandbox. Los tokens de sandbox se resuelven a números de tarjeta de prueba, así que puedes apuntar el proxy al sandbox de tu propio destino de forma segura.
Verifica tu integraciónRevisa yuno-proxy-replacements en la respuesta mientras integras: confirma que el proxy encontró y reemplazó tus expresiones antes de reenviar.