Objetivo

Niveles de Servicio y alcance

Diagrama de Flujo

Mecanismos de seguridad

Servicios Web

U

Consulta de Retiros Efectivo

Pago Retiro

Cancelación de Retrio

Autenticación Consulta

U

Consulta de Transacciones por Emisor

U

Consulta de Saldo

U

Especificaciones

Complementos

Este documento describe como crear una conexión con La Plataforma Tecnológica de CLUBPAGO que permita procesar en línea tus pagos recibidos en los puntos de venta afiliados a CLUBPAGO.

Definiciones y abreviaciones utilizadas

Abreviación Descripción
JSON (acrónimo de JavaScript Object Notation, «notación de objeto de JavaScript») es un formato de texto sencillo para el intercambio de datos
Mensajería Modelo de comunicación, Mensaje es la información dirigida de un emisor a un receptor. Donde ambos conocen la estructura y los conceptos de la información
PDV Punto de Venta
Timeout El tiempo estipulado de espera máxima para la respuesta entre emisor y receptor
EMISOR Es el proveedor de servicio que requiere el pago
Cliente Es el cliente final o usuario del servicio del Emisor. Es el que acude al PDV y realiza el pago
Referencia Identificador de pago que presenta el Cliente al realizar su pago
URL Uniform Resource Locator, es la dirección específica que se asigna a cada uno de los recursos disponibles en la red con la finalidad de que estos puedan ser localizados o
identificados.
HTTPS Protocolo de conectividad seguro utilizado para la Mensajería

NIVELES DE SERVICIO

Disponibilidad de servicio
Plataforma CLUBPAGO
99%
Tiempo de respuesta máxima
de conector CLUBPAGO
15 segundos
Tiempo compromiso de procesamiento de un pago, desde la captura de referencia, hasta concluir con recepción de pago 30 segundos

Alcance

Con la utilización de nuestra herramienta tecnológica GENERADOR DE REFERENCIAS y API en línea tu plataforma realiza la generación de referencia de retiro para que tus clientes pueden disponer de efectivo en las cadenas comerciales autorizadas.

Con este conector también podrás enviar dispersiones por SPEI (Transferencias electrónicas). Previamente se proporcionará una Cuenta Clabe para el fondeo de la cuenta de dispersión. EL Emisor vía API enviará solicitud de dispersión al conector de CLUBPAGO, solicitud que será procesada por CLUBPAGO y posteriormente enviará respuesta al Emisor.

DIAGRAMAS DE FLUJO  RETIROS

 

1.- Retiros en Efectivo

1.- El cliente acude a un PDV de la Red de Distribución de CLUBPAGO y solicita la operación de retiro. El PDV envía transacción validando referencia y el cliente EMISOR correspondiente.

2.- Si el EMISOR tiene conexión en línea, CLUBPAGO solicita Consulta de Referencia en el conector del EMISOR para validar.

3.- El conector del EMISOR envía a CLUBPAGO respuesta exitosa o fallida a la consulta.

4.- CLUBPAGO envía respuesta al PDV.

5.- PDV envía la solicitud retiro a CLUBPAGO.

6.- CLUBPAGO llama al conector del EMISOR con la autorización del retiro, enviando datos de monto a retirar.

7.- EMISOR responde a CLUBPAGO la solicitud de autorización de retiro, respuesta exitosa o fallida.

8.- CLUBPAGO entrega al PDV, respuesta exitosa o fallida.

2.- Cancelación de Retiros en Efectivo

1.- El PDV no ejecuta la solicitud de retiro, CLUBPAGO debe solicitar la cancelación del pago al EMISOR.

2.- Si el EMISOR tiene conexión en línea, CLUBPAGO manda llamar el servicio de
cancelación de pago al EMISOR.

3.- El EMISOR debe confirmar que el retiro solicitado ha sido cancelado. CLUBPAGO implementará cambiar el estado de la operación a cancelada. La solicitud se ejecuta dentro de 24 horas después de la
solicitud de autorización del retiro.

