Preparar la transacción
API Button/Prepare
Este método te permite preparar los montos que se va a cobrar en una transacción, así como información adicional que se necesite.
URL de la solicitud POST
https://pay.payphonetodoesposible.com/api/button/Prepare
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).
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
{
"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 Boton", // referencia de pago
"storeId": "your_storeId",//identificador de tienda
"currency": "USD", // tipo de moneda
"responseUrl": "https://your_domain.com/webhook/resultParameters",
//URL de respuesta a donde se redirecciona con 2 parametros id y clientTransactionID
"cancellationUrl": "https://tu-dominio.com/",
//URL de respuesta a donde se redirecciona si se anula la transaccion
"timeZone": -5, //Zona horaria
"lat": "-1.831239", //latitud en formato decimal
"lng": "-78.183406", //longitud en formato decimal
"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": [
{
"productName": "Producto Vendido",
"unitPrice": 100,
"quantity": 1,
"totalAmount": 115,
"taxAmount": 15,
"productSKU": "3342.0004",
"productDescription": "Descripción Producto"
},
{
"productName": "Servicio Entregado",
"unitPrice": 100,
"quantity": 2,
"totalAmount": 200,
"taxAmount": 0,
"productSKU": "5342.0054",
"productDescription": "Descripción Servicio"
}
]
},
"documentId": null,
"phoneNumber": null,
"email": null,
"optionalParameter": "Descripción Extra"
}
El objeto JSON mostrado define el cobro de $3.15, divididos en $1 con un impuesto del 15% y $2 sin impuesto.
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%
{
"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.
"responseUrl":"https://tu-dominio.com/ConfirmacionPago"
}
//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.
"responseUrl":"https://tu-dominio.com/ConfirmacionPago"
}
//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.
"responseUrl":"https://tu-dominio.com/ConfirmacionPago"
}
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 cobra, moneda, datos del cliente y otros campos que puedes enviar.
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.
Identificador de la sucursal que efectúa el cobro (se obtiene en payphone Developer).
Motivo o referencia específica del pago.
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; se solicitará si no se proporciona.
Número de identificación del cliente; se solicitará si no se proporciona.
Url de respuesta a donde se redirecciona luego del pago.
Url a donde se redirecciona si se cancela la transacción desde el icono X en el formulario.
Información adicional para la transacción.
Arreglos con datos de facturación y detalle de artículos o servicios.
Idioma de Formulario:
inglés (en),
español (es).
Por defecto en español.
latitud en formato decimal: -1.831239
longitud en formato decimal: -78.183406
Advertencia:
Al utilizar los campos phoneNumber, email y documentId en las solicitudes a los servicios de payphone, es crucial que se ingresen los datos del titular de la tarjeta para cada transacción individual. No se permite el uso de datos "quemados" o estáticos, ya que esto puede resultar en el rechazo de sus transacciones y el bloqueo de sus usuarios. El uso de datos falsos o repetitivos puede generar sospechas de fraude.
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.
Descripción de campo ORDER
El campo order se divide en dos arreglos: BillTo, LineItems
BillTo:
El campo billTo es un arreglo que contiene información de facturació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
Ejemplos de solicitud POST a Buttom/Prepare
A continuación, se presenta varios ejemplos 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 transacción
$clientTransactionID = substr((date("ymd-Hi-s").gettimeofday()["usec"]),0, 16);
//Preparar objeto JSON para solicitud
$data = array(
"amount" => 215,
"amountWithoutTax" => 100,
"amountWithTax" => 100,
"tax" => 15,
"service" => 0,
"tip" => 0,
"storeId" => "your_storeId",
"clientTransactionId" => $clientTransactionID,
"currency" => "USD",
"responseUrl" => "https://your_domain.com/confirm.php",
"reference" => "Prueba Boton por redireccion"
);
$objetoJSON = json_encode($data);
//Iniciar solicitud curl: POST
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://pay.payphonetodoesposible.com/api/button/Prepare");
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 Botón por redirección</h1> <br><br>";
$result= json_decode($curl_response);
if(isset($result->paymentId) ) {
echo "<a href='".$result->payWithPayPhone."'>PAGAR CON PAYPHONE</a> <br><br>";
echo "<a href='" .$result->payWithCard."'>PAGAR CON TARJETA VISA/MASTERCARD</a>";
}else{
echo "<pre>".json_encode($result,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
}
?>
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Solicitud POST con jQuery</title>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
<script>
//Genera un Dato Unico por transacción
const redirectClientTraxID =Date.now();
//Se realiza solicitud POST: Se prepara objeto JSON, header y presenta resultado o error
$(document).ready(function() {
$.ajax({
url: "https://pay.payphonetodoesposible.com/api/button/Prepare",
type: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer your_token"
},
data: JSON.stringify({
"amount": 155,
"amountWithoutTax": 155,
"amountWithTax": 0,
"tax": 0,
"reference": "Pago mediante Boton payphone",
"currency": "USD",
"clientTransactionId": redirectClientTraxID,
"storeId": "your_storeId",
"ResponseUrl": "https://your-domain.com/Confirm"
}),
success: function(response) {
$("#resultado").html(
"<a href='" + response.payWithPayPhone + "' target='_blank'>Pagar con payphone</a><br><br>" +
"<a href='" + response.payWithCard + "' target='_blank'>Pagar con Tarjeta Visa/MasterCard</a><br><br>"+
"Respuesta : <pre>" + JSON.stringify(response, null, 2) + "</pre>"
);
},
error: function(error) {
$("#resultado").html(
"Error en la solicitud : <pre>" + JSON.stringify(error, null, 2) + "</pre>"
);
}
});
});
</script>
</head>
<body>
<h1>Ejemplo de Solicitud POST</h1>
<div id="resultado"></div>
</body>
</html>
<!DOCTYPE html>
<html lang="es">
<head>
<title>Ejemplo de Solicitud POST con fetch</title>
<script>
//Genera un Dato Unico por transacción
const redirectClientTraxID =Date.now();
//Preparar cabecera para la solicitud
const headers = {
"Content-Type": "application/json",
"Authorization": "Bearer your_token",
"Referer": document.referrer
};
//Preparar objeto JSON para solicitud
const bodyJSON = {
"amount": 180,//monto total
"amountWithoutTax": 180,//monto que no cobrar impuestos
"amountWithTax": 0,//monto que cobrar impuestos excluido el impuesto
"tax": 0,//monto del impuestos
"reference": "Prueba Boton fetch", //motivo de transaccion opcional
"currency": "USD",//ISO DE MONEDA
"clientTransactionId": redirectClientTraxID,//id unico proporcionado por el comercio
"storeId": "your_storeId",
"ResponseUrl": "https://your-domain.com/Confirm"
};
//Iniciar solicitud: POST
const url = "https://pay.payphonetodoesposible.com/api/button/Prepare";
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(bodyJSON)
})
.then((res) => res.json())
.catch((error) => {
// Se crea etiqueta <pre> que contiene el error
const jsonResult = document.createElement("pre");
jsonResult.textContent = JSON.stringify(error, null, 2);
// Mostrar los enlaces en el documento con un salto de línea entre ellos
const container = document.createElement("div");
container.appendChild(jsonResult);
// Agregar los enlaces al body del documento o a un contenedor específico
document.body.appendChild(container);
})
.then((data) => {
// Se procesa la respuesta JSON
const payWithPayPhone = data.payWithPayPhone;
const payWithCard = data.payWithCard;
// Se crea etiquetas <a> con los enlaces hacia el formulario
const payWithPayPhoneLink = document.createElement("a");
payWithPayPhoneLink.href = payWithPayPhone;
payWithPayPhoneLink.textContent = "Pagar con PayPhone";
const payWithCardLink = document.createElement("a");
payWithCardLink.href = payWithCard;
payWithCardLink.textContent = "Pagar con Tarjeta Visa/MasterCard";
// Se crea etiqueta <pre> que contiene el json de respuesta
const jsonResult = document.createElement("pre");
jsonResult.textContent = JSON.stringify(data, null, 2);
// Mostrar los enlaces en el documento con un salto de línea entre ellos
const container = document.createElement("div");
container.appendChild(payWithPayPhoneLink);
container.appendChild(document.createElement("br")); // Salto de línea
container.appendChild(document.createElement("br")); // Salto de línea
container.appendChild(payWithCardLink);
container.appendChild(document.createElement("br")); // Salto de línea
container.appendChild(document.createElement("br")); // Salto de línea
container.appendChild(jsonResult);
// Agregar los enlaces al body del documento o a un contenedor específico
document.body.appendChild(container);
});
</script>
</head>
<body>
<h1>Ejemplo de Solicitud POST con Fetch</h1>
<div id="resultado"></div>
</body>
</html>
Respuesta a la solicitud POST
Al realizar la solicitud POST, recibirás un objeto JSON que incluye los siguientes parámetros:
- paymentId: Identificador del pago.
- payWithPayPhone: URL para redirigir al usuario a realizar el pago mediante la app de payphone.
- payWithCard: URL para que el usuario realice el pago directamente con su tarjeta de crédito o débito.
Consideraciones: Es importante tener en cuenta que los enlaces generados por el servicio tienen una ventana de tiempo de 10 minutos para ser utilizados. Pasado este lapso, el enlace expirará y será necesario generar uno nuevo.
Nota: Asegúrate de redirigir al usuario a la URL de pago desde tu dominio web configurado; de lo contrario, no se otorgará autorización.
Los clientes pueden pagar con tarjetas de crédito y débito Visa y Mastercard, así como con saldo payphone. Independientemente del método de pago, recibirás la misma respuesta de transacción, ya sea aprobada o rechazada.
.png)