Procesador de Pagos Externo: Usando una pasarela de pago personalizada
soporte, ws.webtv, store, tienda, gestion, procesador, pagos, externo, pasarela, pago
Para algunos clientes, los métodos de pago integrados (Banco y PayPal) no son suficientes y ellos pueden necesitar usar una pasarela de pagos específica para aceptar pagos con tarjeta de crédito en la WebTV. Para permitir esto, hemos implementado un método simple para aceptar pagos a través de un script procesador de pagos externo a la WebTV.
¿Cómo funciona?
1. Ud. desarrolla/implementa la pasarela de pagos deseada (el script ptocesador de pagos...).
2. Ud. habilita el método de pago "Procesador Pagos Ext." en la configuración de la extensión Tienda y suministra la URL del script procesador de pagos.
3. Cuando los usuarios hagan click en el botón "Pagar pedido", ellos serán redireccionados a la URL del procesador de pagos (su script) y una vez que termine de procesar el pago, Ud. redirige al usuario de vuelta a la WebTV para procesar el pedido.
¿Cómo el procesador de pagos obtiene los detalles del pedido?
Cuando la WebTV redirige al usuario al procesador de pagos, enviará los datos requeridos como variables GET (añadidas a la URL del procesador del pagos). Los datos también incluirán una firma de validación (hash). Más información a continuación.
¿Cómo la WebTV "sabe" qué pedido fue pagado a través del procesador de pagos?
El script procesador de pagos, cuando redirija al usuario de vuelta a la WebTV, también debe enviar los datos apropiados como variables GET. Los datos devueltos deben incluir la firma de validación (hash) correspondiente. Más información a continuación.
Ir a Tienda > Configuración (pestaña General), baje hasta la sección "Ventas" y marque "Procesador Pagos Ext." en "Métodos de Pago Permitidos".
Luego, guarde...
Vaya a la pestaña "Procesador Pagos Ext.".
Suministre la información requerida:
• URL Procesador de pagos: La URL del script procesador de pagos (debe ser una URL absoluta).
• Clave de firma (key): Introduzca la clave (string) que será utilizada para generar la firma de validación (hash). Esta clave también deberá utilizarse en su script procesador de pagos para generar las firmas correspondientes.
• Habilitar Pagos Periódicos: (Para suscripciones) habilite esta opción si su script procesador de pagos soporta esta funcionalidad - Funcionalidad disponible desde WS.WebTV 1.7.5+.
Descargue un ejemplo de código de procesador de pagos en PHP:
Ejemplo « sin » procesamiento de pagos periódicos
Ejemplo « con » procesamiento de pagos periódicos (actualizado para contemplar el caso de suscripciones con período de prueba/trailer)
La WebTV añadirá los detalles del pago a la URL del script procesador de pagos como variables GET. Ejemplo:
http://.../procesador_de_pagos.php?id_gateway={id_pasarela_de_pago}&id_order={id_pedido}&amount={importe}¤cy_code={código_de_moneda}&order_number={número_de_pedido}&signature={firma}&id_user={id_de_usuario}
• id_gateway -> ID de la pasartela de pagos en la WebTV
• id_order -> ID del pedido a pagar
IMPORTANTE: Necesitará id_gateway y id_order cuando retorne a la WebTV.
• amount -> Importe a pagar (decimal, por ejemplo: 10.5, 5, ...)
• currency_code -> Código de moneda del pedido (USD, EUR, etc.)
• signature -> Una firma (hash) para validar los datos. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Información adicional:
• id_user -> ID del Usuario (comprador) en la WebTV
Validando los datos
Antes de procesar el pago, debe validar los datos usando la firma. Para ello, debe generar la firma de la misma manera que lo hace la WebTV, y compararla con la firma recibida.
Ejemplo en PHP:
$key = "la clave de firma secreta";
$data = array(
"id_gateway" => (string)$id_gateway,
"id_order" => (string)$id_order,
"amount" => (string)$amount,
"currency_code" => $currency_code,
"order_number" => (string)$order_number
);
$signature = base64_encode(hash_hmac('sha256', json_encode($data), $key, true));
Una vez que ha generado la firma, debe compararla con la firma enviada por la WebTV: Si coinciden, puede continuar.
Cuando realice pruebas durante el desarrollo... si las firmas no coinciden (y está seguro de que los datos no han sido alterados), asegúrese de que las claves utilizadas para generar los hashes (en el script y en la WebTV) son los mismos. Si son iguales, verifique que los datos recibidos están siendo urldecoded y que está generando la firma de la misma manera como se explica en el ejemplo anterior.
Una vez que ha procesado el pago, debe redirigir al usuario de vuelta a la WebTV. En la URL de retorno debe incluir los detalles del pedido, el resultado del pago así como una firma de validación, como variables GET.
Los datos requeridos por la WebTV (variables GET)
• iq -> ID del pedido ("id_order").
• tp -> ID de la pasarela de pagos en la WebTV ("id_gateway") con el prefijo "gid_" y sufijo "-step_2". Ejemplo: si el ID de la pasarela de pagos es 3, entonces tp sería gid_3-step_2
• status -> El estado del pago: "SUCCESS" o "ERROR"
• status_msg -> En caso de que el estado es ERROR entonces suministre un mensaje, de lo contrario, se puede dejar en blanco.
• transaction -> ID de la transacción (esto es, normalmente, el ID/código de transacción suministrado por la pasarela de pago).
• signature -> Una firma (hash) para validar los datos. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Generando la firma de validación (hash) para la URL de retorno
Debe genertar una firma de validación que la WebTV utilizará para determinatr si los datos no han sido alterados en la URL de retorno.
Ejemplo en PHP:
$key = "la clave de firma secreta";
$data = array(
"id_gateway" => (string)$id_gateway,
"id_order" => (string)$id_order,
"status" => $status, // recuerde: "SUCCESS" o "ERROR"
"id_transaction" => (string)$id_transaction // el ID de la transacción...
);
$signature = base64_encode(hash_hmac('sha256', json_encode($data), $key, true));
Construyendo la URL de retorno...
Una vez que tiene los datos requeridos, construya la URL de retorno.
Fórmula:
{url_base_de_la_webtv}/index.php?go=store&do=payOrder&iq={id del pedido}&tp=gid_{id de la pasarela de pagos de la WebTV}-step_2&status={estado}&status_msg={urlencoded:mensaje de estado}&transaction={urlencoded:id de transacción}&signature={urlencoded:firma}
Ejemplo:
URL base de la WebTV: https://www.mywebtvdomain.com (use https:// si tiene habilitado SSL en la WebTV)
ID del pedido: 99
ID de la pasarela de pagos en la WebTV: 3
Estado del pago: "SUCCESS"
Mensaje de estado: "" (url encoded)
ID de la transacción: 98dfgdf89g7dg97df (url encoded)
Firma (hash): MGI5YzY0ZmE2N2Y4NW3ZDFmN2M0Zjc%3D (url encoded)
URL de retorno generada:
https://www.mywebtvdomain.com/index.php?go=store&do=payOrder&iq=99&tp=gid_3-step_2&status=SUCCESS&status_msg=&transaction=98dfgdf89g7dg97df&signature=MGI5YzY0ZmE2N2Y4NW3ZDFmN2M0Zjc%3D
Si la WebTV es capaz de validar los datos entonces procesará el pedido, otorgará el acceso al contenido comprado y mostrará el mensaje correspondiente al usuario.
La WebTV añadirá los detalles del pago (pago único + pagos periódicos) a la URL del script procesador de pagos como variables GET. Ejemplo:
http://.../procesador_de_pagos.php?action=pay&id_gateway={id_pasarela_de_pago}&id_order={id_pedido}&amount={importe}¤cy_code={código_de_moneda}&order_number={número_de_pedido}&signature={firma}&id_user={id_de_usuario}&rp_num={número_de_pagos_periódicos}&rp_1_...
Datos del pago único
• id_gateway -> ID de la pasartela de pagos en la WebTV
• id_order -> ID del pedido a pagar
IMPORTANTE: Necesitará id_gateway y id_order cuando retorne a la WebTV.
• amount -> Importe a pagar (decimal, por ejemplo: 10.5, 5, ...)
• currency_code -> Código de moneda del pedido (USD, EUR, etc.)
• signature -> Una firma (hash) para validar los datos. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Información adicional:
• id_user -> ID del Usuario (comprador) en la WebTV
Validando los datos del pago único
Antes de procesar el pago, debe validar los datos usando la firma. Para ello, debe generar la firma de la misma manera que lo hace la WebTV, y compararla con la firma recibida.
Ejemplo en PHP:
$key = "la clave de firma secreta";
$data = array(
"id_gateway" => (string)$id_gateway,
"id_order" => (string)$id_order,
"amount" => (string)$amount,
"currency_code" => $currency_code,
"order_number" => (string)$order_number
);
$signature = base64_encode(hash_hmac('sha256', json_encode($data), $key, true));
Una vez que ha generado la firma, debe compararla con la firma enviada por la WebTV: Si coinciden, puede continuar.
Cuando realice pruebas durante el desarrollo... si las firmas no coinciden (y está seguro de que los datos no han sido alterados), asegúrese de que las claves utilizadas para generar los hashes (en el script y en la WebTV) son los mismos. Si son iguales, verifique que los datos recibidos están siendo urldecoded y que está generando la firma de la misma manera como se explica en el ejemplo anterior.
Datos pagos periódicos
En caso de que la WebTV solicite la creación de pagos periódicos entonces incluirá variables GET adicionales.
• rp_num -> Número de solicitudes de pago periódicas.
Cada dato de un pago periódico llevará el prefijo rp_n_{data_field_name}, donde n es el número de la solicitud. Por favor tenga presente que el número es necesario cuando retorne a la WebTV.
• rp_n_sku -> SKU de la solicitud de pago periódico n - Puede utilizar esto como descripción.
• rp_n_amount -> Importe de la solicitud de pago periódico n (la moneda es la misma que la solicitud de pago única).
• rp_n_period -> Período de la solicitud de pago periódico n (puede ser DAY, WEEK, MONTH o YEAR).
• rp_n_period_frequency -> Frecuencia de la solicitud de pago periódico n (valor int). "period" y "period_frequecy" determinan el intervalo de tiempo que debe transcurrir para que cobre la tarjeta de crédito del comprador.
• rp_n_first_payment_date -> Fecha del primer pago para la solicitud de pago periódico n (Unix timestamp, UTC time zone). Esta es la fecha cuando debe realizar el primer cargo en la tarjeta de crédito del comprador (para este pago periódico).
Por ejemplo: si "period" es MONTH, "period_frequency" es 1 y "first_payment_date" es 22 Feb 2016, entonces
Pago 1 = 22 Feb 2016
Pago 2 = 22 Mar 2016
Pago 3 = 22 Abr 2016
• rp_n_signature -> Una firma (hash) para validar la solicitud de pago periódico n. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Creando un arreglo con las solicitudes de pagos periódicos y validando los datos
Mientras crea el arreglo con las solicitudes de pagos periódicos, las validará utilizando sus firmas. Para ello, debe generar la firma de la misma manera que lo hace la WebTV, y compararla con la firma recibida. Si una firma no coincide, deberá añadir una solicitud fallida al arreglo, con un mensaje de error en el índice "error"; sino, añada la solicitud -válida- al arreglo, para posterior procesado.
Ejemplo en PHP:
$key = "la clave de firma secreta"; // normalmente, definida al comienzo del script
$recurring_payments = array();
if ( isset($_GET["rp_num"]) && $_GET["rp_num"]>0)
{
for ( $i=0; $i<$_GET["rp_num"]; $i++)
{
// Recopile los datos del pago periódico "i"
$rp_sku = (isset($_GET["rp_".$i."_sku"]))? rawurldecode($_GET["rp_".$i."_sku"]) : "";
$rp_amount = (isset($_GET["rp_".$i."_amount"]))? $_GET["rp_".$i."_amount"] : 0.0;
$rp_period = (isset($_GET["rp_".$i."_period"]))? $_GET["rp_".$i."_period"] : "";
$rp_period_frequency = (isset($_GET["rp_".$i."_period_frequency"]))? $_GET["rp_".$i."_period_frequency"] : 0;
$rp_first_payment_date = (isset($_GET["rp_".$i."_first_payment_date"]))? $_GET["rp_".$i."_first_payment_date"] : 0;
$rp_signature = (isset($_GET["rp_".$i."_signature"]))? rawurldecode($_GET["rp_".$i."_signature"]) : "";
// Ahora, genere una firma para compararla contra la variable "signature".
$rp_computed_signature = base64_encode(hash_hmac('sha256', md5( $rp_sku . floatval($rp_amount) . $rp_period_frequency . $rp_period ) , $key, true));
if ( $rp_computed_signature!=$rp_signature)
{
// Si las firmas no coinciden, añada un item fallido (omítalo de su procesamiento pero manténgalo como "fallido" para poder retornar el resultado a la WebTV)
// Items fallidos deben tener un índice "error" en el arreglo, de lo contrario ese índice no debe estar presente en el resultado de retorno
$recurring_payments[$i]=array(
"error" => "Datos inválidos para la solicitud de pagos periódicos o firma incorrecta",
"sku" => "",
"amount" => 0,
"period" => "",
"period_frequency" => 0,
"first_payment_date" => 0,
"profile_id" => "",
"status" => "Perfil inválido"
);
}
else
{
// Añada un item válido para procesar posteriormente
$recurring_payments[$i]=array(
"sku" => $rp_sku,
"amount" => $rp_amount,
"period" => $rp_period,
"period_frequency" => $rp_period_frequency,
"first_payment_date" => $rp_first_payment_date
// Los siguientes campos deben ser rellenados después de procesar esta solicitud
"profile_id" => "MyUniqueInternalProfileID", // ID para identificar este perfil en llamadas futuras
"status" => "Active" // El estado puede ser: Active, Pending, Cancelled, Suspended, Expired
);
}
}
}
Una vez que el arreglo ha sido generado, debe procesar las solicitudes. Como puede ver en el ejemplo, para cada ítem (válido) procesado debe retornar un ID único, este es el ID interno para el pago periódico. Será utilizado por la WebTV para solicitar al script procesador de pagos el estatus de un perfil (para saber si está activo, la fecha del último/próximo pago, etc.) o para solicitar la cancelación de un pefil.
Una vez que ha procesado el pago único, así como los periódicos, debe redirigir al usuario de vuelta a la WebTV. En la URL de retorno debe incluir los detalles del pedido, los resultados del pago único y los periódicos, así como las firmas de validación corresponsientes, como variables GET.
Datos del pago único
Los datos requeridos por la WebTV (variables GET)
• iq -> ID del pedido ("id_order").
• tp -> ID de la pasarela de pagos en la WebTV ("id_gateway") con el prefijo "gid_" y sufijo "-step_2". Ejemplo: si el ID de la pasarela de pagos es 3, entonces tp sería gid_3-step_2
• status -> El estado del pago: "SUCCESS" o "ERROR"
• status_msg -> En caso de que el estado es ERROR entonces suministre un mensaje, de lo contrario, se puede dejar en blanco.
• transaction -> ID de la transacción (esto es, normalmente, el ID/código de transacción suministrado por la pasarela de pago).
• signature -> Una firma (hash) para validar los datos. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Generando la firma de validación (hash) para la URL de retorno
Debe generar una firma de validación que la WebTV utilizará para determinatr si los datos no han sido alterados en la URL de retorno.
Ejemplo en PHP:
$key = "la clave de firma secreta";
$data = array(
"id_gateway" => (string)$id_gateway,
"id_order" => (string)$id_order,
"status" => $status, // recuerde: "SUCCESS" o "ERROR"
"id_transaction" => (string)$id_transaction // el ID de la transacción...
);
$signature = base64_encode(hash_hmac('sha256', json_encode($data), $key, true));
Construyendo la URL de retorno...
Una vez que tiene los datos requeridos, construya la URL de retorno.
Fórmula:
{url_base_de_la_webtv}/index.php?go=store&do=payOrder&iq={id del pedido}&tp=gid_{id de la pasarela de pagos de la WebTV}-step_2&status={estado}&status_msg={urlencoded:mensaje de estado}&transaction={urlencoded:id de transacción}&signature={urlencoded:firma}
Ejemplo:
URL base de la WebTV: https://www.mywebtvdomain.com (use https:// si tiene habilitado SSL en la WebTV)
ID del pedido: 99
ID de la pasarela de pagos en la WebTV: 3
Estado del pago: "SUCCESS"
Mensaje de estado: "" (url encoded)
ID de la transacción: 98dfgdf89g7dg97df (url encoded)
Firma (hash): MGI5YzY0ZmE2N2Y4NW3ZDFmN2M0Zjc%3D (url encoded)
URL de retorno generada:
https://www.mywebtvdomain.com/index.php?go=store&do=payOrder&iq=99&tp=gid_3-step_2&status=SUCCESS&status_msg=&transaction=98dfgdf89g7dg97df&signature=MGI5YzY0ZmE2N2Y4NW3ZDFmN2M0Zjc%3D
Datos de los pagos periódicos
En caso de haber solicitudes de pagos periódicos, también debe incluir los datos de cada solicitud (como variables GET), así como un indicador de la existencia de dichos pagos periódicos.
- El indicador de pagos periódicos: A la variable GET tp detallada anteriormente debe añadir el string "-rp_1". Ejemplo: &tp=gid_3-step_2-rp_1
- Para cada solicitud de pago periódico se requieren las variables GET correspondientes, de la forma rp_n_{data_field_name}, donde n es el número de la solicitud.:
• rp_n_error -> (opcional) Únicamente si existe el índice "error" en el arreglo de pagos periódicos.
• rp_n_profile_id -> ...
• rp_n_status -> ...
• rp_n_first_payment_date -> ...
• rp_n_signature -> Una firma (hash) para validar los datos. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Ejemplo en PHP:
$key = "la clave de firma secreta";
$return_url = "...."; // La URL de retorno generada hasta el momento
if ( !empty($recurring_payments))
{
// Añadiendo el inidacor de pagos periódicos
$return_url = str_replace('-step_2&','-step_2-rp_1&',$return_url);
foreach ( $recurring_payments as $rp_index => $rp_data)
{
// Generando la firma de validación
$rp_signature = base64_encode(hash_hmac('sha256', md5( $rp_data["profile_id"] . $rp_data["status"] ) , $key, true));
// Añadiendo las variables GET a la URL de retorno
if ( isset($rp_data["error"])) $return_url .= "&rp_".$rp_index."_error=".urlencode($rp_data["error"]);
$return_url .= "&rp_".$rp_index."_profile_id=".urlencode($rp_data["profile_id"]);
$return_url .= "&rp_".$rp_index."_status=".urlencode($rp_data["status"]);
$return_url .= "&rp_".$rp_index."_first_payment_date=".$rp_data["first_payment_date"];
$return_url .= "&rp_".$rp_index."_signature=".urlencode($rp_signature);
}
}
Redireccionando al comprador a la WebTV
Si la WebTV es capaz de validar los datos entonces procesará el pedido, otorgará el acceso al contenido comprado, asignará los perfiles de pagos periódicos a las suscripciones y mostrará el mensaje correspondiente al usuario.
La WebTV añadirá los datos de la solicitud a la URL del script procesador de pagos como variables GET. Ejemplo:
http://.../procesador_de_pagos.php?action=rp_status&profile_id={id_perfil_de_pagos}&signature={firma}
Datos de la solicitud (variables GET)
• profile_id -> ID del perfil de pagos periódicos. Este es el ID que este script retornó a la WebTV cuando creó el perfil de pagos periódicos.
• signature -> Una firma (hash) para validar los datos. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Validando los datos de la solicitud
Antes de procesar el pago, debe validar los datos usando la firma. Para ello, debe generar la firma de la misma manera que lo hace la WebTV, y compararla con la firma recibida.
Ejemplo en PHP:
$key = "la clave de firma secreta";
$profile_id = (isset($_GET["profile_id"]))? $_GET["profile_id"] : "";
$data = array(
"action" => "rp_status",
"profile_id" => (string)$profile_id
);
$signature = base64_encode(hash_hmac('sha256', json_encode($data), $key, true));
Una vez que ha obtenido la información del perfil de pagos periódicos debe retornar los datos como un arreglo en formato JSON.
Índices del arreglo requeridos por la WebTV
• error -> (opcional) Sólo si ocurrió un error al procesar los datos.
• status -> Estado del perfil. Valores posibles: Active, Pending, Cancelled, Suspended, Expired
• last_payment_date -> Fecha del último pago -exitoso- (Unix timestamp, UTC time zone). IMPORTANTE: Esto será utilizado por la WebTV para saber si un (ciclo de) pago periódico se ha efectuado. Devuelva 0 si no se ha realizado ningún pago.
• next_payment_date -> Fecha del próximo pago (Unix timestamp, UTC time zone).
Ejemplos en PHP:
- Éxito -
echo json_encode( array(
"status" => "Active",
"last_payment_date" => 1422344201,
"next_payment_date" => 1425022599
));
-Error-
echo json_encode( array(
"error" => "Un mesaje de error detallado..."
));
La WebTV añadirá los datos de la solicitud a la URL del script procesador de pagos como variables GET. Ejemplo:
http://.../procesador_de_pagos.php?action=rp_cancel&profile_id={id_perfil_de_pagos}&signature={firma}
Datos de la solicitud (variables GET)
• profile_id -> ID del perfil de pagos periódicos. Este es el ID que este script retornó a la WebTV cuando creó el perfil de pagos periódicos.
• signature -> Una firma (hash) para validar los datos. La firma es generada con la clave de firma introducida en la configuración de la Tienda, usando HMAC SHA256.
Validando los datos de la solicitud
Antes de procesar el pago, debe validar los datos usando la firma. Para ello, debe generar la firma de la misma manera que lo hace la WebTV, y compararla con la firma recibida.
Ejemplo en PHP:
$key = "la clave de firma secreta";
$profile_id = (isset($_GET["profile_id"]))? $_GET["profile_id"] : "";
$data = array(
"action" => "rp_status",
"profile_id" => (string)$profile_id
);
$signature = base64_encode(hash_hmac('sha256', json_encode($data), $key, true));
Una vez que haya cancelado el perfil de pagos periódicos debe retornar el resultado como un arreglo en formato JSON.
Índices del arreglo requeridos por la WebTV
• error -> (opcional) Sólo si ocurrió un error al procesar los datos.
• status -> Estado del perfil después de haber sido cancelado. Debe ser Cancelled.
Ejemplos en PHP:
- Éxito -
echo json_encode( array(
"status" => "Cancelled"
));
-Error-
echo json_encode( array(
"error" => "Un mesaje de error detallado..."
));