Implementación del API
POST API Sale
Para cobrar a través de la aplicación de Payphone, usa API SALE, que te permite solicitar el pago y verificar el estado de la transacción.
URL de la solicitud POST
https://pay.payphonetodoesposible.com/api/Sale
Cabeceras Requeridas:
Authorization: bearer TU_TOKEN (Token de autenticación de la aplicación, precedido por la palabra "Bearer").Content-type: application/json (Formato de los datos: JSON).
Estructura del Cuerpo de la Solicitud:
El cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:
//Ejemplo completo de un cobro mixto: 1 USD con impuesto del 15% y 2 USD sin impuesto
{
"phoneNumber": "0984111222", //Número de teléfono registrado en payphone
"countryCode": "593",//codigo de pais
"amount": 315,//Valor total a cobrar
"amountWithoutTax": 200,//Monto que NO está sujeto a impuestos.
"amountWithTax": 100,//Monto que esta sujeto a impuestos, excluyendo el propio impuesto.
"tax": 15, //Monto del impuesto aplicado a la transacción.
"service": 0,//cobro por servicio
"tip": 0,//cobro por propina
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001", //id unico proporcionado por el comercio
"reference": "Motivo de cobro con Sale", // referencia de pago
"storeId": "your_storeId",//identificador de tienda
"currency": "USD", // tipo de moneda
"timeZone": -5, //Zona horaria
"lat": "-1.831239", //latitud en formato decimal
"lng": "-78.183406", //longitud en formato decimal
"clientUserId": "idUserClient.001", //Identificador del usuario generado por comercio
"optionalParameter1": "Informacion Adicional 1", //Parámetro opcional 1
"optionalParameter2": "Informacion Adicional 2", //Parámetro opcional 2
"optionalParameter3": "Informacion Adicional 3", //Parámetro opcional 3
"responseUrl": "https://your_domain.com/webhook/resultParameters",
//URL de respuesta donde nuestro servidor adjunta 2 parametros id y clientTransactionID
"order": {
"billTo": { //datos de facturacion
"billToId": 12,
"address1": "Colorado Springs",
"address2": "Denver",
"country": "EC",
"state": "Azuay",
"locality": "Cuenca",
"firstName": "Elisabeth",
"lastName": "Sobeck",
"phoneNumber": "+593999999999",
"email": "aloy@mail.com",
"postalCode": "EC090108",
"customerId": "idUserClient.001",
"ipAddress": "127.0.0.1"
},
"lineItems": [ //datos de productos o servicios
{
"productName": "Producto Vendido",
"unitPrice": 100,
"quantity": 1,
"totalAmount": 115,
"taxAmount": 15,
"productSKU": "3342.0004",
"productDescription": "Descripción Producto"
}
]
}
}
Importante:
*Cálculo del amount:
Recuerda que el campo amount (valor a cobrar) debe ser la suma de los campos amountWithTax, amountWithoutTax, tax, service y tip.
amount = amountWithoutTax + amountWithTax + tax + service + tip
Aunque los montos individuales son opcionales, al menos uno debe estar presente para respaldar el campo amount
*Valores Monetarios:
Todos los valores monetarios deben expresarse en enteros. Es decir, se multiplica el valor en dólares por 100. Por ejemplo:
$1 dólar = 100
$1.50 dólares = 150
$10 dólares = 1000
$12.68 dólares = 1268
Ejemplos de solicitudes mínimas
A continuación, se muestran ejemplos de objetos JSON con los campos mínimos para diferentes tipos de cobro:
//Ejemplo de cobro de 1 USD con impuesto del 15%
{
"phoneNumber": "0984111222", //Número de teléfono registrado en payphone
"countryCode": "593",//codigo de pais
"amount": 115,//Valor total a cobrar
"amountWithTax": 100,//Monto que esta sujeto a impuestos, excluyendo el propio impuesto.
"tax": 15, //Monto del impuesto aplicado a la transacción.
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001", //id unico proporcionado por el comercio
"reference": "Motivo de cobro con Sale", // referencia de pago
"storeId": "your_storeId",//identificador de tienda
"currency": "USD" // tipo de moneda
}
Esta estructura permite una flexibilidad completa para manejar transacciones con impuestos, sin impuestos o mixtas, adaptándose a las necesidades del comercio.
//Ejemplo de cobro de 2 USD sin impuesto
{
"phoneNumber": "0984111222", //Número de teléfono registrado en payphone
"countryCode": "593",//codigo de pais
"amount": 200,//Valor total a cobrar
"amountWithoutTax": 200,//Monto que NO está sujeto a impuestos.
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001", //id unico proporcionado por el comercio
"reference": "Motivo de cobro con Sale", // referencia de pago
"storeId": "your_storeId",//identificador de tienda
"currency": "USD" // tipo de moneda
}
//Ejemplo de un cobro mixto: 1 USD con impuesto del 15% y 2 USD sin impuesto
{
"phoneNumber": "0984111222", //Número de teléfono registrado en payphone
"countryCode": "593",//codigo de pais
"amount": 315,//Valor total a cobrar
"amountWithoutTax": 200,//Monto que NO está sujeto a impuestos.
"amountWithTax": 100,//Monto que esta sujeto a impuestos, excluyendo el propio impuesto.
"tax": 15, //Monto del impuesto aplicado a la transacción.
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001", //id unico proporcionado por el comercio
"reference": "Motivo de cobro con Sale", // referencia de pago
"storeId": "your_storeId",//identificador de tienda
"currency": "USD" // tipo de moneda
}
Descripción de parámetros en la petición
A continuación se detallan los parámetros que puedes utilizar en una transacción, incluyendo los montos a cobrar, la moneda, los datos del cliente y otros campos opcionales que puedes incluir en la solicitud
Número de teléfono registrado en Payphone (ej: 0984111222)
Código de país estándar E.164 (ej: 593)
Valor total a cobrar. Debe ser igual a la suma de todos los montos individuales
Monto que no está sujeto a impuestos.
Monto que incluye el valor sujeto a impuestos, excluyendo el propio impuesto.
Monto del impuesto aplicado a la transacción.
Monto asociado al servicio proporcionado.
Monto de la propina otorgada por el cliente.
Código de moneda ISO 4217. (ej:USD)
Identificador único asignado a la transacción para su seguimiento.
Identificador de la sucursal que efectúa el cobro (se obtiene en Payphone Developer).
Motivo o referencia específica del pago.
Url de respuesta donde nuestro servidor envía dos parámetros: id, clientTransactionID
latitud en formato decimal: -1.831239
longitud en formato decimal: -78.183406
Información adicional para la transacción.
Información adicional para la transacción.
Información adicional para la transacción.
Identificador del cliente otorgada por el comercio
Arreglos con datos de facturación y detalle de artículos o servicios.
Descripción del campo Order
El campo order se divide en dos arreglos principales: BillTo y LineItems
BillTo:
El campo billTo es un arreglo que contiene la información de facturación asociada a la transacción.
Identificador para los datos de facturación (Opcional)
Dirección de facturación 1
Dirección de facturación 2
El código de país según la norma ISO 3166-1 alfa-2.
(EJ: EC)
Número de teléfono del titular; se solicitará si no se proporciona.
Formato: Símbolo(+) + Código País + numero telefónico.
Ej. +593984111222
Correo electrónico del cliente.
Código Postal: dirección numérica de un lugar específico.
Identificador del cliente otorgada por el comercio
Dirección IP del dispositivo
LineItems:
El campo lineItems es un conjunto de arreglos que contiene la información de los servicios o productos entregados
Nombre del producto o servicio
Total a pagar por este servicio
Identificador del producto o servicio
Descripcion corta del producto
Nota:
Campos obligatorios: Aunque muchos de los campos son opcionales, algunos parámetros como phoneNumber, countryCode, amount, currency y clientTransactionId son necesarios para procesar una transacción correctamente.
Formato de datos: Asegúrate de seguir el formato de datos especificado para cada campo.
Respuesta a la solicitud POST
Al realizar la solicitud POST, recibirás una respuesta en formato JSON con la siguiente estructura:
Respuesta exitosa
{
"transactionId": 45441137
}
En caso de éxito, la respuesta incluirá el campo transactionId, que es un identificador único para la transacción. Este identificador te permitirá consultar el estado de la transacción, el cual puede ser uno de los siguientes: Pendiente, Aceptado o Cancelado.
Respuesta de error
Si la transacción no se puede crear, recibirás una respuesta de error con la siguiente estructura:
{
"message": "La transacción no pudo ser creada por favor inténtelo de nuevo",
"errorCode": 22,
"errors": [
{
"message": "El cliente tiene transacciones pendientes con su local",
"errorCode": 2061
}
]
}
Al manejar errores, muestra al usuario el mensaje específico contenido en el arreglo errors, en lugar del mensaje general. Por ejemplo, deberías mostrar "El cliente tiene transacciones pendientes con su local" en lugar de "La transacción no pudo ser creada por favor inténtelo de nuevo".
Notificación en la aplicación de Payphone del usuario
Después de enviar la solicitud POST, el proceso para el usuario de Payphone continúa de la siguiente manera:
- El usuario de Payphone recibe una notificación push en su aplicación móvil.
- La notificación contiene los detalles de la transacción, incluyendo el monto a pagar y el comercio solicitante.
- Al abrir la notificación, el usuario puede seleccionar su método de pago preferido.
- Para confirmar el pago, el usuario debe autenticarse utilizando uno de los métodos biométricos o de seguridad (Huella dactilar, Reconocimiento facial o Contraseña)
Aviso:
La solicitud de pago desde la aplicación Payphone tiene una ventana de tiempo de 5 minutos para completarse. Si transcurre este tiempo, la solicitud expirará y la transacción será cancelada
Uso del campo responseUrl (Webhook)
Si configuras el campo responseUrl en la solicitud inicial, nuestro servidor enviará una respuesta a esa URL con dos parámetros:
id: Identificador de la transacciónclientTransactionID: Identificador de la transacción proporcionado por el comercio
Esta respuesta solo se enviará en dos casos de acción:
- Cuando el usuario aprueba el pago
- Cuando el usuario rechaza el pago
Es importante que tu servidor esté preparado para recibir y procesar esta respuesta en la URL especificada.
