Partners

Openpay provee un esquema de integración para los partners, este esquema permite realizar operaciones a nombre de un comercio, sin que este tenga que compartir sus credenciales de acceso a Openpay. Bajo este esquema, el comercio determina cuando restringe o permite a un partner realizar acciones a nombre del comercio dentro de Openpay.

Para que un partner pueda conectarse a la plataforma Openpay, es de suma importancia entender los siguientes temas:

  1. Cargos a tarjetas
  2. API Openpay
  3. Estándar OAuth 2
  4. Clientes OAuth 2
  5. Servicios Rest/HTTPS

Para conectar un partner a la plataforma, vamos realizar los siguientes pasos

  1. Registro de partner en plataforma.
  2. Integración del protocolo OAuth 2 en el aplicativo del partner.
  3. Consumir los servicios que expone Openpay en su API con las credenciales del partner.

1. Registro de partner

Como primer paso es necesario que el partner se registre en la plataforma de Openpay como integrador, este registro consta de llenar un formulario con datos similares al solicitado para los comercios. Después de haber completado y enviado este formulario, personal de Openpay validará su información, en caso de pasar este control se le notificará su confirmación de su registro vía correo electrónico y un par de códigos que identificarán a su empresa dentro de la plataforma como integradores.

Para accesar al formulario de registro en el ambiente de pruebas dar clic aquí

Al terminar de llenar el formulario y enviarlo, la cuenta del integrador se activará automáticamente y se enviará un correo con los datos necesarios para iniciar la integración mediante OAuth 2.0.

El correo electrónico que recibirá el integrador llevará un “client_id y un client_secret”, este par de códigos serán los identificadores del integrador ante Openpay.

Nota: Si después de la integración y pruebas en el ambiente de desarrollo, estas listo para pasar a producción da clic aquí para registrarte

2. Integración de flujo OAuth 2.0

El flujo OAuth que define Openpay para el esquema de integradores permite que de forma segura un comercio autorice a un partner que pueda realizar operaciones a nombre del comercio dentro de Openpay con llaves propias del integrador.

El partner deberá implementar el estándar OAuth 2 en su aplicativo para realizar la integración con Openpay, a continuación se muestra un par de diagramas donde se ilustran las 2 variantes del esquema que proporciona Openpay.

Flujo 1 : En este primer flujo se muestra la interacción entre las 3 entidades que intervienen en el flujo cuando un comercio ya tiene una cuenta existente y activa en Openpay.

Ejemplo de flujo oauth 2 con cuenta existente

Flujo 2: En este segundo flujo se muestra la interacción entre las 3 entidades que intervienen en el flujo cuando un comercio aun no esta registrado en Openpay.

Ejemplo de flujo oauth 2 con cuenta nueva

En ambos flujos se van a consumir 3 endpoint’s diferentes: Uno para solicitar permisos al usuario, otro para obtener un token de acceso y uno más para obtener la información del comercio. A continuación se describen cada uno de ellos:

Endpoints OAuth

  • https://sandbox-dashboard.openpay.mx/oauth/authorize: Permite conceder los permisos al partner para controlar la cuenta de un comercio.
  • https://sandbox-dashboard.openpay.mx/oauth/token: Permite obtener un token de acceso o un token de actualización.
  • https://sandbox-dashboard.openpay.mx/oauth/merchant: Permite consultar la información del comercio para realizar las operaciones en su nombre.

Nota: Para llamar los “Endpoints” de producción, es necesario cambiar en el path de las URI’s “sandbox-dashboard.openpay.mx” por “dashboard.openpay.mx”.

La interacción que existe entre las 3 entidades durante todo el flujo se pueden resumir en 5 pasos, que a continuación se describen:

1. Solicitando acceso a cuenta de comercio

El “Cliente (Integrador)” deberá hacer una llamada http al “Proveedor de servicios (Openpay)” para solicitar la autorización de acceso a la cuenta del comercio, el proveedor de servicios valida que sea una petición valida, posteriormente se redirecciona al “Usuario (Comercio)” a una pagina dentro del proveedor de servicios, en este punto al comercio se le mostrará una pantalla donde podrá conceder los permisos para que un “Integrador” pueda realizar operaciones en su nombre.

El integrador deberá proveer un botón para que el comercio pueda activar la funcionalidad de procesar pagos mediante Openpay, este botón deberá llamar la URI de autorización.

