Esto lleva una orden de compra desde tu software hasta quedar pagada en el entorno de stage, con cuatro llamadas a la API y un webhook.
Necesitas un token de API y el site_id de un sitio de prueba en stage. Envía un correo a api-support@hyfin.app para solicitar ambos, y pídeles que activen el acceso a la API para ese sitio.
Envía cada solicitud a https://stage-api.hyfin.app con tu token en el encabezado x-access-token.
También necesitas una URL HTTPS pública que te muestre lo que se le envía, para recibir el webhook. Un request bin funciona para hacer pruebas.
Omite _id y externalId: eso le indica a Hyfin que es una orden de compra nueva. El cliente se crea junto con ella. Usa tu propio correo electrónico para que la orden de compra te llegue a ti, y establece webhookUrl con tu URL de prueba.
Guarda el _id de la respuesta. link es la página donde el cliente paga.
{
"invoiceNumber": "1001",
"description": "Lawn care, October",
"totals": {
"total": 4599
},
"customer": {
"externalId": "C-1001",
"primaryContact": {
"firstName": "Jane",
"lastName": "Doe",
"email": "you@yourcompany.com"
}
},
"webhookUrl": "https://yourcompany.com/webhook"
}
{
"success": true,
"action": "added",
"_id": "6537f1c2a90735097a811c01",
"updatedAt": "2026-10-22T15:04:05.123Z",
"link": "https://site.url/L-KA39T1A45JL",
"missingCustomer": false
}
Envía de nuevo el _id con los campos que quieras cambiar. Sin él, Hyfin crearía una segunda orden de compra.
{
"_id": "6537f1c2a90735097a811c01",
"customerMemo": "Thank you for your business!"
}
{
"success": true,
"action": "updated",
"_id": "6537f1c2a90735097a811c01",
"updatedAt": "2026-10-22T15:06:12.456Z",
"link": "https://site.url/L-KA39T1A45JL",
"missingCustomer": false
}
Abre el link del paso 1, o el correo electrónico que te envió Hyfin, y paga con una tarjeta de prueba.
Hyfin envía el pago a tu webhookUrl. allocations[0].ref es el _id de la orden de compra que guardaste en el paso 1, y así tu software sabe qué orden de compra se pagó. Las claves del webhook están en snake_case.
{
"action": "payment",
"data": {
"_id": "6537f2d4a90735097a811c9e",
"status": "captured",
"amount": 4599,
"allocations": [
{
"ref_type": "Invoice",
"ref": "6537f1c2a90735097a811c01",
"amount": 4599
}
]
}
}
Obtener orden de compra enumera los _id de pago de la orden de compra en payments. Obtener pago devuelve uno de ellos completo. Ese es todo el ciclo: la orden de compra se envió, el cliente pagó y tu software lo sabe.