Verificar pagos
Uno de los aspectos más importantes de cualquier integración es poder verificar que un pago se ha realizado correctamente. El método para hacerlo y la cantidad de información que recibas pueden variar dependiendo de cómo tu cuenta reciba los fondos. TropiPay ofrece múltiples formas de recibir pagos; las tarjetas de pago son una opción, quizás la más adecuada para sitios web. Sin embargo, también existe la opción de compartir tu perfil (lo que genera una tarjeta de pago especial que permite al cliente especificar el monto) o recibir transferencias internas desde otra cuenta de TropiPay. Estos métodos difieren en cuanto a comisiones, y quizás prefieras uno sobre otro, o incluso una combinación de varios.
Uso de Paymentcards y notificationUrl
La notificationUrl debe ser un endpoint público, accesible desde los servidores de Tropipay. Puedes usar servicios como webhook.site o ngrok para probar de forma local.
Al crear una tarjeta de pago mediante la API, puedes especificar una notificationUrl. TropiPay enviará una solicitud POST con un payload JSON a esta URL cuando ocurra el evento transaction_completed o transaction_failed. Este payload contiene información útil como la referencia, el código de orden bancaria y los datos del cliente (email, nombre, apellidos, etc). Si recibes "status":"OK", significa que tu orden está pagada. Si recibes "status":"KO", significa que el pago se inició pero falló (consulta Pruebas de pagos con tarjeta para ver los payloads de callback fallidos y los detalles de las tarjetas de prueba).
Preferiblemente, tu endpoint debe devolver un estado 200 OK lo antes posible. Luego, procesa el payload de forma asíncrona. Cualquier otro código de estado o falta de respuesta de tu notificationUrl (timeout) se interpretará como un fallo al recibir el callback correctamente. TropiPay intentará reenviar el callback a intervalos hasta que el webhook devuelva un estado 200.
Verifica siempre la firma del payload en producción para asegurarte de que proviene de TropiPay. La firma se encuentra en el campo signatureV3. Debes calcular y comparar la firma proporcionada con la recibida en el payload.
signatureV3 = sha256( bankOrderCode + apiKey + sha1(apiSecret) + originalCurrencyAmount )
Esto aplica tanto para notificationUrl como para hooks. Conserva logs de cada callback recibido para tener una trazabilidad, documentando los detalles de la transacción. Los logs facilitan la depuración al proporcionar información sobre fallos o discrepancias en los pagos. Servicios como Papertrail o Loggly pueden centralizar tus logs, dándote un punto único para consultarlos.
Ejemplo de payload de éxito de notificationUrl
{
"status": "OK",
"data": {
"id": 389863,
"reference": "1695389078367",
"bankOrderCode": "690259220262",
"provider": 4,
"userId": "366e8170-65d3-11ed-a813-575702a10503",
"bookingDate": "2023-09-22T13:24:38.370Z",
"days": null,
"amount": 200,
"currency": "EUR",
"originalCurrencyAmount": "200",
"destinationAmount": "143",
"destinationCurrency": "EUR",
"conversionRate": 1,
"depositaccountId": null,
"ourFee": 300,
"providerFee": -57,
"state": 5,
"serviceId": 2,
"paymentcardId": "92ad58b0-594a-11ee-893c-db9cbd81fd9c",
"expirationDate": "2023-09-22T13:24:38.367Z",
"movementTypeId": 2,
"transactionId": null,
"isInternal": false,
"agent": "TROPIPAY",
"ip": "152.206.139.26",
"reasonId": 4,
"reasonDes": null,
"errorReason": null,
"notificationUrl": null,
"riskFlag": 0,
"riskScore": 0,
"createdAt": "2023-09-22T13:24:38.370Z",
"updatedAt": "2023-09-22T13:25:12.354Z",
"paymentcard": {
"id": "92ad58b0-594a-11ee-893c-db9cbd81fd9c",
"reference": "2ksuahi1olmumodrr",
"concept": "Bicycle",
"description": "Two wheels",
"amount": 200,
"currency": "EUR",
"singleUse": false,
"reasonId": 4,
"reasonDes": null,
"userId": "366e8170-65d3-11ed-a813-575702a10503",
"qrImage": null,
"shortUrl": "https://tppay.me/lmumoe35",
"state": 1,
"expirationDays": 0,
"lang": "es",
"urlSuccess": "https://www.tropipay.com",
"urlFailed": "https://www.google.com",
"urlNotification": "https://webhook.site/22db2afd-3fb8-404b-b4c4-c39b1334e439",
"expirationDate": null,
"serviceDate": null,
"hasClient": false,
"paymentUrl": null,
"favorite": true,
"saveToken": false,
"imageBase": null
},
"charges": [
{
"clientName": "John",
"clientLastName": "Wick",
"clientAddress": "Hotel Continental",
"clientPhone": "892498324234",
"clientEmail": "johnwick@gmail.com",
"riskScore": 0,
"id": 260991,
"orderCode": "1695389078367",
"cardPan": "0004",
"cardExpirationDate": "2024-02-01T00:00:00.000Z",
"cardHolderName": "John",
"saveToken": false,
"amount": 200,
"currency": 978,
"userId": "366e8170-65d3-11ed-a813-575702a10503",
"bookingId": 389863,
"errorReason": "",
"state": 3,
"serviceId": 2,
"clientTC": "true",
"clientCountryId": 25,
"updatedAt": "2023-09-22T13:25:12.246Z",
"createdAt": "2023-09-22T13:24:38.381Z",
"cardCountry": "DE",
"cardBrand": "VISA",
"cardCategory": "SecureTrading Test Issuer1",
"cardType": "",
"clientIp": "152.206.139.26",
"cardSubBrand": null,
"card3DSVersion": "",
"card3DS2IdMsg": null,
"cardAut3DSecure2Method": null,
"card3DS2Partition": null,
"cardDcc": null,
"cardBin": "454881",
"securityCheckPostCode": "0",
"securityCheckAddress": "0"
}
],
"cardTokenId": null,
"signature": "e78e9e31139c35e9e987cd3d0ad1208108318fb26685c7fa6cba3e3a6626be42",
"signaturev2": "4845e478d69d77f2556f48617e5c9c012c3929df3c259cc4e640e634661f1d34",
"signaturev3":"9875e478d69d77f2556f48617e5c9c012c3929df3c259cc4e640e634661f1n84",
"clientData": {
"clientName": "John",
"clientLastName": "Wick",
"clientAddress": "Hotel Continental",
"clientEmail": "johnwick@gmail.com"
}
}
}
Uso de Hooks
El webhook debe ser un endpoint público, accesible desde los servidores de Tropipay. Puedes usar servicios como webhook.site o ngrok para probar de forma local.
Los hooks, a menudo llamados webhooks, son una forma conveniente de recibir notificaciones cuando ocurren ciertos eventos en tu cuenta de TropiPay. Estos eventos pueden ser, por ejemplo: cuando un pago se completa o los fondos son retenidos por TropiPay en una tarjeta de pago de mediación. Puedes usar hooks en lugar de notificationUrl para verificar pagos.
Responder de inmediato
TropiPay enviará una solicitud POST con un payload JSON a esta URL cuando ocurra el evento seleccionado. Estos endpoints deben ser accesibles desde Internet, y específicamente desde los servidores de Tropipay. Asegúrate de que tu endpoint devuelva HTTP 200/OK de inmediato. Si no hay respuesta (timeout) o la respuesta es diferente de HTTP 200 (4xx, 5xx), TropiPay intentará reenviar el callback varias veces.
Próximamente
Más información en la sección de hooks de la documentación.