Referencia de API

Referencia completa de los endpoints de la API de pagos de Saga

La API de pagos de Saga proporciona una interfaz simple y segura para procesar pagos en stablecoins. Construida para la web descentralizada, nuestra API maneja la creación de pagos, el seguimiento de estado y las notificaciones de webhook con mínima complejidad de integración.

URL Base

Sandbox:

https://beta.saga.onl/api/v1

Production:

https://saga.onl/api/v1

POST/pay

Crear Pago

Crea una nueva solicitud de pago y devuelve los detalles del pago para la transacción blockchain.

Cuerpo de la Solicitud

{
  "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "chainId": 11155111,
  "nonce": 42,
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "metadata": {
    "orderId": "12345",
    "description": "Payment for order #12345"
  },
  "callbackUrl": "https://your-site.com/webhook/saga",
  "callbackSecret": "your-webhook-secret-key"
}

Parámetros

Name	Type	Required	Description
`transactionHash`	string	Required	Blockchain transaction hash
`chainId`	number	Required	Blockchain chain ID (11155111 for Sepolia, 1 for Mainnet)
`nonce`	number	Required	Transaction nonce for correlation
`payeeAddress`	string	Required	Merchant's wallet address
`grossAmount`	string	Required	USDC amount in smallest units (6 decimals, e.g., "1000000" = $1.00)
`payerAddress`	string	Required	Customer's wallet address
`metadata`	object	Optional	Optional payment metadata
`callbackUrl`	string	Optional	Optional webhook callback URL
`callbackSecret`	string	Optional	Secret key for webhook signature verification (recommended for production)

Respuesta

200Payment created successfully

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "status": "PENDING"
}

400Bad Request - Invalid input

{
  "error": "transactionHash is not in the expected format"
}

Parámetros de Respuesta

Name	Type	Required	Description
`paymentId`	string	Required	Unique payment identifier (UUID)
`payeeAddress`	string	Required	Merchant's wallet address
`payerAddress`	string	Required	Customer's wallet address
`grossAmount`	string	Required	USDC amount in smallest units (6 decimals)
`status`	string	Required	Payment status (PENDING, COMPLETED, FAILED)

GET/pay/{paymentId}

Obtener Estado del Pago

Recupera el estado actual y los detalles de un pago por su ID.

Parámetros

Name	Type	Required	Description
`paymentId`	string (UUID)	Required	Unique payment identifier

Respuesta

200Payment status retrieved successfully

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "status": "COMPLETED",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:32:15Z",
  "metadata": {
    "orderId": "12345",
    "description": "Payment for order #12345"
  },
  "blockchainTx": {
    "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "blockNumber": 12345678
  }
}

404Payment not found

{
  "error": "Payment not found"
}

Parámetros de Respuesta

Name	Type	Required	Description
`paymentId`	string	Required	Unique payment identifier (UUID)
`payeeAddress`	string	Required	Merchant's wallet address
`payerAddress`	string	Optional	Customer's wallet address (null until payment submitted)
`grossAmount`	string	Required	USDC amount in smallest units (6 decimals)
`status`	string	Required	Payment status (PENDING, COMPLETED, FAILED)
`createdAt`	string	Required	Payment creation timestamp (ISO 8601)
`completedAt`	string	Optional	Payment completion timestamp (ISO 8601)
`metadata`	object	Optional	Payment metadata
`blockchainTx`	object	Optional	Blockchain transaction details (txHash, blockNumber)

Estado del Pago

Los pagos pueden tener uno de los siguientes estados:

PENDIENTE

El pago ha sido creado pero aún no confirmado en la blockchain

COMPLETADO

El pago ha sido confirmado exitosamente en la blockchain

FALLIDO

El pago falló debido a un error en la transacción o tiempo de espera agotado

Códigos de Error

La API de Saga devuelve códigos de estado HTTP estándar con mensajes de error descriptivos. Todas las respuestas de error siguen un formato consistente.

400Solicitud Incorrecta

Parámetros de solicitud o formato de datos inválidos

{
  "error": "transactionHash is not in the expected format"
}

404No Encontrado

El ID de pago no existe o es inválido

{
  "error": "Payment not found"
}

500Error Interno del Servidor

Error inesperado del servidor

{
  "error": "Internal server error"
}

Webhooks

Saga envía notificaciones de webhook a tu URL de callback cuando cambia el estado del pago. Los webhooks se envían para la finalización del pago, fallos y otras actualizaciones de estado.

Cuándo se Envían los Webhooks

Actualizaciones de Estado de Pago

Los webhooks se envían inmediatamente cuando el estado del pago cambia de PENDIENTE a COMPLETADO o FALLIDO después de la confirmación de la transacción blockchain

Intentos de Reintento

Los webhooks se reintentan si tu endpoint no responde exitosamente

Carga del Webhook

Las cargas de webhook contienen la respuesta completa del estado del pago:

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "payeeAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "payerAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "grossAmount": "1000000",
  "status": "COMPLETED",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:35:00Z",
  "metadata": {
    "orderId": "12345",
    "description": "Payment for order #12345"
  },
  "blockchainTx": {
    "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "blockNumber": 12345678
  }
}

Encabezados del Webhook

Saga incluye encabezados adicionales con cada solicitud de webhook:

Content-Type: application/json

X-Saga-Callback-Attempt: 1

X-Saga-Sent-At: 2024-01-15T10:30:00Z

X-Saga-Callback-Secret: your-webhook-secret-key

Seguridad del Webhook

🔒 Mejor Práctica: Siempre Validar con Solicitud GET

Independientemente de si usas callbackSecret o no, siempre realiza una solicitud GET a/pay/{paymentId} para validar el estado del pago.

GET /pay/550e8400-e29b-41d4-a716-446655440000

Esto asegura que estás procesando el estado de pago más actualizado y previene ataques de repetición.

Validación del Webhook

Cuando proporcionas un callbackSecret en tu solicitud de pago, Saga incluye este secreto en los encabezados del webhook para validación adicional:

X-Saga-Callback-Secret: your-webhook-secret-key

Esto ayuda a verificar la autenticidad del webhook, pero la validación de solicitud GET anterior sigue siendo la medida de seguridad principal.

Política de Reintento

• Los webhooks se reintentan hasta 5 veces (configurable vía MAX_ATTEMPTS)

• Cada intento de reintento incluye el número de intento en el encabezado X-Saga-Callback-Attempt

• Los webhooks que fallan después de los intentos máximos se marcan como fallidos

• Tu endpoint siempre debe devolver HTTP 200, independientemente del éxito o fallo del procesamiento

• El tiempo de espera se establece en 5 segundos (configurable vía CALLBACK_TIMEOUT_MS)

Found a bug or have a question?

Report an Issue