API Reference

Complete reference for Saga's payment API endpoints

Saga's payment API provides a simple, secure interface for processing stablecoin payments. Built for the decentralized web, our API handles payment creation, status tracking, and webhook notifications with minimal integration complexity.

Base URL

Sandbox:

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

Production:

https://saga.onl/api/v1

POST/pay

Create Payment

Creates a new payment request and returns payment details for blockchain transaction.

Request Body

{
  "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"
}

Parameters

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)

Response

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"
}

Response Parameters

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}

Get Payment Status

Retrieves the current status and details of a payment by its ID.

Parameters

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

Response

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"
}

Response Parameters

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)

Payment Status

Payments can have one of the following statuses:

PENDING

Payment has been created but not yet confirmed on the blockchain

COMPLETED

Payment has been successfully confirmed on the blockchain

FAILED

Payment failed due to transaction failure or timeout

Error Codes

Saga API returns standard HTTP status codes with descriptive error messages. All error responses follow a consistent format.

400Bad Request

Invalid request parameters or data format

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

404Not Found

Payment ID does not exist or is invalid

{
  "error": "Payment not found"
}

500Internal Server Error

Unexpected server error

{
  "error": "Internal server error"
}

Webhooks

Saga sends webhook notifications to your callback URL when payment status changes. Webhooks are sent for payment completion, failure, and other status updates.

When Webhooks Are Sent

Payment Status Updates

Webhooks are sent immediately when payment status changes from PENDING to COMPLETED or FAILED after blockchain transaction confirmation

Retry Attempts

Webhooks are retried if your endpoint doesn't respond successfully

Webhook Payload

Webhook payloads contain the complete payment status response:

{
  "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
  }
}

Webhook Headers

Saga includes additional headers with each webhook request:

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

Webhook Security

🔒 Best Practice: Always Validate with GET Request

Regardless of whether you use callbackSecret or not, always perform a GET request to/pay/{paymentId} to validate payment status.

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

This ensures you're processing the most current payment status and prevents replay attacks.

Webhook Validation

When you provide a callbackSecret in your payment request, Saga includes this secret in webhook headers for additional validation:

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

This helps verify webhook authenticity, but the GET request validation above remains the primary security measure.

Retry Policy

• Webhooks are retried up to 5 times (configurable via MAX_ATTEMPTS)

• Each retry attempt includes the attempt number in the X-Saga-Callback-Attempt header

• Webhooks that fail after max attempts are marked as failed

• Your endpoint should always return HTTP 200, regardless of processing success or failure

• Timeout is set to 5 seconds (configurable via CALLBACK_TIMEOUT_MS)

Found a bug or have a question?

Report an Issue