Inicio rápido: tu primera orden de compra

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.


Antes de comenzar

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.

1. Crea una orden de compra

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.

POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate
Solicitud
			
{
  "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"
}


		
Respuesta
			
{
  "success": true,
  "action": "added",
  "_id": "6537f1c2a90735097a811c01",
  "updatedAt": "2026-10-22T15:04:05.123Z",
  "link": "https://site.url/L-KA39T1A45JL",
  "missingCustomer": false
}


		

2. Actualízala

Envía de nuevo el _id con los campos que quieras cambiar. Sin él, Hyfin crearía una segunda orden de compra.

POST
{base_url}/api/v4/site/{site_id}/invoice/addUpdate
Solicitud
			
{
  "_id": "6537f1c2a90735097a811c01",
  "customerMemo": "Thank you for your business!"
}


		
Respuesta
			
{
  "success": true,
  "action": "updated",
  "_id": "6537f1c2a90735097a811c01",
  "updatedAt": "2026-10-22T15:06:12.456Z",
  "link": "https://site.url/L-KA39T1A45JL",
  "missingCustomer": false
}


		

3. Págala

Abre el link del paso 1, o el correo electrónico que te envió Hyfin, y paga con una tarjeta de prueba.

4. Recibe el webhook de pago

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.

Carga útil del webhook (recortada)
			
{
  "action": "payment",
  "data": {
    "_id": "6537f2d4a90735097a811c9e",
    "status": "captured",
    "amount": 4599,
    "allocations": [
      {
        "ref_type": "Invoice",
        "ref": "6537f1c2a90735097a811c01",
        "amount": 4599
      }
    ]
  }
}


		

5. Consúltalo de nuevo

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.

GET
{base_url}/api/v4/site/{site_id}/invoice/{_id}