MECANISMOS DE SEGURIDAD PARA EL CONECTOR DEL EMISOR

El EMISOR debe definir la ubicación su conector, para que la Plataforma CLUBPAGO realice las solicitudes de servicio al EMISOR.

El EMISOR debe definir la ubicación su conector, para que la Plataforma CLUBPAGO realice las solicitudes de servicio al EMISOR.
https://[BASE_URL]/

Donde [BASE_URL] es la URL del EMISOR

Se requiere que para un ambiente de producción es obligatorio que la URL del servicio solo pueda ser accesada mediante HTTPS: es decir un Protocolo seguro de Transferencia que contiene un certificado de seguridad para el manejo encriptado de datos.

AUTENTICACIÓN PARA EL EMISOR

Se definirá un TOKEN que funcionará como identificador Único para el EMISOR.
Este TOKEN es de longitud variable y se forma de letras y números.

Las solicitudes de SERVICIO incluyen un HEADER que contiene la identificación del EMISOR con lo siguiente

KEY  VALUE DESCRIPTION
X-Origin TOKEN EMISOR base64  Método de autenticación de  Emisor
User-Agent CPAPI_AGNT_V1 Identificador de la aplicación

Estos valores podrán ser CAMBIADOS, en periodos de tiempo como medida de SEGURIDAD, CLUBPAGO enviará nuevos valores de IDENTIFICACION y se coordinará con el EMISOR para su actualización.

Estos valores de IDENTIFICACIÓN DEL EMISOR son enviados y validados en cada servicio que solicite CLUBPAGO al EMISOR. Si en dicha validación SE PRESENTAN problemas se contestará con los siguientes números de mensaje.

Si el TOKEN no corresponde se contesta HTTP 401 con el mensaje: “Token Inválido”. 

Si el User-Agent no corresponde se contesta HTTP 403 con el mensaje: “Origen Desconocido”.

Ejemplo de Solicitud :

La autenticación de CLUBPAGO entregará un TOKEN que funcionará como identificador Único para el EMISOR. Este TOKEN es de longitud variable y se forma de letras y números. Entrega un JSON con la siguiente estructura:

Nombre del Campo Tipo del Valor Descripción
Message Alfanumérico Mensaje (Exito, Error, etc)
Token Alfanumérico Serie de caracteres que contiene la información para la autenticación.
Expiration Fecha Fecha de vigencia del Token

SERVICIOS WEB A IMPLEMENTAR POR EL EMISOR

La Plataforma CLUBPAGO podrá solicitar los siguientes SERVICIOS WEB, los cuales serán llamados por HTTPS

1.- onsulta de Referencia de Retiro de Efectivo.
2.- SPago Referencia de Retiro de Efectivo.
3.- Cancelación Referencia de Retiro de Efectivo.

 

 SERVICIO DE CONSULTA DE REFERENCIA

El servicio de Consulta será llamado por La Cadena Receptora cuando un Cliente solicite un Retiro de Efectivo. Esta acción realizará una validación de la Referencia por CLUBPAGO y en su respuesta indicando el resultado de la consulta debe contener código respuesta y monto del retiro en efectivo en el caso de ser una consulta exitosa. Si la consulta de referencia de retiro es fallida envía en la respuesta la descripción del error.

Timeout Consulta: El Timeout de la Cadena Receptora será de 30 Segundos de espera de la
respuesta de la consulta.

Timeout Consulta: La plataforma CLUBPAGO espera 10 segundos la respuesta a la consulta Emisor controla si acepta más de un pago por Referencia El EMISOR puede controlar solo recibir un pago por Referencia. Dado que en este servicio se consulta la Referencia, si el EMISOR ya recibió el pago y NO PUEDE RECIBIR MÁS PAGOS CON ESTA REFERENCIA, enviará en la consulta de pago el código 13 Referencia sin adeudo.

Petición enviada por Cadena Comercial

