Api PayPhone | Cobro por app

¡Bienvenido! en este tutorial vas a conocer el Api de PayPhone para cobro por app. Su implementación te ayudará para ampliar los canales de cobro a tus clientes. Con el app de PayPhone puedes recibir pagos desde:

  • Tarjetas de crédito, Visa y Mastercard de cualquier país del mundo.
  • Tarjetas de débito, Visa y Mastercard de cualquier país del mundo.
  • Tarjetas de regalo.
  • Saldo PayPhone de tus clientes.

El api PayPhone se compone de un servicio web REST, una llamada POST en la que debes enviar una estructura json y una llamada GET de consulta de estado.

El flujo de la integración por Api es la siguiente:

  1. Envías el cobro (indicas a PayPhone los datos del cliente, el valor a cobrar, impuestos y datos generales de la transacción) mediante una llamada POST.
  2. PayPhone muestra notificación al cliente en su app. El servicio POST te responde un transactionID.
  3. Debes consultar cada x tiempo el estado de la transacción mediante nuestro servicio web de tipo GET, el estado puede ser Pendiente, Aprobado o Rechazado, de acuerdo con la acción del cliente. Cuando te responda Aprobado o rechazado, significa que el cliente completo la transacción.

Configuraciones preliminares

Para implementar el botón de pagos debes cumplir los siguientes requisitos: Requisitos Comerciales y Requisitos de Desarrollo.

Requisitos Comerciales:

  • El establecimiento que va a recibir los pagos tiene que estar registrado en PayPhone como una tienda habilitada. Para iniciar el registro como PayPhone Business puedes hacer click aquí.
  • Con la tienda activa y lista para transaccionar, debes crear un usuario de tipo “desarrollador“, el cual te explicaremos más adelante.

Requisitos de Desarrollo:

  • Debes configurar en nuestro sitio web «PayPhone Developer» tu ambiente de desarrollo en donde podrás obtener todas tus credenciales, tokens y llaves con las que podrás identificarte en nuestros servicios y añadir la seguridad respectiva al proceso.

Crear usuario desarrollador

Ingresa en tu página PayPhone Business, e inicia sesión con el ruc, correo y contraseña, (si no tienes acceso el administrador de la empresa puede entrar y crear tu usuario) y dirígete a la sección de «Usuarios» a continuación selecciona «Crear Usuario»:

Ingresa todos los datos del desarrollador en el formulario, no olvides que en el campo «Roles» debes ingresar «Desarrollador». (El administrador debe entregar al desarrollador el correo electrónico y la contraseña ingresadas)

Selecciona la tienda o sucursal que recibirá los pagos y presiona el botón Guardar:

Con este proceso listo, el usuario desarrollador puede iniciar la implementación.

Configuración de ambiente

Configurar el ambiente de desarrollo te permite tener un control total sobre las transacciones efectuadas a través de PayPhone. Por favor sigue los siguientes pasos:

1. Iniciar sesión como desarrollador

Ingresa en la página https://appdeveloper.payphonetodoesposible.com/ e inicia sesión con las credenciales de tu usuario desarrollador (Ruc, correo y contraseña).

2. Crear Aplicación PayPhone:

Las aplicaciones de desarrollo PayPhone te permiten configurar los parámetros de implementación, como la plataforma, permisos o usuarios de prueba, y te ayuda a obtener tus credenciales de autenticación como el token.

Para crear tu aplicación haz click en  el “+”  de la parte superior:

Se abrirá un formulario donde debes ingresar los campos informativos.

Por último selecciona tu tipo de aplicación como API

Presiona Guardar

Con la aplicación configurada puedes obtener tu token de autenticación. En el menú superior haz click en credenciales, y tendrás el botón para copiar tu token.

Implementación del Api:

Nuestro Api dispone de diferentes servicios web, para realizar un cobro debes usar el método SALE ya que es el encargado de solicitar el pago a los clientes y verificar el estado de la transacción. El flujo de ejecución del método SALE es el siguiente:

  1. Llamada POST solicitando el pago: El pago con el app de PayPhone es rápido, seguro y cómodo, por su flujo claro y sencillo. El cliente confirma sus consumos desde su dispositivo móvil gracias a una solicitud del establecimiento; el método SALE nos ayuda a crear esta solicitud. Mediante una llamada POST indicamos al servicio de PayPhone los atributos de la transacción como el número de teléfono del cliente, el valor, los impuestos, entre otros. Todos los valores monetarios a enviar deben ir multiplicados por 100, por ejemplo, $1 dólar = 100; $1.50 dólares = 150. Recuerda siempre enviar los campos de acuerdo a tu tipo de facturación; AmountWithTax y Tax en caso de cobrar IVA  o AmountWithoutTax en caso de ser tarifa 0%. La llamada Sale la haces a la url https://pay.payphonetodoesposible.com/api/sale, no olvides adjuntar tu token de autenticación en la cabecera de la llamada, el tipo es «Authorization» y el contenido es «Bearer TUTOKEN«. La llamada es con un objeto del tipo Json que cuente con los siguientes parámetros:

phoneNumberStringXNúmero de teléfono del usuario que realiza el pago.phoneNumberStringXNúmero de teléfono del usuario que realiza el pago.

