🛠️Implementación de split
¡Divide pagos automáticamente entre varios usuarios de forma segura y eficiente!
⚙️Implementación de servicios
Para implementar el Split de pagos debes seguir los siguientes pasos:
1️⃣ Integra uno de los servicios Payphone:
Integra correctamente el Botón de Pagos 🖱️, la Cajita de Pagos 📦 o el Link de Pagos 🔗 a través de nuestra API.
¡Sigue nuestras guías al pie de la letra! Esto incluye configurar tu aplicación en Payphone Developer, preparar la transacción y confirmarla.
2️⃣ Agrega el parámetro transferTo
Al método seleccionado se debe agregar un nuevo parametro llamado "transferTo", Este parámetro es un objeto JSON 🔒 encriptado con AES 256 CBC sin vector de inicialización.
El objeto JSON tiene la siguiente estructura:
[
{
"Identifier": "+593999999999",
"Type": 4,
"Amount":"100"
},
{
"Identifier": "0123456789001",
"Type": 3,
"Amount":"100"
}
]
📄Descripción de los campos :
Type: es un valor entero
- 3 : para indicar q el campo Identifier recibe como valor un número de identificación del comercio
- 4 : para indicar q el campo Identifier recibe como valor un número de teléfono
Identifier: identificador de usuario de Payphone Business o Payphone Personal
- Número de Identificación: en este campo se indica el identificador de un usuario de Payphone Business, puede ser RUC(019041XXXX001) o CI (019041XXXX) o el identificador con el cual el comercio se registro.
- Número de teléfono: en este campo se indica el identificador de un usuario de Payphone Personal.
Formato: Símbolo(+) + Código País + número telefónico. Ej. +59398XXXXXXX
Amount: es el valor que se pagará al actor registrado.
- Número Entero: Los valores monetarios deben expresarse en enteros. Es decir, se multiplica el valor en dólares por 100
- Límite de monto: el valor que se pagará al actor registrado no debe pasar el monto total a cobrar y se debe tener en cuenta el valor de comisión del 5.75% que se descuenta al pagar con tarjeta.
Si al dividir el pago entre usuarios Payphone se supera el valor cobrado se usará el saldo disponible en la wallet del comercio.
🔒Encriptación de objeto JSON:
Para utilizar el servicio de split de pagos es necesario que el valor del campo transferTo esté encriptado para posteriormente enviarlo en la solicitud.
Utiliza el algoritmo de encriptación AES 256 CBC sin vector de inicialización para cifrar el objeto JSON antes de enviarlo en la solicitud.
- Clave de Encriptación: Consulta la clave de encriptación específica en la configuración de Payphone Developer.
🧱 Ejemplo encriptación:
<!DOCTYPE html>
<html lang="es">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Encriptacion AES 256 CBC</title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/aes.js"></script>
</head>
<body>
<h1>Encriptacion AES 256 CBC sin vector de inicializacion</h1>
<div><a>Objeto JSON: <pre id="objetJSON"></pre></a></div>
<div><a>Valor Encriptado : <strong id="result"></strong></a></div>
<script>
//funcion que encripta en AES 256 CBC sin vector de inicializacion
function encrypted_aes(objet) {
const key = CryptoJS.enc.Utf8.parse('your_coding_password');
const iv = CryptoJS.enc.Utf8.parse('');
const encrypted = CryptoJS.AES.encrypt(objet, key,{ iv: iv });
const result_aes = encrypted.ciphertext.toString(CryptoJS.enc.Base64);
return result_aes;
}
let objetJSON=[
{
"Identifier":"+593999999999",
"Type": 4,
"Amount": 500
},
{
"Identifier": "0123456789001",
"Type": 3,
"Amount": 442
}
];
//ejecutar funcion de encriptacion para obtener transferTo
let myTransferTo=encrypted_aes(JSON.stringify(objetJSON));
//se muestra resultados
document.getElementById("objetJSON").innerHTML=JSON.stringify(objetJSON, null, 2);
document.getElementById("result").innerHTML=myTransferTo;
console.log("Valor Encriptado : "+myTransferTo);
</script>
</body>
</html>
<?php
//funcion que encripta en AES 256 CBC sin vector de inicializacion
function encrypt($object) {
error_reporting(E_ERROR | E_PARSE | E_NOTICE);
$encrypted = base64_encode(openssl_encrypt($object,'AES-256-CBC',"your-coding-password",OPENSSL_RAW_DATA,""));
error_reporting(E_ALL);
return $encrypted;
}
//Objeto JSON que contiene los usuarios y los montos a dividir
$objetJSON=array(
array(
"Identifier"=> "+593984112233",
"Type"=> 4,
"Amount"=>500
),
array(
"Identifier"=> "0123456789001",
"Type"=> 3,
"Amount"=>442
)
);
//ejecutar funcion de encriptacion para obtener transferTo
$transferTo=encrypt(json_encode($objetJSON));
//se muestra resultados
echo "<h1>Encriptacion AES 256 CBC sin vector de inicializacion</h1>";
echo "Respuesta : <pre>".json_encode($objetJSON,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
echo "<a>Valor Encriptado : <strong>$transferTo</strong></a>";
?>
🚀Generación de transacciones con Split:
Una vez implementados estos pasos, el comercio podrá generar transacciones utilizando la división de montos con el parámetro transferTo, para esto se debe realizar una solicitud HTTP POST normal a cualquiera de nuestros servicios pero esta vez cuenta con la funcionalidad de split.
Las url de los endpoint y cabeceras necesarias serán los mismo que se especifican en la documentación de cada servicio.
Lo único que cambiará es la configuración del cuerpo de la solicitud.
Estructura del Cuerpo de la Solicitud:
El cuerpo de la solicitud debe ser un objeto JSON similar al que estas utilizando en el servicio seleccionado de Payphone donde se indica montos y demás información para la transacción, pero se debe agregar el nuevo parámetro transferTo como se muestra en el ejemplo a continuación:
{
"amount": 315,
"amountWithoutTax": 200,
"amountWithTax": 100,
"tax": 15,
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"currency": "USD",
"storeId": "your_storeId",
"reference": "Pago con Boton",
"responseUrl":"https://tu-dominio.com/ConfirmacionPago",
"transferTo": "{{JSON_encriptado}}"
}
<script>
window.addEventListener('DOMContentLoaded',()=>{
ppb = new PPaymentButtonBox({
token: 'ACA TU TOKEN',
clientTransactionId: 'ID_UNICO_X_TRANSACCION-001',
amount: 315,
amountWithoutTax: 200,
amountWithTax:100,
tax: 15,
currency: "USD",
storeId:"TU_STOREID",
reference:"Pago por venta Fact#001",
transferTo: "{{encriptado}}"
}).render('pp-button');
})
</script>
{
"amount": 315,
"amountWithoutTax": 200,
"amountWithTax": 100,
"tax": 15,
"clientTransactionId": "ID_UNICO_X_TRANSACCION-001",
"currency": "USD",
"storeId": "your_storeId",
"reference": "Pago con API Link",
"transferTo": "{{JSON_encriptado}}"
}
Proceso de pago: Con esto solo queda seguir el proceso normal de pago.
- El cliente realice el pago normalmente desde uno de los servicios Payphone pero esta vez dispone con la funcionalidad de split de pagos.
- Si la transacción es aprobada, Payphone realiza el la división de los montos de acuerdo con las configuraciones indicadas.
🧱 Ejemplos de solicitudes POST con split de pagos
A continuación, se presenta varios ejemplos de cómo realizar solicitudes POST con split de pagos:
<?php
//Funcion q ejecuta una solicitud http POST
function curlPost($urlAPI, $headers,$body) {
//Iniciar solicitud curl: POST
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $urlAPI);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
//Respuesta en formato JSON
$curl_response = curl_exec($curl);
//Finaliza solicitud curl: POST
curl_close($curl);
return json_decode($curl_response);
}
// funcion de encriptacion en AES 256 CBC sin vector de inicializacion
function encrypt($objet) {
error_reporting(E_ERROR | E_PARSE | E_NOTICE);
$encrypted = base64_encode(openssl_encrypt($objet,'AES-256-CBC',"your_coding_password",OPENSSL_RAW_DATA,""));
error_reporting(E_ALL);
return $encrypted;
}
/*## Preparar credenciales como variables para la solicitud ##*/
$token="your_token";
$storeId="your_storeID";
/*## Preparar Datos para la transaccion ##*/
//Genera Dato Unico por transaccion
$clientTransactionID = substr((date("ymd-Hi-s").gettimeofday()["usec"]),0, 16);
//monto total a cobrar
$totalAmount=1000;
//valor dividir entre usuarios: monto total - 5.75% de comision.
//Ej: De $10 menos el porcentaje de comision, el valor que se podria dividir es $9.42
$amountUser1=500; //montos entregado a usuario 1
$amountUser2=442; //montos entregado a usuario 2
//Objeto JSON que contiene los usuarios y los montos a dividir
$objetJSON=array(
array(
"Identifier"=> "+593999999999",
"Type"=> 4,
"Amount"=>$amountUser1
),
array(
"Identifier"=> "0123456789001",
"Type"=> 3,
"Amount"=>$amountUser2
)
);
//ejecutar funcion de encriptacion para obtener transferTo
$transferTo=encrypt(json_encode($objetJSON));
/*## Preparar informacion para la solicitud POST ##*/
//URL del servicio payphone
$url="https://pay.payphonetodoesposible.com/api/button/Prepare";
//Preparar cabecera para la solicitud
$headers[] = "Authorization: Bearer ".$token ;//CREDENCIALES DE CONFIGURACION
$headers[] = "Content-Type: application/json" ;//TIPO DE APLICACION
//Preparar objeto JSON para solicitud
$data = array(
"amount"=> $totalAmount, //monto total a cobrar, debe ser igual a la suma de los montos individuales
"amountWithoutTax"=> $totalAmount, //Monto que no está sujeto a impuestos.
//Identificador único asignado por el comercio a cada transacción para su seguimiento.
"clientTransactionId"=> $clientTransactionID, //
"currency"=> "USD", //Código de moneda ISO 4217. (ej:USD)
"storeId"=> $storeId, //Identificador de la tienda que efectúa el cobro
"reference"=> "Pago con Boton", //Motivo o referencia específica del pago.
"responseUrl"=>"https://tu-dominio.com/ConfirmacionPago",
"transferTo"=> $transferTo
);
$bodyJSON = json_encode($data); //objeto de tipo JSON
//realizar solicitud http POST
$result=curlPost($url, $headers,$bodyJSON);
//Mostrar Resultado en Pantalla
echo "<h1>Prueba de Transaccion con split</h1> <br>";
echo "Cuerpo Solicitud : <pre>".json_encode($data,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
echo "Valores a Dividir: <pre>".json_encode($objetJSON,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
echo "Respuesta : <pre>".json_encode($result,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
echo "<br>";
if(isset($result->payWithCard)){
echo "PAGAR CON TARJETA : <a href='".$result->payWithCard."'>CLIC AQUI</a>";
}
?>
<html lang="es">
<head>
<meta charset="utf-8">
<title>Split con Cajita de pagos</title>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/aes.js"></script>
<script src="https://cdn.payphonetodoesposible.com/box/v1.1/payphone-payment-box.js" type="module" ></script>
<link href="https://cdn.payphonetodoesposible.com/box/v1.1/payphone-payment-box.css" rel="stylesheet" >
</head>
<body>
<h1>Split con Cajita de pagos</h1>
<div style="display: flex;">
<div style="padding-right: 20px;border: 1px solid;">
<a>Valor a Cobrar : <strong id="monto"></strong></a><br>
<a>Valores a Dividir : <pre id="objetJSON"></pre></a>
</div>
<div>
<a>PAGAR CON CAJITA</a><br>
<div id="pp-button"></div>
</div>
</div>
<script>
//funcion que encripta en AES 256 CBC sin vector de inicializacion
function encrypted_aes(objet) {
const key = CryptoJS.enc.Utf8.parse('your_coding_password');
const iv = CryptoJS.enc.Utf8.parse('');
const encrypted = CryptoJS.AES.encrypt(objet, key,{ iv: iv });
const result_aes = encrypted.ciphertext.toString(CryptoJS.enc.Base64);
return result_aes;
}
/*## Preparar credenciales como variables para la solicitud ##*/
const myToken="your_token";
const myStoreId="your_storeID";
/*## Preparar Datos para la transaccion ##*/
//Genera Dato Unico por transaccion
let fecha = new Date();
let myClientTransactionId=fecha.toISOString()+"-5";
//monto total a cobrar
let totalAmount=1000;
//valor dividir entre usuarios: monto total - 5.75% de comision.
//Ej: De $10 menos el porcentaje de comision, el valor que se podria dividir es $9.42
let amountUser1=500; //montos entregado a usuario 1
let amountUser2=442; //montos entregado a usuario 2
//Objeto JSON que contiene los usuarios y los montos a dividir
let objetJSON=[
{
"Identifier":"+593999999999",
"Type": 4,
"Amount": amountUser1
},
{
"Identifier": "0123456789001",
"Type": 3,
"Amount": amountUser2
}
];
//ejecutar funcion de encriptacion para obtener transferTo
let myTransferTo=encrypted_aes(JSON.stringify(objetJSON));
window.addEventListener('DOMContentLoaded',()=>{
ppb = new PPaymentButtonBox({
token: myToken, //credenciales de acceso, se genera en payphone developer
//Identificador único asignado por el comercio a cada transacción para su seguimiento.
clientTransactionId: myClientTransactionId,
amount: totalAmount, // Valor total de la factura a cobrar
amountWithoutTax: totalAmount, //Monto que no está sujeto a impuestos.
currency: "USD", //Código de moneda ISO 4217. (ej:USD)
storeId: myStoreId, //Identificador único asignado a la transacción para su seguimiento.
reference:"Pago por venta Fact#001", //Motivo o referencia específica del pago.
transferTo: myTransferTo
}).render('pp-button');
})
// Mostrar en pnatalla datos relevantes
document.getElementById("monto").innerHTML="$"+Math.round(totalAmount/100); //Monto a cobrar
document.getElementById("objetJSON").innerHTML=JSON.stringify(objetJSON, null, 2); //montos a dividir
</script>
</body>
</html>
<?php
//Funcion q ejecuta una solicitud http POST
function curlPost($urlAPI, $headers,$body) {
//Iniciar solicitud curl: POST
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $urlAPI);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
//Respuesta en formato JSON
$curl_response = curl_exec($curl);
//Finaliza solicitud curl: POST
curl_close($curl);
return json_decode($curl_response);
}
// funcion de encriptacion en AES 256 CBC sin vector de inicializacion
function encrypt($objet) {
error_reporting(E_ERROR | E_PARSE | E_NOTICE);
$encrypted = base64_encode(openssl_encrypt($objet,'AES-256-CBC',"your_coding_password",OPENSSL_RAW_DATA,""));
error_reporting(E_ALL);
return $encrypted;
}
/*## Preparar credenciales como variables para la solicitud ##*/
$token="your_token";
$storeId="your_storeID";
/*## Preparar Datos para la transaccion ##*/
//Genera Dato Unico por transaccion
$clientTransactionID = substr((date("ymd-Hi-s").gettimeofday()["usec"]),0, 15);
//monto total a cobrar
$totalAmount=1000;
//valor dividir entre usuarios: monto total - 5.75% de comision.
//Ej: De $10 menos el porcentaje de comision, el valor que se podria dividir es $9.42
$amountUser1=500; //montos entregado a usuario 1 : $5
$amountUser2=442; //montos entregado a usuario 2 : $4.42
//Objeto JSON que contiene los usuarios y los montos a dividir
$objetJSON=array(
array(
"Identifier"=> "+593999999999",
"Type"=> 4,
"Amount"=>$amountUser1
),
array(
"Identifier"=> "0123456789001",
"Type"=> 3,
"Amount"=>$amountUser2
)
);
//ejecutar funcion de encriptacion para obtener transferTo
$transferTo=encrypt(json_encode($objetJSON));
/*## Preparar informacion para la solicitud POST ##*/
//URL del servicio payphone
$url="https://pay.payphonetodoesposible.com/api/Links";
//Preparar cabecera para la solicitud
$headers[] = "Authorization: Bearer ".$token ;//CREDENCIALES DE CONFIGURACION
$headers[] = "Content-Type: application/json" ;//TIPO DE APLICACION
//Preparar objeto JSON para solicitud
$data = array(
"amount"=> $totalAmount, //monto total a cobrar, debe ser igual a la suma de los montos individuales
"amountWithoutTax"=> $totalAmount, //Monto que no está sujeto a impuestos.
//Identificador único asignado por el comercio a cada transacción para su seguimiento.
"clientTransactionId"=> $clientTransactionID, //
"currency"=> "USD", //Código de moneda ISO 4217. (ej:USD)
"storeId"=> $storeId, //Identificador de la tienda que efectúa el cobro
"reference"=> "Pago con Boton", //Motivo o referencia específica del pago.
"transferTo"=> $transferTo
);
$bodyJSON = json_encode($data); //objeto de tipo JSON
//realizar solicitud http POST
$result=curlPost($url, $headers,$bodyJSON);
//Mostrar Resultado en Pantalla
echo "<h1>Prueba Link de pago con split</h1>";
echo "Cuerpo Solicitud : <pre>".json_encode($data,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
echo "Valores a Dividir: <pre>".json_encode($objetJSON,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
if(is_string($result)){
echo "<h3>Link creado</h3>";
echo "<a>".$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>";
}
?>
¡Recuerda la Confirmación! ✅
En el caso del Botón y la Cajita de Pagos, ¡no olvides realizar la confirmación de la transacción tal como se indica en la documentación!
¡Y eso es todo! Si has llegado a este punto, ¡felicidades! Tu integración está completada. En la siguiente sección, te explicaremos cómo visualizar las transacciones con split de pagos desde Payphone Business.
