🛠️Guía de Implementación de Pagos Masivos
🧩API StorePayments/transfer
Este método permite transferir montos a usuarios o comercios Payphone.
Para utilizarlo, debe realizar una solicitud POST como se muestra a continuación:
🔗 URL para la solicitud POST
https://pay.payphonetodoesposible.com/api/StorePayments/transfer
🔐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:
{
"currency":"USD",
"reference":"Referencia de Lote de pagos",
"paymentItems":"{{encriptado}}"
}
📄Descripción de los campos :
🔸Currency: Código de moneda ISO 4217. (ej:USD)
🔸Reference: Motivo o referencia específica del lote de pagos.
🔸PaymentItems: consta de un arreglo encriptado en AES 256 CBC sin vector de inicialización. (Se detalla a continuación)
📦Estructura del arreglo paymentItems (antes de encriptar)
El arreglo paymentItems contiene la información de todos los pagos que se realizarán entre cuentas Payphone:
[
{
"identifier":"1701111111001",
"customerType":"B",
"amount":200,
"reference":"id unico de transferencia"
},
{
"identifier":"593984111111",
"customerType":"C",
"amount":200,
"reference":"id unico de transferencia"
}
]
🧾 Descripción de cada campo:
🔸CustomerType: (string) Indica el tipo de usuario.
- B : Usuario de Payphone Business (el campo
identifier recibe como valor el número de identificación del comercio) - C : Usuario de Payphone Personal (el campo
identifier recibe como valor un número de teléfono).
🔸Identifier: Identificador de usuario de Payphone Business o Payphone Personal:
- Para Business: Número de Identificación de un usuario de Payphone Business, RUC(019041XXXX001) o CI (019041XXXX) o el identificador con el cual el comercio se registró.
- Para Personal: Número de teléfono de un usuario de Payphone Personal.
Formato: Código País + número telefónico. Ej. 59398XXXXXXX
🔸Amount: 💲es el valor que se pagará al actor registrado.
- Número Entero: Valor expresado en centavos (multiplica el valor en dólares por 100).
🔸Reference: Identificador que le entrega el comercio
- Cadena de Caracteres: cadena de caracteres que representen un identificador para el comercio.
- Seguimiento: Este identificador permite al comercio dar un seguimientos de los pagos que realice a los distintos usuarios Payphone.
⚠️ ¡Puntos Importantes a Recordar!
- Pagos a Usuarios Personales: Al realizar transferencias mediante pagos masivos a usuarios de Payphone Personal, si el número de teléfono no está registrado, Payphone pre registra este usuario, creará su billetera y le transferirá el saldo indicado.
- ¡Verifica antes de enviar! Para evitar transferencias a números no registrados en Payphone, puede revisar la sección de "Verificar Usuarios de Payphone" para usar nuestros servicios de consultas de usuarios.
- Pagos a Usuarios Business: Al realizar transferencias a usuarios de Payphone Business, si el identificador del comercio no está registrado, Payphone cancelará la transferencia y mostrará el error de "Tienda no existe" en la consulta del lote.
🔐 Encriptación del arreglo paymentItems
Para utilizar el servicio de pagos masivos es necesario que el valor del campo paymentItems esté encriptado para posteriormente enviarlo en la solicitud.
El algoritmo de encriptación a utilizar es 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",
"customerType": "C",
"amount": 500,
"reference":"id_unico_c_001"
},
{
"identifier": "0123456789001",
"customerType": "B",
"amount": 442,
"reference":"id_unico_b_101"
}
];
//ejecutar funcion de encriptacion para obtener paymentItems
let myPaymentItems=encrypted_aes(JSON.stringify(objetJSON));
//se muestra resultados
document.getElementById("objetJSON").innerHTML=JSON.stringify(objetJSON, null, 2);
document.getElementById("result").innerHTML=myPaymentItems;
console.log("Valor Encriptado : "+myPaymentItems);
</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 pagar
$objetJSON=array(
array(
"identifier"=> "+593984112233",
"customerType"=> "C",
"amount"=>500,
"reference"=> "id_unico_c_001",
),
array(
"identifier"=> "0123456789001",
"customerType"=> "B",
"amount"=>442,
"reference"=> "id_unico_b_101",
)
);
//ejecutar funcion de encriptacion para obtener paymentItems
$paymentItems=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>".$paymentItems."</strong></a>";
?>
Una vez implementados estos pasos, el comercio podrá generar transferencias entre cuentas Payphone utilizando la solicitud HTTP POST al API de pagos masivos.
📬Respuesta a la solicitud POST de Pagos Masivos :
Una vez que envías tu solicitud, Payphone te responderá con un objeto JSON que te dará información general sobre el lote:
{
"total": 2,
"batchId": 12345,
"pending": false,
"message": "Proceso de pago masivo generado satisfactoriamente."
}
📝Descripción de parámetros de respuesta
🔸Total: número de registros en el lote
🔸batchId: número del lote
🔸pending: si la solicitud se encuentra pendiente
🔸message: texto que indica que el proceso para ejecutar las transferencias se inició correctamente
⚠️ ¡Recuerda estos puntos clave sobre la API!
- ⏱️ Frecuencia de Solicitudes al API: Se puede realizar una vez cada minuto.
- Registros por lote: El API soporta hasta 1000 registros por solicitud.
- Respuesta del API: Solo representa lo que paso con el lote. Para saber que paso con cada pago individual, debe realizar la consulta de los pagos por número de lote.
- ⏳Tiempo para Consulta: Se recomienda realizar la consulta de los resultados de cada transferencia 10 segundos después de ejecutar el API de pagos masivos.
- Paginación: Si el lote contiene muchos registros, la respuesta de la consulta se paginara. Utilice el parámetro
page para navegar entre las páginas. - 💸Saldo Real: Recordar que el servicio realiza movimientos reales de saldo entre cuentas Payphone.
- Credenciales: Es fundamental que el establecimiento gestione las credenciales con la máxima seguridad y rigurosidad para proteger el token de autenticación y la contraseña de codificación.
- Almacenar: Estas credenciales no deben almacenarse en texto plano o en el código visible para el cliente, ya que una fuga de estas podría comprometer la seguridad de los saldos del comercio.
- Proceso: las solicitudes al API se debería realizar en backend.
🧱 Ejemplo de solicitud POST de Pagos Masivos
A continuación, se presenta un ejemplos de cómo realizar una solicitud POST de pagos masivos:
<?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";
//Objeto JSON que contiene los usuarios y los montos a transaferir
$objetJSON=array(
array(
"identifier"=> "593984112233",
"customerType"=> "C",
"amount"=>100,
"reference"=> "id_unico_c_001",
),
array(
"identifier"=> "0123456789001",
"customerType"=> "B",
"amount"=>100,
"reference"=> "id_unico_b_101",
)
);
//ejecutar funcion de encriptacion para obtener paymentItems
$paymentItems=encrypt(json_encode($objetJSON));
/*## Preparar informacion para la solicitud POST ##*/
//URL del servicio payphone
$url="https://pay.payphonetodoesposible.com/api/StorePayments/transfer";
//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(
"currency"=> "USD",
"reference"=> "Lote de transferencias de prueba",
"paymentItems"=> $paymentItems
);
$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 Pagos Masivos</h1> <br>";
echo "Cuerpo Solicitud : <pre>".json_encode($data,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
echo "Valores a Transferir: <pre>".json_encode($objetJSON,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
echo "Respuesta : <pre>".json_encode($result,JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT )."</pre>";
?>
Si has llegado a este punto, terminaste la primera parte. En la siguiente sección, te explicaremos cómo Consultar el estado de las transferencias realizadas a los usuarios Payphone.