Nombre Tipo Opcional Descripción
phoneNumber String Número de teléfono del usuario que va a realizar el pago con su app PayPhone.
countryCode String Código de país del usuario que va a realizar el pago con su app PayPhone. Ej: 593 en Ecuador
amount Integer Valor total por cobrar al cliente
amountWithoutTax Integer X Valor del subtotal de los productos que no cobran impuestos. Solo se usa con tipo de facturación tarifa 0% o mixta.
amountWithTax Integer X Valor del subtotal de los productos que cobran impuestos sin sumar el valor de los impuestos. Solo se usa con tipo de facturación con IVA o mixta.
tax Integer X Valor total de los impuestos. Solo se usa con tipo de facturación con IVA o mixta.
service Integer X Valor del servicio
tip Integer X Valor de la propina
currency String X Moneda con la que se cobra, ejemplo “USD”.
clientTransactionId String Identificador de la transacción en la aplicación del cliente (String asignado por tu empresa  tu plataforma). Es un parámetro que sirve de identificación para consulta o reverso de la transacción.
StoreId String X Id del Store que va a cobrar, Este valor solo se envía cuando se manejan diferentes tiendas o sucursales, si no se usan diferentes tiendas se puede omitir. Para especificar que tienda hace el cobro, el storeID se obtiene desde la página web de PayPhone Developer, en la sección solicitud de compañía, columna Acciones, Listado de tiendas.
Reference String X Referencia de la transacción, por ejemplo “Venta Zapatos Azules”
OptionalParameter1 String X Parámetro opcional a tu disposición.
transferTo String X Parámetro para pagos compartidos. En el siguiente enlace puedes revisar como hacer pagos compartidos.

Ejemplos de Json método sale:

      • Cobro de $1 dólar sin impuestos al cliente con teléfono 0998457410:

{
«phoneNumber»: «0998457410»,
«countryCode»: «593»,
«amount»: 100,
«amountWithoutTax»: 100,
«clientTransactionId»: «idunicoapi01»
}

      • Cobro de $1.12, donde $1 dólar es el subtotal y $0.12 los impuestos al cliente con teléfono 0998457410::

{
«phoneNumber»: «0998457410»,
«countryCode»: «593»,
«amount»: 112,
«amountWithTax»: 100,
«tax»: 12,
«clientTransactionId»: «idunicoapi01»
}

Estos son los objetos base pero te recomendamos enviar la mayor cantidad de datos para que tengas mejor control.

La respuesta de la petición POST del método SALE es un objeto JSON con el parámetro transactionId:

{ «transactionId«: int }

Con ese transactionId, debes hacer una petición GET para obtener el estado de la transacción: Pendiente, Aprobado o Cancelado.

El Cliente recibe la notificación en su app de la siguiente forma, donde puede seleccionar su método de pago (Tarjeta de crédito, débito, tarjetas de regalo o saldo), confirma su identidad con su huella, rostro o contraseña y el pago se confirma:

 

2. Consultar estado de la transacción: Después de la ejecución de la llamada anterior PayPhone te entregara un identificador de transacción (transactionId) con el que podrás consultar en qué estado se encuentra el cobro realizado (Pendiente, Aceptado o Cancelado). Para esto debes hacer una llamada GET al servicio de PayPhone enviando como parámetro el transactionID. La llamada es a la misma url del método Sale, solo que en lugar de hacer una petición POST se hace una petición GET, enviando el transactionId: https://pay.payphonetodoesposible.com/api/sale

Puedes crear una rutina para que cada cierto tiempo tu plataforma consulte a PayPhone el estado de la transacción y según la respuesta le muestres al cliente el resultado. Como resultado obtienes un objeto Json con los siguientes parámetros:

 

Nombre Descripción
statusCode Código de estado de la transacción. 2=Cancelado.03=Aprobada
transactionStatus Estado de la transacción.
clientTransactionId Identificador de transacción que tu enviaste en la petición.
authorizationCode Código de autorización bancario.
transactionId Identificador de transacción asignado por PayPhone.
email El correo electrónico empleado por el usuario para el pago.
phoneNumber Número de teléfono empleado por el usuario para el pago.
document Número de cédula empleado por el usuario para el pago.
amount Monto total pagado.
cardType Tipo de tarjeta empleada, puede ser crédito o débito.
cardBrandCode Código de la marca de la tarjeta.
cardBrand Marca de la tarjeta.
bin Primeros 6 dígitos de la tarjeta empleada.
lastDigits Últimos dígitos de la tarjeta empleada.
deferredCode Código de diferido empleado por el usuario. Aquí puedes conocer más de los diferidos.
deferredMessage Mensaje del diferido.
deferred Variable boleana que indica si se uso un diferido o no.
message En caso de error se muestra el error en este parámetro. Puedes consultar el catálogo de errores haciendo click aquí.
messageCode Código de mensaje.
currency Moneda empleada para el pago.
taxes Arreglo con todos los impuestos pagados, con los campos: («name»,»amount», «value», «tax»)
recap Parámetro de identificación bancario.
optionalParameter1 Parámetro opcional

¡Y Listo! Con la petición y consulta tendrás implementado nuestro Api

Cabe recalcar que de aquí en adelante tienes dos identificadores para tu transacción, un transactionID entregado por PayPhone y un clientTransactionId que proporcionas tu en la primera llamada POST. Para las llamadas de cancelar, consulta, reverso o anulación puedes usar ya sea el transactionID o tu clientTransactionID.

Método Reverse: Con este método puedes reversar transacciones automáticamente en caso de que tu plataforma no confirme algún valor o que por seguridad el pago necesite ser reversado. Leer más

Nota: El campo StoreId  solo se envía cuando se manejan diferentes tiendas o sucursales, si no se usan diferentes tiendas se puede omitir. Para especificar que tienda hace el cobro el storeId se obtiene desde la página web de PayPhone Developer, en la sección solicitud de compañía, columna Acciones, Listado de tiendas.

Puedes consultar el catálogo de errores haciendo click aquí.

Leave A Comment?