Se llamará a este servicio mediante un método HTTP GET, utilizando las reglas de autenticación.
Se envía en el Header Authorization (Token) CLUBPAGO llamará a este servicio mediante un método HTTP GET, utilizando las reglas de Autenticación para el EMISOR. El cuerpo de la petición se enviará vacío.
La estructura de la solicitud será la siguiente:

https://[BASE_URL]/Service/ConsultaRetiro/?r=[REFERENCIA]
Usando el parámetro “r” en la URL el cual va a contener la Referencia a consultar En el ambiente de producción es obligatorio que la URL del servicio solo pueda ser accesada mediante HTTPS.

Respuesta del Servicio

El servicio espera una respuesta HTTP 200 OK, con un cuerpo de tipo application/json con los siguientes campos:

 

Nombre Tipo Longitud Máxima Descripción
Código Numérico 2 El código de respuesta indicando el resultado del Servicio.
Mensaje Alfanumérico 1 – 255 Una descripción del resultado del servicio. Esto solo es usado por CLUBPAGO para revisión de posibles errores.
Monto Numérico 16 Monto a pagar multiplicado por 100 Ej. 150 debe enviarse como 15000. Los 2 últimos dígitos son decimales.
Referencia Alfanumérico Max Referencia a pagar, con finalidad de cotejar que sea idéntica a la solicitada.
Transacción Numérico 16 Identificador consecutivo de la operación.

PAGO RETIRO

Petición enviada por CLUBPAGO.

CLUBPAGO llamará a este servicio mediante un método HTTP POST, utilizando las reglas de autenticación del EMISOR. El contenido de la petición será de tipo application/json, codificado en UTF-8.

La estructura de la solicitud será la siguiente: https://[BASE_URL]/Service/PagoRetiro/
El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades:

La estructura de la solicitud será la siguiente: https://[BASE_URL]/Service/PagoReferencia/


El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades:

 

Nombre Tipo Longitud Máxima Descripción
Referencia Alfanumérico  Max La Referencia que se está autorizando.
Fecha fecha 25 La fecha y hora del pago efectuado.
Monto Numérico 16 Monto a pagar multiplicado por 100 Ej. 150 debe enviarse como 15000. Los 2 últimos dígitos son decimales.
Transacción Numérico 16 Id de la transacción registrada en CLUBPAGO.
Método de pago Alfanumérico 2 Identificación del método de pago: EF”(Efectivo)

En el ambiente de Producción es obligatorio que la URL del servicio solo pueda ser accesada mediante HTTPS.

Respusta del Servicio

El servicio espera una respuesta HTTP 200 OK, con un cuerpo de tipo application/json con los siguientes campos:

 

 

Nombre Tipo Longitud
Max
Descripción
codigo Numérico  2 El código de respuesta indicando el resultado de la autorización.
autorización Numérico 8 Un número que identifique el pago, en caso de una autorización exitosa.
mensaje Alfanumérico 255 Una descripción del error, en caso de una autorización fallida.
Esto solo es usado por CLUBPAGO para revisión de posibles errores.
transacción Numérico 16 Id de la transacción registrada en CLUBPAGO.
fecha Fecha 25 La fecha y hora del pago autorizado. Formato sugerido (yyyy-MM-ddTHH:mm:ssZ)
mensaje_ticket Alfanumérico  160 Términos y condiciones de la transacción realizada.
notificacion_sms Numérico  10 Número telefónico para notificar al cliente por
SMS para confirmar que su pago fue exitoso.
mensaje_sms Alfanumérico 160 Mensaje para notificación SMS en caso de ser
un pago exitoso.

Códigos de respuesta

El servicio autorizador debe de regresar un código indicando el resultado de la autorización:

 

 Código Descripción Causa