Ejemplo botón para recibir cargos mediante Openpay

A continuación se muestra la URI que el cliente deberá de invocar.

Características de la petición http:

  • Deberá ser una petición GET a la URI de autorización
  • El tipo de contenido deberá definirse como: “text/html, application/xhtml+xml o application/xml”

Sintaxis:

  https:///oauth/authorize?
  client_id=<client_id>
  &redirect_uri=<redirect_uri>
  &response_type=code
  &scope=<scope>

Ejemplo:

  https://sandbox-dashboard.openpay.mx/oauth/authorize?
  client_id=ppk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  &redirect_uri=https%3a%2f%2flocalhost%3a8443%2fsitepartner%2fregisterok
  &response_type=code
  &scope=read+write

Donde:

  • client_id: Identificador único del Integrador, este fue enviado por correo electrónico al Integrador despues de completar su registro y ser activada su cuenta.
  • redirect_uri: URI a la que se redirigirá al usuario tras su aprobación. Esta dirección debe coincidir con el valor definido en el campo URL del formulario de registro o fallará la aprobación. Este valor debe tener codificación de URL.
  • response_type: Valor fijo “code”. Indica que al autorizar el acceso a la cuenta Openpay por parte del usuario, se regresará un código de autorización.
  • scope: Valor fijo “read+write”. Define a lo que puede acceder la aplicación cliente en una cuenta Openpay.

Nota:

  • Los errores que puede lanzar el protocolo OAuth se describen en la sección “errores OAuth”
  • Para llamar la URI en producción, es necesario cambiar en el path “sandbox-dashboard.openpay.mx” por “dashboard.openpay.mx”

2. Autenticando usuario en la plataforma Openpay

El comercio tendrá la posibilidad de crear una nueva cuenta o usar una cuenta existente en Openpay, en ambos casos se requiere de una autorización ya sea implícita o explicita para que el “Integrador” pueda accesar a la cuenta del comercio. A continuación se describen ambos flujos:

  1. El comercio crea una nueva cuenta en Openpay

    El comercio al dar clic en el botón que provee el integrador desde su aplicativo, será enviado a una página dentro de la plataforma Openpay. El comercio selecciona “Nueva cuenta”, completa el formulario de registro y lo envía a Openpay.

    Openpay validará la información solicitada en el formulario, en caso de ser correctos estos datos personal de Openpay enviará un correo electrónico de confirmación. El correo recibido tendrá un botón para definir una contraseña y poder ingresar al portal WEB que provee Openpay para cualquier comercio.

Nota:

  • Cuando se crea una cuenta nueva desde un partner, la autorización se realizara de forma implícita.
  1. El comercio usa una cuenta existente en Openpay

    El comercio al dar clic en el botón que provee el integrador desde su aplicativo, será enviado a una página dentro de la plataforma Openpay. El comercio selecciona “Usar cuenta” e inicia sesión en Openpay.

    Como parte de la seguridad que provee este esquema de integración, al comercio se le mostrará una página de autorización para que explícitamente conceda al Integrador los permisos necesarios para que pueda realizar operaciones en su nombre.

    En caso de que el comercio no permita el acceso a su cuenta, el proveedor de servicios hará un redirect a la URI del Integrador, enviando como parámetros de respuesta en la URI:

    • error: access_denied
    • error_description: User+denied+access

Nota:

  • En el ambiente de pruebas cuando se crea un nuevo comercio, el correo de confirmación se envìa automaticamente y la activación de su cuenta también es automática.
  • Cuando se usa una cuenta existente desde un partner, la autorización se realizara de forma explícita.

3. Recibiendo código de autorización

El proveedor de servicios al recibir la concesión para que el integrador pueda realizar operaciones a nombre del comercio, se generará un código de autorización, el cual será enviado al integrador como parámetro (code) en un redirect http usando la URI proporcionada por el integrador.

A continuación se muestra la URI que el proveedor de servicios invoca:

Sintaxis:

  https://<redirect_uri>?code=<code>

Ejemplo:

  https://www.sitepartner.mx/PartnerTest/home?
  code=769FkXdN7rAicf1l2dLUEeBLs53pgM

