🛠️Guía de Integración: Link de pagos por API
Esta guía te mostrará cómo integrar los links de pago Payphone a tu sistema mediante nuestra API.
🧩 API Links
Para Preparar y generar link de pagos, debes realizar una solictud POST.
🔗 URL de la solicitud POST
https://pay.payphonetodoesposible.com/api/Links
📦 Estructura del Cuerpo de la Solicitud:
El cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:
{
"amount": 315,
"amountWithoutTax": 200,
"amountWithTax": 100,
"tax": 15,
"service": 0,
"tip": 0,
"currency": "USD",
"reference": "Pago por API Link",
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"storeId": "your_storeId",
"additionalData": "Descripción Extra",
"oneTime": true,
"expireIn": 0,
"isAmountEditable": false
}
Este JSON completo describe un cobro mixto: 1 USD con impuesto del 15% y 2 USD sin impuesto.
🔐 Es fundamental incluir las siguientes cabeceras en la solicitud:
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).
📌 Importante:
📟 Cálculo del monto total (amount)
El campo amount debe ser la suma de todos los valores monetarios
amount = amountWithoutTax + amountWithTax + tax + service + tip
Aunque los campos individuales son opcionales, debe haber al menos uno presente que respalde el valor total amount
💵 Valores monetarios en centavos:
Todos los montos deben expresarse como enteros. Multiplica el valor en dólares por 100:
| 💵 Valor en USD |
🪙 Valor en centavos |
| $ 1.00 |
100 |
| $ 1.50 |
150 |
| $ 10.00 |
1000 |
| $ 12.68 |
1268 |
🔸Ejemplos de cuerpos de solicitudes con campos mínimos
A continuación, se muestran ejemplos de objetos JSON con los campos mínimos para diferentes tipos de cobro:
Este objeto JSON define el cobro de $1 con un impuesto del 15%.
{
"amount": 115,
"amountWithTax": 100,
"tax": 15,
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"currency": "USD",
"storeId": "your_storeId",
"reference": "Pago con API Link"
}
El objeto JSON define el cobro de $2 sin impuesto.
{
"amount": 200,
"amountWithoutTax": 200,
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"currency": "USD",
"storeId": "your_storeId",
"reference": "Pago con API Link"
}
Este objeto JSON define el cobro de $3.15, divididos en $1 con un impuesto del 15% y $2 sin impuesto.
{
"amount": 315,
"amountWithoutTax": 200,
"amountWithTax": 100,
"tax": 15,
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"currency": "USD",
"storeId": "your_storeId",
"reference": "Pago con API Link"
}
Este objeto JSON define un link con monto editable.
{
"isAmountEditable": true,
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"currency": "USD",
"storeId": "your_storeId",
"reference": "Pago con API Link"
}
Estos son cuerpos JSON con parametros básicos, pero te recomendamos enviar la mayor cantidad de datos posibles para tener un mejor control.
📋Descripción de parámetros en la petición
A continuación, se detallan todos los parámetros que se pueden usar para una transacción, como montos a cobrar, moneda, datos del cliente y otros campos adicionales.
Valor total a cobrar. Debe ser igual a la suma de todos los montos individuales
( amountWithoutTax, amountWithTax, Tax, service y tip ).
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.
Longitud máxima 15 caracteres
Identificador de la sucursal que efectúa el cobro (se obtiene en Payphone Developer).
Referencia del pago que puedes enviar.
Controla si el enlace solo se paga una vez, el pago debe ser aprobado.
*true: Link funciona solo una vez,
*false: Link puede usarse varias veces.
Número de horas que estará disponible el link de pago.
Si deseas crear un link con monto editable. Es necesario tener los permisos habilitados.
Parámetros adicionales, acepta un JSON.
🛑 Aviso:
Para crear un link con monto editable utilizando el campo isAmountEditable en las solicitudes, es crucial que se tenga los permisos necesarios activos.
Si no cuenta con estos permisos debera comunicarte con soporte Payphone.
- 📧Email de Soporte: Clic Aqui
- 📲Soporte en Whatsapp: Contactar
Payphone se compromete a proteger la seguridad y privacidad de los datos, por lo que es fundamental cumplir con esta política para garantizar un proceso de pago seguro y confiable.
🧱 Ejemplos de Solicitud POST a API Links
A continuación, se presenta un ejemplo de cómo realizar solicitudes POST:
<?php
date_default_timezone_set('America/Guayaquil');
//Preparar cabecera para la solicitud
$headers[] = 'Authorization: Bearer your_token' ;//CREDENCIALES DE CONFIGURACION
$headers[] = 'Content-Type: application/json' ;//TIPO DE APLICACION
//Genera Dato Unico por transaccion
$clientTransactionID = substr((date("ymd-Hi-s").gettimeofday()["usec"]),0, 15);
//Preparar objeto JSON para solicitud
$data = array(
"amount" => 315,
"amountWithoutTax" => 200,
"amountWithTax" => 100,
"tax" => 15,
"storeId" => "your_storeId",
"clientTransactionId" => $clientTransactionID,
"currency" => "USD",
"reference" => "Pago con API Link"
);
$objetoJSON = json_encode($data);
//Iniciar solicitud curl: POST
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://pay.payphonetodoesposible.com/api/Links");
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $objetoJSON);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
//Respuesta en formato JSON
$curl_response = curl_exec($curl);
//Finaliza solicitud curl: POST
curl_close($curl);
//Mostrar Resultado en Pantalla
echo "<h1>Prueba con API Link</h1>";
$result= json_decode($curl_response);
if(is_string($result)){
echo "<h3>Link creado</h3>";
echo "<a href='$result' target='_blank'>".$result."</a><br><br>";
echo "<a href='$result' target='_blank'>PAGAR MEDIANTE LINK</a>";
}else{
echo "<pre>".json_encode($result,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
}
?>
📬Respuesta a la solicitud POST
Al realizar la solicitud POST, recibirás como respuesta un string que contiene el enlace hacia el formulario de pago, como se muestra a continuación.
Este enlace puede enviarse por cualquier medio de comunicación (correo, WhatsApp, Facebook, Instagram, SMS), mostrarse en tu sistema como un botón o transformarse en un código QR.
❌ Respuesta con error en la solicitud POST
Si algun campo no cumple con las reglas o formato en la solicitud POST, recibirás un objeto JSON que incluye el detalle del error:
{
"message": "Validaciones fallidas",
"errorCode": 800,
"errors": [
{
"message": "Amount",
"errorCode": 0,
"errorDescriptions": [
"El campo Amount no es igual a la suma de AmountWithTax, AmountWithoutTax, Tax, Service, Tip"
]
}
]
}
📌 Consideraciones
📨 Solicitudes POST
- Recuerda que solo puedes realizar hasta 30 solicitudes POST por minuto a la API Links.
- Es importante tener en cuenta que el formulario tiene una ventana de tiempo de 10 minutos para ser utilizado.
- Pasado este lapso, el formulario expirará y será necesario abrir nuevamente el enlace.
📝 Interfaz del formulario de link de pago
🔸El link de pago redirige a un formulario como el que se muestra a continuación:
🔸Cuando el cliente realice el pago, se mostrará el recibo de pago.
🔸Podrás revisar el pago realizado directamente en la plataforma Payphone Business.
¡Listo! Estos son todos los pasos para generar links de pago.
