Guía de Integración: Link de pagos por API
API Links
Este método te permite preparar los montos que se va a cobrar en una transacción, así como agregar información adicional que se necesite.
Para utilizar el método Links, debes realizar una solicitud POST a la siguiente URL:
https://pay.payphonetodoesposible.com/api/Links
Es fundamental incluir las siguientes cabeceras en la solicitud:
Authorization: bearer TU_TOKEN (Esta cabecera debe contener el token de autenticación de tu aplicación, precedido por la palabra “Bearer”).Content-type: application/json (Indica que el formato de los datos enviados en el cuerpo de la solicitud es JSON).
El cuerpo de la solicitud debe ser un objeto JSON con la siguiente estructura:
//JSON completo de un cobro mixto: 1 USD con impuesto del 15% y 2 USD sin impuesto
{
"amount": 315, //monto total a cobrar, debe ser igual a la suma de los montos individuales
"amountWithoutTax": 200, //Monto que no está sujeto a impuestos.
"amountWithTax": 100, //Monto sujeto a impuestos, excluyendo el propio impuesto.
"tax": 15, //Monto del impuesto aplicado a la transacción.
"service": 0, //Monto asociado al servicio proporcionado.
"tip": 0, //Monto de la propina otorgada por el cliente.
"currency": "USD", //Código de moneda ISO 4217. (ej:USD)
"reference": "Pago por API Link", //Motivo o referencia específica del pago.
//Identificador único asignado por el comercio a cada transacción para su seguimiento.
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"storeId": "your_storeId", //Identificador de la tienda que efectúa el cobro
"additionalData": "Descripción Extra", //Parámetros adicionales, acepta un json
"oneTime": true, //El enlace solo se puede pagar una vez, el pago debe ser aprobado
"expireIn": 0, //Cuando el enlace ya no esté disponible en horas
"isAmountEditable": true //si es link con monto editable, es necesario permisos
}
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
Con estas definiciones, podemos crear configuraciones básicas con solo ciertos campos en el cuerpo de la solicitud. Por ejemplo:
//Ejemplo de cobro de 1 USD con impuesto del 15%
{
"amount": 115, //Monto total a cobrar
"amountWithTax": 100, //Monto sujeto a impuestos, excluyendo el propio impuesto.
"tax": 15, //Monto del impuesto aplicado a la transacción.
//Identificador único asignado por el comercio a cada transacción para su seguimiento.
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001", //
"currency": "USD", //Código de moneda ISO 4217. (ej:USD)
"storeId": "your_storeId", //Identificador de la tienda que efectúa el cobro
"reference": "Pago con API Link", //Motivo o referencia específica del pago.
}
//Ejemplo de cobro de 2 USD sin impuesto
{
"amount": 200, //monto total a cobrar, debe ser igual a la suma de los montos individuales
"amountWithoutTax": 200, //Monto que no está sujeto a impuestos.
//Identificador único asignado por el comercio a cada transacción para su seguimiento.
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001", //
"currency": "USD", //Código de moneda ISO 4217. (ej:USD)
"storeId": "your_storeId", //Identificador de la tienda que efectúa el cobro
"reference": "Pago con API Link", //Motivo o referencia específica del pago.
}
//Ejemplo de un cobro mixto: 1 USD con impuesto del 15% y 2 USD sin impuesto
{
"amount": 315, //monto total a cobrar, debe ser igual a la suma de los montos individuales
"amountWithoutTax": 200, //Monto que no está sujeto a impuestos.
"amountWithTax": 100, //Monto sujeto a impuestos, excluyendo el propio impuesto.
"tax": 15, //Monto del impuesto aplicado a la transacción.
//Identificador único asignado por el comercio a cada transacción para su seguimiento.
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001", //
"currency": "USD", //Código de moneda ISO 4217. (ej:USD)
"storeId": "your_storeId", //Identificador de la tienda que efectúa el cobro
"reference": "Pago con API Link", //Motivo o referencia específica del pago.
}
Estos son los objetos 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.
Advertencia:
Para utilizar el campo isAmountEditable en las solicitudes a los servicios de payphone, es crucial que se tenga los permisos de montos editables activos.
Si no cuenta con estos permisos deberías comunicarte con soporte payphone.
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.
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.
Consideraciones: Recuerda que solo puedes realizar hasta 20 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 al formulario como 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.