Donde:

  • redirect_uri: URI a la que se redirigirá al usuario tras su aprobación. Debe coincidir con el valor del campo URL del formulario de registro del partner exactamente o fallará la aprobación. Este valor debe tener codificación de URL
  • code: Código de autorización que debe utilizar el integrador para obtener los tokens de acceso y actualización.

Nota: El código de autorización que regresa Openpay al integrador deberá conservarse, este se usará para solicitar el token de acceso.

4. Solicitando token de acceso

El integrador al momento de recibir el “código de autorización”, deberá generar una llamada http en background para solicitar al proveedor de servicios que genere el token de acceso a partir del código de autorización que le está enviando.

A continuación se muestra la URI que el integrador invoca.

Características de la petición http:

  • Deberá realizarse una petición GET a la URI de token

Sintaxis:

https://<Dashboard>/oauth/token
  ?code=<code>
  &client_id=<client_id>
  &client_secret=<client_secret>
  &grant_type=authorization_code
  &redirect_uri=<redirect_uri>

Ejemplo:

  https://sandbox-dashboard.openpay.mx/oauth/token?
  code=769FkXdN7rAicf1l2dLUEeBLs53pgM
  &client_id=ppk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  &client_secret=psk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  &grant_type=authorization_code
  &redirect_uri=http%3A%2F%2Fwww.sitepartner.mx%2FPartnerTest%2Fhome

Donde:

  • code: Código de autorización que debe utilizar el integrador para obtener los tokens de acceso y actualización.
  • client_id: Identificador único del integrador, este fue enviado por correo electrónico al Integrador despues de completar su registro y ser activada su cuenta.
  • client_secret: Llave secreta del integrador, esta llave fue enviada por correo electrónico al integrador despues de completar su registro y ser activada su cuenta.
  • grant_type: Valor fijo “authorization_code”. Define el tipo de validación que se aplicará para validar el acceso y generar el token de acceso.
  • redirect_uri: URI a la que se redirigirá al usuario tras su aprobación. Debe coincidir con el valor del campo URL del formulario de registro del partner exactamente o fallará la aprobación. Este valor debe tener codificación de URL.

A continuación se muestra la respuesta a la petición realizada por el integrador al proveedor de servicios:

Características de la respuesta http:

  • El tipo de contenido que se regresará es de tipo: “application/json”
  • Código de respuesta: 200.

Sintaxis:

{
   "access_token":"<access_token>",
   "token_type":"<token_type>",
   "refresh_token":"<refresh_token>",
   "expires_in":<expires_in>,
   "scope":"<scope>"
}

Ejemplo:

{
   "access_token":"5abd52c7-c320-46ae-832b-d3a0108f3242",
   "token_type":"bearer",
   "refresh_token":"29439t39-51f1a-4f3a-9479-e58a873b4ad0",
   "expires_in":297,
   "scope":"read write"
}

Donde:

  • access_token: Token de acceso usado para consumir los servicios expuestos con seguridad OAuth 2.
  • token_type: Valor fijo “bearer”.Tipo de token.
  • refresh_token: Token que podrá utilizarse en un futuro para obtener nuevos tokens de acceso (sesiones). Se trata de un valor secreto, por lo tanto debe considerarse como la contraseña del usuario y tomar las medidas adecuadas para protegerlo.
  • expires_in: Tiempo de vida para el token de acceso, expresado en segundos.
  • scope: Define los permisos que se han concedido para interactuar con los recursos expuestos por el API de Openpay.

Nota:

  • Los errores que puede lanzar el protocolo OAuth se describen en la sección “errores OAuth”

5. Obtener información del comercio para conectarse a su cuenta

Como último paso, el integrador deberá de consumir el servicio (petición http) que expone Openpay con seguridad OAuth 2 para obtener la información del comercio, quien acaba de autorizar el control de su cuenta. Con esta información se podrá consumir los servicios que actualmente expone el API de Openpay, pero recordar que toda operación se realizará en nombre del comercio.

A continuación se muestra la URI que el integrador invoca.

Características de la petición http:

  • Deberá realizarse una petición GET a la URI de información de comercio.

Sintaxis:

  https:///oauth/merchant?access_token=

Ejemplo:

  https://sandbox-dashboard.openpay.mx/oauth/merchant?
  access_token=e05fe2e3-6437-42e3-a82c-8c8131811b51

