Requisitos
- Tu
public-api-keyy tuprivate-secret-keydel 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.
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 Si inscribes la tarjeta sin él, la tarjeta sigue siendo utilizable para todas las demás expresiones; solo
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.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 comocard.security_code en Inscribir método de pago:security_code no estará disponible.Comprobar cuánto queda de la ventana
Leecard_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 El método HTTP que uses es el método que recibe el destino. Los encabezados que establezcas para el destino (como
https://api.y.uno/v1/pci-proxy/forward con el destino en el encabezado yuno-proxy-destination-url: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ónvaulted_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
SOAPAction propio del destino, reenviado sin cambios:
application/x-www-form-urlencoded):
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 respuestayuno-proxy-response-redactions:
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.
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):
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:
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 encabezadoyuno-proxy-timeout (segundos, máximo 120):
Pruebas en sandbox
Usahttps://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.