API Documentation

Payments API

Create and manage payments between agents and users using the x402 and h402 protocols.

Create Payment

Create a new payment request between agents or users.

bash

POST /api/payments

Request Body

Parameter	Type	Description
amount	string	Payment amount in the specified currency
currency	string	Currency code (ETH, USDC, DAI)
description	string	Description of the payment
type	string	Payment type (immediate, escrow, time-locked)
expiresIn	string?	Optional expiration time (e.g. "30m", "24h", "7d")
requirements	object?	Optional payment requirements (callbackUrl, etc.)
metadata	object?	Optional metadata for the payment

Response

json

{
  "status": 200,
  "message": "Payment request created successfully",
  "data": {
    "paymentRequest": {
      "id": "uuid",
      "amount": "1.0",
      "currency": "ETH",
      "description": "Payment for services",
      "status": "pending",
      "expiresAt": "2024-03-21T12:00:00Z",
      "createdAt": "2024-03-20T12:00:00Z",
      "metadata": {}
    },
    "paymentUrl": "https://paydirect.com/pay/uuid"
  }
}

Get Payment

Retrieve details of a specific payment.

bash

GET /api/payments/:paymentId

Parameters

Parameter	Type	Description
paymentId	string	Unique identifier of the payment

Response

json

{
  "status": 200,
  "message": "Payment request retrieved successfully",
  "data": {
    "paymentRequest": {
      "id": "uuid",
      "amount": "1.0",
      "currency": "ETH",
      "description": "Payment for services",
      "status": "pending",
      "expiresAt": "2024-03-21T12:00:00Z",
      "createdAt": "2024-03-20T12:00:00Z",
      "metadata": {}
    }
  }
}

Update Payment

Update the status or metadata of a payment.

bash

PATCH /api/payments/:paymentId

Request Body

Parameter	Type	Description
status	string	New payment status (pending, completed, failed, expired, cancelled)
metadata	object?	Optional metadata to update

Response

json

{
  "status": 200,
  "message": "Payment request updated successfully",
  "data": {
    "paymentRequest": {
      "id": "uuid",
      "amount": "1.0",
      "currency": "ETH",
      "description": "Payment for services",
      "status": "completed",
      "expiresAt": "2024-03-21T12:00:00Z",
      "createdAt": "2024-03-20T12:00:00Z",
      "metadata": {
        "customField": "value"
      }
    }
  }
}

Cancel Payment

Cancel a pending payment request.

bash

DELETE /api/payments/:paymentId

Parameters

Parameter	Type	Description
paymentId	string	Unique identifier of the payment to cancel

Response

json

{
  "status": 200,
  "message": "Payment request cancelled successfully"
}

List Payments

Retrieve a list of payments with optional filtering.

bash

GET /api/payments

Query Parameters

Parameter	Type	Description
status	string?	Filter by payment status (pending, completed, failed, expired, cancelled)
currency	string?	Filter by currency
page	number?	Page number for pagination (default: 1)
limit	number?	Number of items per page (default: 20, max: 100)

Response

json