Donde:

  • access_token: Token de acceso usado para consumir los servicios expuestos con seguridad OAuth 2, este token es una representación de las credenciales de acceso.

A continuación se muestra la respuesta a la petición realizada por el integrador al proveedor de servicios.

Características de la respuesta http:

  • El tipo de contenido que se regresará es de tipo: “application/json”
  • Código de respuesta: 200.

Sintaxis:

{
   "merchant_id":"<merchant_id>",
   "secret_key":"<secret_key>",
   "public_key":"<public_key>",
   "merchant_partner_status":"<merchant_partner_status>",
   "merchant_status":"<merchant_status>"
}

Ejemplo:

{
   "merchant_id":"xxxxxxxxxxxxxxxxxxxx",
   "secret_key":"sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "public_key":"pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "merchant_partner_status":"active",
   "merchant_status":"active"
}

Donde:

  • merchant_id: Identificador de Openpay del comercio.
  • secret_key: Clave secreta, usada para llamar a la API de Openpay a nombre del comercio.
  • public_key: Llave pública, usada para la creación de tokens de tarjetas desde la libreria de Javascript de Openpay.
  • merchant_partner_status: Estado actual de la relación entre el comercio y el partner.
  • merchant_status: Estado actual del comercio.

Nota:

  • Para conocer los posibles errores que puede lanzar el protocolo OAuth. “Véase errores OAuth”
  • El Token de Acceso tiene una duración de 5 min. de validez para obtener la información del comercio.

3. Consumir el API de Openpay como integrador

A partir de este momento el integrador ya podrá consumir los servicios que provee Openpay como se especifica en la “documentación”, recordando usar siempre las llaves de acceso que se obtuvo en el paso anterior.

Cualquier par de llaves que se provean a los integradores podrán realizar las siguientes operaciones:

¡¡Listo!! Ya puedes empezar a integrar comercios a tu plataforma y procesar los cargos mediante Openpay.

Errores en el proceso de autorización

Durante el proceso de autenticación, si no se forma correctamente la URI para solicitar al proveedor de servicios la autorización del cliente, se podría mostrar una pagina de error:

Mensaje

Causa

Error en protocolo OAuth

Es posible que faltara algún parámetro o internamente hubo un problema en el protocolo OAuth

URI usada para el redirect es inválida

No se ha proporcionado el parámetro “redirect_uri” en la petición.

Petición inválida para solicitar acceso al servicio de autorización.

La petición esta malformada o algún parámetro no fue enviado.

El client_id de la empresa aliada es inválido.

No se ha proporcionado el parámetro “client_id” en la petición.

La empresa no esta autorizada.

El “id_client” no existe o el integrador aún no ha sido autorizado.

El tipo de autorización no esta soportada.

No se ha proporcionado el parámetro “grant_type” en la petición o es un valor invalido.

Permisos no soportados.

Los permisos que envía en el parámetro “scope” de la petición son invalidos.

URI usada para el redirect es inválida.

La uri proporcionada no esta bien formada.

Tipo de respuesta no soportada.

El valor del parámetro “response_type” es inválido y no esta soportado.

Acceso denegado.

No se tienen permisos para accesar al recurso solicitado.

El comercio que intenta registrar, ya existe.

El comercio que ha enviado el formulario de registro ya tiene una cuenta activa en Openpay.

Error en el proceso para registrar al nuevo comercio. Información inválida, verifique sus datos.

No se han completado todos los campos del formulario de registro.

Errores al obtener token o información del comercio

Durante el proceso para obtener el token de acceso y/o el consumo del servicio para obtener la información del comercio, es posible que el protocolo regrese alguno de los siguientes errores:

Como parte de la respuesta de error, se regresarán 2 parámetros:

  • error: Código de error.
  • errorrror_description: Descripción del error con información adicional.

Códigos de error:

Mensaje

Causa

unsupported_response_type

Tipo de respuesta no compatible

invalid_client_id

Identificador de cliente no válido

invalid_request

HTTPS necesario o se debe utilizar HTTP POST

invalid_client_credentialst

Secreto de cliente no válido

invalid_grant

Código de autorización no válido

redirect_uri_mismatcht

Uri de redirección no proporcionada o no coincidente con la url definida en el registro del integrador.

inactive_user

El administrador ha definido al usuario como inactivo

rate_limit_exceeded

Se ha superado el número de intentos de inicio de sesión