Payment Links API

API publica para crear, editar y consultar links de pago.

Autenticacion

No todos los endpoints de esta seccion usan el mismo mecanismo de acceso.

Endpoints autenticados (API Key + Client ID)

Aplica a:

• POST /api/payment-links
• PUT /api/payment-links/{id}

Headers requeridos:

Header	Valor	Descripcion
Authorization	Bearer {API_KEY}	API Key privada
x-client-id	{CLIENT_ID}	Identificador de cliente
Content-Type	application/json	Tipo de contenido

Endpoints con proof (sin API Key)

Aplica a:

• GET /api/payment-links/{id}?proof={token}
• POST /api/payment-links/{id}/sandbox-action

Estos endpoints validan el acceso mediante el token proof del payment link.

---

1) Crear Payment Link

Endpoint

POST /api/payment-links

Body Parameters

Parametro	Tipo	Requerido	Descripcion
items	Array	Si	Lista de conceptos a cobrar
items[].title	String	Si	Nombre del producto o servicio
items[].quantity	Number	Si	Cantidad (mayor a 0)
items[].unitPrice	Number	Si	Precio unitario (mayor o igual a 0)
items[].currencyId	String	Si	Moneda (ejemplo: ARS)
items[].imageUrl	String	No	URL de imagen del item
referenceId	String	Si	ID de referencia en tu sistema
backUrl	Object	No	URLs de redireccion
backUrl.success	String	No	URL para pago exitoso
backUrl.failure	String	No	URL para pago fallido
notificationUrl	String	No	URL webhook para este link (prioridad sobre la del cliente)
sandbox	Bool	No	Si es true, crea link de prueba

Request de ejemplo

{
  "items": [
    {
      "title": "Testing",
      "quantity": 1,
      "unitPrice": 100,
      "currencyId": "ARS"
    }
  ],
  "referenceId": "orden-456",
  "notificationUrl": "https://tusitio.com/webhooks/pagos",
  "sandbox": true,
  "backUrl": {
    "success": "https://tusitio.com/pago-exitoso",
    "failure": "https://tusitio.com/pago-fallido"
  }
}

Respuesta exitosa (201)

{
  "url": "https://pay.galio.app/payment/64a1b2c3d4e5f6g7h8i9j0k1?proof=a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "proofToken": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "referenceId": "orden-456",
  "sandbox": true
}

Errores frecuentes (400)

{
  "error": "Items array is required"
}

{
  "error": "Reference ID is required"
}

{
  "error": "Minimum payment amount is $100"
}

cURL

curl -X POST https://pay.galio.app/api/payment-links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "x-client-id: TU_CLIENT_ID" \
  -d '{
    "items": [
      {
        "title": "Testing",
        "quantity": 1,
        "unitPrice": 100,
        "currencyId": "ARS"
      }
    ],
    "referenceId": "orden-456"
  }'

---

2) Editar Payment Link

Endpoint

PUT /api/payment-links/{id}

Solo se actualizan los campos enviados.

URL Parameters

Parametro	Tipo	Requerido	Descripcion
id	String	Si	ID del payment link

Body Parameters

Parametro	Tipo	Descripcion
referenceId	String	Sin espacios; solo letras, numeros, _ y -
items	Array	Lista completa de items actualizada
backUrl	Object	URLs de redireccion
notificationUrl	String	URL para webhook del payment link

Webhook por payment link

Si envías notificationUrl al crear o editar un payment link, los webhooks de ese link se enviarán a esa URL.

Prioridad de destino:

1. paymentLink.notificationUrl (si está definido)
2. client.notificationUrl (fallback)

Si no hay ninguna de las dos configuradas, no se envía webhook.

Respuesta exitosa (200)

{
  "message": "Payment link updated successfully",
  "paymentLink": {
    "_id": "64a1b2c3d4e5f6g7h8i9j0k1",
    "referenceId": "orden-456-updated"
  }
}

Errores frecuentes

{
  "error": "Cannot edit a payment link that has already been paid"
}

{
  "error": "Items must be a non-empty array"
}

cURL

curl -X PUT "https://pay.galio.app/api/payment-links/64a1b2c3d4e5f6g7h8i9j0k1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "x-client-id: TU_CLIENT_ID" \
  -d '{
    "referenceId": "orden-456-updated",
    "description": "Nueva descripcion"
  }'

---

3) Obtener Payment Link

Endpoint

GET /api/payment-links/{id}?proof={token}

URL Parameters

Parametro	Tipo	Requerido	Descripcion
id	String	Si	ID del payment link

Query Parameters

Parametro	Tipo	Requerido	Descripcion
proof	String	Si	Token de verificacion del link

Respuesta exitosa (200)

{
  "id": "64a1b2c3d4e5f6g7h8i9j0k1",
  "proofToken": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "items": [
    {
      "title": "Testing",
      "quantity": 1,
      "unitPrice": 100,
      "currencyId": "ARS"
    }
  ],
  "referenceId": "orden-456",
  "backUrl": {
    "success": "https://tusitio.com/pago-exitoso",
    "failure": "https://tusitio.com/pago-fallido"
  },
  "status": "pending",
  "sandbox": false,
  "paymentId": null
}

cURL

curl -X GET "https://pay.galio.app/api/payment-links/64a1b2c3d4e5f6g7h8i9j0k1?proof=a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"

---

4) Accion Sandbox (aprobar)

Solo disponible para links creados con sandbox: true.

Endpoint

POST /api/payment-links/{id}/sandbox-action

Body Parameters

Parametro	Tipo	Requerido	Descripcion
proof	String	Si	Token de verificacion del payment link
action	String	Si	approve

Request de ejemplo

{
  "proof": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
  "action": "approve"
}

Respuesta exitosa (200)

{
  "success": true,
  "message": "Sandbox payment approved",
  "payment": {
    "id": "67a8f1b2c3d4e5f6a7b8c9d0",
    "status": "approved"
  }
}

cURL

curl -X POST "https://pay.galio.app/api/payment-links/64a1b2c3d4e5f6g7h8i9j0k1/sandbox-action" \
  -H "Content-Type: application/json" \
  -d '{
    "proof": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6",
    "action": "approve"
  }'