{
  "status": 200,
  "message": "Payments retrieved successfully",
  "data": {
    "payments": [
      {
        "id": "uuid",
        "amount": "1.0",
        "currency": "ETH",
        "description": "Payment for services",
        "status": "completed",
        "expiresAt": "2024-03-21T12:00:00Z",
        "createdAt": "2024-03-20T12:00:00Z",
        "metadata": {}
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1
    }
  }
}

Payment Statuses

Status	Description
pending	Payment request is waiting to be processed
completed	Payment has been successfully processed
failed	Payment processing failed
expired	Payment request has expired
cancelled	Payment request was cancelled

Expiration

Payment requests can have an expiration time specified using the expiresIn parameter. The expiration time can be specified in the following formats:

Format	Example	Description
minutes	30m	30 minutes from creation
hours	24h	24 hours from creation
days	7d	7 days from creation

If no expiration time is specified, the payment request will expire after 24 hours by default. Expired payment requests cannot be processed and will need to be recreated.

Status Tracking

Payment status can be tracked through the API. The status will automatically update to "expired" when the expiration time is reached. You can also manually update the status using the Update Payment endpoint.

Webhooks

You can receive real-time updates about payment status changes by configuring a webhook URL in the payment requirements. The webhook will be called with the following events:

Event	Description
payment.created	Payment request was created
payment.completed	Payment was successfully processed
payment.failed	Payment processing failed
payment.expired	Payment request has expired
payment.cancelled	Payment request was cancelled

Example Webhook Payload

json

{
  "event": "payment.expired",
  "data": {
    "paymentRequest": {
      "id": "uuid",
      "amount": "1.0",
      "currency": "ETH",
      "description": "Payment for services",
      "status": "expired",
      "expiresAt": "2024-03-21T12:00:00Z",
      "createdAt": "2024-03-20T12:00:00Z"
    }
  },
  "timestamp": "2024-03-21T12:00:00Z"
}

Error Codes

Code	Description
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
403	Forbidden - Payment does not belong to merchant
404	Not Found - Payment not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Try it Out

Visit our interactive playground to test the Payments API with real examples:

Open Payment Examples

Transaction Status Tracking

Track the status of blockchain transactions associated with payments.

Transaction Statuses

Status	Description
pending	Transaction is pending confirmation on the blockchain
confirmed	Transaction has been confirmed on the blockchain
failed	Transaction failed on the blockchain
dropped	Transaction was dropped from the mempool

Get Transaction Status

bash

GET /api/payments/:paymentId/transaction

Response

json

{
  "status": 200,
  "data": {
    "transaction": {
      "hash": "0x...",
      "status": "confirmed",
      "confirmations": 12,
      "blockNumber": 12345678,
      "timestamp": "2024-03-21T12:00:00Z",
      "error": null
    }
  }
}

Error Handling

Error Code	Description
INSUFFICIENT_GAS	Transaction failed due to insufficient gas
INSUFFICIENT_FUNDS	Transaction failed due to insufficient balance
NONCE_TOO_LOW	Transaction nonce is too low
REPLACEMENT_UNDERPRICED	Transaction replacement is under-priced

Wallet Integration

Check wallet balances and validate addresses before processing payments.

Get Wallet Balance

bash

GET /api/wallets/:address/balance

Parameters

Parameter	Type	Description
address	string	Wallet address to check
currency	string?	Optional currency to check (default: ETH)

Response

json

{
  "status": 200,
  "data": {
    "address": "0x...",
    "balances": {
      "ETH": "1.23456789",
      "USDC": "1000.00",
      "DAI": "500.00"
    },
    "isValid": true,
    "lastUpdated": "2024-03-21T12:00:00Z"
  }
}

Validate Address

bash

POST /api/wallets/validate

Request Body

Parameter	Type	Description
address	string	Wallet address to validate
chainId	number?	Optional chain ID for validation (default: 1 for Ethereum mainnet)

Response

json

{
  "status": 200,
  "data": {
    "address": "0x...",
    "isValid": true,
    "checksumAddress": "0x...",
    "chainId": 1,
    "validationDetails": {
      "isContract": false,
      "isEOA": true,
      "hasCode": false
    }
  }
}

When creating a payment, the system will automatically check the sender's wallet balance. If the balance is insufficient, the payment request will be rejected with an INSUFFICIENT_FUNDS error.

Transaction Confirmation System

Monitor and track blockchain transaction confirmations in real-time.

Get Transaction Confirmation Status

bash

GET /api/payments/:paymentId/transaction/confirmation

Response

json

{
  "status": 200,
  "data": {
    "transaction": {
      "hash": "0x...",
      "status": "confirmed",
      "confirmations": 12,
      "requiredConfirmations": 6,
      "blockNumber": 12345678,
      "blockHash": "0x...",
      "receipt": {
        "status": true,
        "gasUsed": "21000",
        "effectiveGasPrice": "20000000000",
        "logs": []
      },
      "timestamp": "2024-03-21T12:00:00Z"
    }
  }
}

Webhook Events

Event	Description
transaction.confirmed	Transaction has reached required confirmations
transaction.failed	Transaction failed on the blockchain
transaction.replaced	Transaction was replaced with a new one

Payment Flow Completion

Handle payment completion with redirects and callbacks.

Configurable Redirect URLs

Configure where users are redirected after different payment states.

Status	URL Parameter	Description
Success	successUrl	Redirect after successful payment completion
Failure	failureUrl	Redirect after payment failure or error
Cancelled	cancelUrl	Redirect when user cancels the payment
Pending	pendingUrl	Redirect while payment is being processed

Example Configuration

json

{
  "amount": "1.0",
  "currency": "ETH",
  "description": "Payment for services",
  "requirements": {
    "successUrl": "https://your-domain.com/payment/success",
    "failureUrl": "https://your-domain.com/payment/failed",
    "cancelUrl": "https://your-domain.com/payment/cancelled",
    "pendingUrl": "https://your-domain.com/payment/pending"
  }
}

All redirect URLs are optional. If not provided, users will stay on the payment page and see the appropriate status message. We recommend implementing all URLs for the best user experience.

URL Parameters

The following parameters are appended to your redirect URLs:

Parameter	Description
paymentId	Unique identifier for the payment
status	Payment status (completed, failed, cancelled, pending)
amount	Payment amount
currency	Payment currency

Example Redirect

bash

https://your-domain.com/payment/success?paymentId=123&status=completed&amount=1.0&currency=ETH

Implementation Example

typescript

// Create payment request with redirect URLs
const paymentRequest = await X402Protocol.createPaymentRequest(merchantId, {
  amount: "1.0",
  currency: "ETH",
  description: "Payment for services",
  requirements: {
    successUrl: "https://your-domain.com/payment/success",
    failureUrl: "https://your-domain.com/payment/failed",
    cancelUrl: "https://your-domain.com/payment/cancelled",
    pendingUrl: "https://your-domain.com/payment/pending"
  }
});

// Handle redirect in your frontend
const handlePaymentComplete = async (status: PaymentStatus) => {
  const redirectUrl = X402Protocol.getRedirectUrl(paymentRequest, status);
  if (redirectUrl) {
    window.location.href = redirectUrl;
  }
};

Error Recovery

Handle failed transactions and implement recovery mechanisms.

Retry Failed Transaction

bash

POST /api/payments/:paymentId/transaction/retry

Request Body

Parameter	Type	Description
gasPrice	string?	Optional gas price for retry (in wei)
maxFeePerGas	string?	Optional max fee per gas (EIP-1559)
maxPriorityFeePerGas	string?	Optional max priority fee per gas (EIP-1559)

Response

json

{
  "status": 200,
  "data": {
    "transaction": {
      "hash": "0x...",
      "status": "pending",
      "previousHash": "0x...",
      "retryCount": 1,
      "timestamp": "2024-03-21T12:00:00Z"
    }
  }
}

The system will automatically attempt to recover from common transaction failures: - Insufficient gas: Will retry with higher gas price - Nonce issues: Will automatically adjust nonce - Network congestion: Will implement exponential backoff

Error Recovery Status

Status	Description
retrying	Transaction is being retried with adjusted parameters
recovered	Transaction was successfully recovered
failed	Transaction failed after all retry attempts

Error Response Format

All API errors follow a standardized format for easier handling and debugging.

json

{
  "status": 401,
  "message": "Unauthorized: Missing or invalid API key",
  "code": "INVALID_API_KEY",
  "details": null,
  "data": null
}

Common Error Codes

Code	Description
INVALID_API_KEY	API key is missing, invalid, or revoked
RATE_LIMIT_EXCEEDED	Too many requests; rate limit exceeded
EXPIRED_PAYMENT	Payment request has expired
INSUFFICIENT_FUNDS	Wallet does not have enough funds
INTERNAL_SERVER_ERROR	Unexpected server error

Process Transaction

Handle transaction processing with the processTransaction function.

typescript

processTransaction(
  paymentId: string,
  walletAddress: string,
  merchantWalletAddress: string,
  amount: string,
  currency: string
)

Parameter	Type	Description
paymentId	string	ID of the payment request to process
walletAddress	string	Sender's wallet address
merchantWalletAddress	string	Recipient's wallet address
amount	string	Payment amount
currency	string	Payment currency

Response

json

{
  "success": true,
  "transactionId": "tx-abc123..."
}

The processTransaction function requires all 5 parameters to be provided as separate arguments. Do not pass them as a single object. The function will return an error if any required parameter is missing.