0 CONSULTA EXITOSA El resultado de la consulta fue exitoso.
0 RETIRO EFECTIVO
EXITOSO
El retiro de efectivo fue exitoso.
2 ORIGEN DESCONOCIDO Header no presente o no configurado. Se debe dar aviso de inmediato por parte del emisor hacia CLUBPAGO.
10 MONTO INVÁLIDO El monto de la referencia es inválido.
21 SOLICITUD INVÁLIDA La solicitud enviada en inválida.
61 FORMATO DE
REFERENCIA INVÁLIDO
El formato de la referencia no corresponde a las especificaciones del producto.
62 CANCELACION FALLIDA La cancelación enviada ha sido fallidao.
69 ERROR DESCONOCIDO Ocurrió un error en el servicio es una error de la plataforma del Emisora.
90 EMISOR DESHABILITADO El emisor se encuentra deshabilitado.
91 REVERSO EJECUTADO
PREVIAMENTE
El Reverso que se ha solicitado fue previamente ejecutado.
92 TRANSACCION NO
EXITOSA NO ES POSIBLE
REVERSAR
El estatus de la transacción que intenta reversar es fallido y no es posible reversar.
93 REVERSO EXITOSO El reverso de la transacción solicitada es exitoso.
94 REVERSO NO
ENCONTRADO
Al intentar realizar el reverso la transacción no ha sido encontrada.
95 SIN SALDO PARA
EJECUTAR RETIRO
El saldo de la cuenta no es suficiente para ejecutar el Retiro solicitado.
96 REFERENCIA INVÁLIDA Error en la Referencia.
97 EFERENCIA EXPIRADA La referencia del retiro que intenta cobrar esta fuera del período de
vigencia.
98 REFERENCIA YA
CANJEADA
El Retiro que intenta cobrar ha sido pagada previamente.

SERVICIO DE CANCELACIÓN DE RETIRO

El servicio de cancelación será llamado por CLUBPAGO cuando el PDV requiera cancelar un retiro, usualmente en caso de que tuviera un error al momento de registrar su transacción.

Petición enviada por CLUBPAGO La petición enviada por CLUBPAGO será de tipo HTTP DELETE, con los valores de la
transacción a cancelar en la URL del servicio.

La estructura de la solicitud será la siguiente:

https://[BASE_URL]/Service/CancelaRetiro/

El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades:

 

Nombre Tipo Longitud Máxima Descripción
referencia Alfanumérico  255 La referencia que se está autorizando.
fecha fecha 20 La fecha y hora del pago efectuado,
Formato sugerido (yyyy-MM-ddTHH:mm:ssZ)
monto Numérico 16 Monto a pagar multiplicado por 100 Ej. 150 debe enviarse
como 15000.(Los 2 últimos dígitos son decimales)
transaccion Numérico 16 Id de la transacción registrada en CLUBPAGO
autorización Numérico 8 Número de autorización enviado por el emisor

En el ambiente de producción es obligatorio que la URL del servicio solo pueda ser accesada
mediante HTTPS.
Respuesta del Servicio

En este caso CLUBPAGO espera una respuesta HTTP con un estado HTTP 2xx de preferencia 200 OK o 204 No Content.

 

Nombre Tipo Longitud Máxima Descripción
codigo Numérico  2 El código de respuesta indicando el resultado de la
autorización.
mensaje Alfanumérico 255 Una descripción del error, en caso de una autorización
fallida. Esto solo es usado por CLUBPAGO para revisión
de posibles errores.

Códigos de Respuesta 

El servicio autorizador debe de regresar un código indicando el resultado de la autorización:

 

 Código Descripción Causa
0 Cancelación Exitosa Transacción cancelada. Si la cancelación ya había sido previamente cancelada también se tiene que responder con código 0.
1 Token Inválido El Token no coincide. Se debe dar aviso de inmediato por parte del emisor a CLUBPAGO.
2 Origen Desconocido Header no presente o no configurado. Se debe dar aviso de inmediato por parte del emisor hacia CLUBPAGO.
60 Cancelación fuera de período La cancelación se intentó después de la fecha permitida(Después del día del pago).
61 Cancelación fallida La cancelación no puede ser procesada por el EMISOR.

AUTENTICACIÓN SERVICIO DE CONSULTA 

Para utilizar los servicios de Consulta de Transacciones por Emisor y Consulta de Saldo CLUBPAGO entregará un TOKEN que funcionará como identificador único para el EMISOR. Este TOKEN es de longitud variable y se forma de letras y números

solicitud será la siguiente:

El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades:

 

Nombre Tipo Descripción Obligatorio
User Alfanumérico  Nombre de Usuario  SI
PSW Alfanumérico Contraseña SI

El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades:

https://qa.clubpago.site/plat/apiRetiros/token

Ejemplo de Solicitud :

{
"User": "Emisorcppruebas",
"Pswd": "Emisorcppruebas"
}
var options = new RestClientOptions("")
{
MaxTimeout = -1,
};

var client = new RestClient(options);
var request = new RestRequest("https://qa.clubpago.site/plat/apiConsulta/token", Method.Post);
request.AddHeader("Content-Type", "application/json");
var body = @"{
" + "n" +
@"  ""User"": ""Emisorcppruebas"",
" + "n" +
@"  ""Pswd"": ""Emisorcppruebas""
" + "n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);
Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post("https://qa.clubpago.site/plat/apiConsulta/token")
.header("Content-Type", "application/json")
.body("{rnt"User": "Emisorcppruebas",rnt"Pswd": "Emisorcppruebas"rn}")
.asString();

 

<?php

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://qa.clubpago.site/plat/apiConsulta/token',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"User": "Emisorcppruebas",
"Pswd": "Emisorcppruebas"
}',

CURLOPT_HTTPHEADER => array(
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

curl --location 'https://qa.clubpago.site/plat/apiConsulta/token' 
--header 'Content-Type: application/json' 
--data '{ "User": "Emisorcppruebas", "Pswd": "Emisorcppruebas"
}'

Respuesta

{
” Message “: “Token generado exitosamente”,
” Token “:” eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJiNjM3OWZj          Ni01NDNlLTRhZmMtOWZhYy01NjgxNGY1MzdkZmIiLCJVc2VySWQiOiIyNDQiLCJFbWlzb3JJZCI6IjYyOCIsIlVzZXJOYW1lIjoiRW1pOTUwSEIiLCJuYmYiOjE3NzAxMzczMDEsImV4cCI6MTc3MDI0MTcwMSwiaXNzIjoiY2x1YnBhZ28ubXgiLCJhdWQiOiJjbHVicGFnby5teCJ9.GXm1avm0tMKcaV1V3h7FP5nZRNzsFS4iQrJfAES2RypsLBXLZE”,
“Expiration”: “00260103012505307001”,
}

SERVICIO DE CONSULTA TRANSACCIONES POR EMISOR

El servicio de consulta por transacciones por emisor muestra la totalidad de transacciones exitosas por emisor
en un rango de fechas. La estructura de la solicitud será la siguiente:

El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades

Parámetros

 

Nombre Tipo Descripción Obligatorio
DtDesde Fecha  Fecha Desde SI
DtHasta Fecha Fecha Hasta SI
https://qa.clubpago.site/plat/apiRetiros/ConsultaTransaccionesPorEmisorRetiros

Parametros

No Requiere

"ResponseCode": "00",
"ResponseMessage": "Consulta exitosa"
"Data": [
{
"TransactionId": 10109,
"TransactionDate":"2026-01-13T16:43:14.277",
"Authorization": "609490",
"ExternalId": "00260103012505307001",
"Reference": "5559609876543213035",
"Amount": 200.0000
},
{
"TransactionId": 10110,
"TransactionDate":"2026-01-13T16:43:26.733",
"Authorization": "5661763",
"ExternalId": "00260103012505307002",
"Reference": "5559609876543213043",
"Amount": 200.0000
}
]
}

SERVICIO DE CONSULTA DE SALDO

El servicio de consulta de saldo muestra el saldo disponible para realizar dispersiones. La estructura de la solicitud será la siguiente:

El cuerpo de la petición contendrá un objeto JSON con las siguientes propiedades

Parámetros

https://qa.clubpago.site/plat/apiRetiros/ConsultaTransaccionesPorEmisorRetiros

Parametros

No Requiere

{
 "ResponseCode": "00",
 "ResponseMessage":"Consulta Exitosa",
 "Balance": 19562.0000
}

ESPECIFICACIONES A CONSIDERAR

Tiempo de comunicación entre CLUBPAGO y el Servicio

CLUBPAGO esperará máximo 15 segundos por una respuesta del servicio autorizador, y una vez pasado ese tiempo es posible que CLUBPAGO cancele la conexión y considere la transacción como rechazada.

Comunicación HTTPS

Aunque en el ambiente de Sandbox se permite que el servicio sea HTTP, no olvides que en el ambiente de producción se requiere que el servicio se encuentre solo disponible mediante HTTPS.

Errores en el servicio autorizador

Si los servicios llegaran a fallar, ya sea porque el servidor no responde o por que el servicio no regresó una respuesta HTTP 2xx, CLUBPAGO tomará las siguientes acciones:
    • En el caso del servicio de autorización, se considerará la transacción como rechazada
      y no se aceptará el pago.
    • En el caso de cancelación, CLUBPAGO solo registrará el evento y continuará con la
      operación de cancelación. Es decir, realizará reintentos cada 15 minutos, hasta que
      obtenga una RESPUESTA EXITOSA DEL EMISOR

Tiempo de cancelación

Pago recibido en Cadena:
Una vez autorizada una transacción, ésta podría ser cancelada de manera automática
dentro de los 10 minutos siguientes, por lo que su aplicación debe tomar esto en cuenta e implementar funciones para cubrir esta posibilidad.
Para pagos por transferencia Bancaria y pago con tarjeta la cancelación no aplica, ya que se confirma como exitosa o fallida.

Recomendación para desarrollo de la aplicación del EMISOR

Se recomienda al EMISOR desarrollar utilizando POSTMAN
POSTMAN nace como una herramienta que principalmente nos permite crear peticiones sobre APIs de una forma muy sencilla y poder, de esta manera, probar las APIs. Todo basado en una extensión de Google Chrome. Convirtiendo a POSTMAN plataforma de desarrollo de APIs que se basa por un modelo de desarrollo API First POSTMAN permite el envío de peticiones HTTP REST sin necesidad de desarrollar un cliente.
Una vez instalado POSTMAN, es necesario abrirlo e instalar el plugin Jetpack de Postman para poder crear las pruebas y lanzarlas conjuntamente.
En el Anexo A de este documento encontrará una guía de cómo utilizar POSTMAN para construir su aplicación que interactúe con CLUBPAGO

Contacto para dudas

Favor de contactarme si tienes dudas durante la integración a:

 

Nivel Nombre Correo Teléfono
Nivel 1 Ángel Maldonado Chagoya  amaldonado@clubpago.mx 871 478 0520
Nivel 2 Marco Galván Torres it@rpmmx.net 871 478 0520

ANEXO A
GUIA EMULADOR CLUBPAGO API CON POSTMAN

Para descargar el software POSTMAN lo puedes realizar desde la siguiente dirección:
https://www.postman.com/downloads/
POSTMAN hará la función de envío de solicitudes como si fuera CLUBPAGO API.
Tenemos disponible un Emulador de Emisor que contiene la estructura básica, de ejemplo, que tienes que programar para poder implementar CLUBPAGO API y una colección de solicitudes para importar en POSTMAN.
https://github.com/clubpago/ClubPagoAP

Complementos a esta funcionalidad

CLUBPAGO cuenta con un Sandbox (Ambiente de pruebas) que te ayudará a probar tu INTEGRACION DE PROVEEDORES O EMISORES DE PAGO. Solicita tus accesos y el Documento de Guía de uso del Sanbox de la Plataforma Tecnológica de CLUBPAGO.