Direct API integration

Integrate with Kobaru using raw JSON/REST endpoints for complete control over the payment flow. This approach is ideal for non-TypeScript backends, enterprises building proprietary payment workflows, or when you need intricate internal orchestration.

Overview

The Direct API integration gives you full control by calling Kobaru's endpoints directly. You implement four steps in your API:

Return HTTP 402 with payment requirements when payment is needed

Parse the PAYMENT-SIGNATURE header from the client's payment proof

Call Kobaru's API to verify or settle the payment

Return the response with payment confirmation

This approach works with any programming language or framework: Go, Python, Rust, Java, Ruby, PHP, or any language that can make HTTP requests.

Authentication

All requests to Kobaru's API require your API key in the Authorization header:

Header	Value	Description
`Authorization`	`Bearer <API_KEY>`	Your Kobaru API key from the console
`Content-Type`	`application/json`	Required for all POST requests

API keys follow the format kbr_{env}_{random} where env is live or test.

Step 1: Return Payment Required (HTTP 402)

When a request requires payment and no valid payment proof is provided, return an HTTP 402 response with the PAYMENT-REQUIRED header.

Response Format

The PAYMENT-REQUIRED header contains a base64-encoded JSON object with payment options.

Payment Required Structure

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.yourcompany.com/premium-data",
    "description": "Premium data access",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "1000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "YourSolanaWalletAddress...",
      "maxTimeoutSeconds": 60
    }
  ],
  "extensions": {
    "usage": {
      "model": "pay_per_request",
      "limit": 1,
      "unit": "request"
    }
  }
}

Payment Required Fields

Field	Type	Required	Description
`x402Version`	integer	Yes	Must be `2` for x402 v2 protocol
`error`	string	Yes	Human-readable error message
`resource`	object	No	Information about the requested resource
`resource.url`	string	Yes	Full URL of the requested resource
`resource.description`	string	No	Human-readable description of the resource
`resource.mimeType`	string	No	MIME type of the resource
`accepts`	array	Yes	Array of accepted payment methods
`extensions`	object	No	Protocol extensions (e.g., usage tracking)

Payment Method Fields (accepts array items)

Field	Type	Required	Description
`scheme`	string	Yes	Payment scheme. Currently only `exact` is supported
`network`	string	Yes	CAIP-2 network identifier (e.g., `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)
`amount`	string	Yes	Payment amount in atomic units (e.g., `1000` = 0.001 USDC)
`asset`	string	Yes	Token mint address for Solana (USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`)
`payTo`	string	Yes	Your wallet address to receive payment
`maxTimeoutSeconds`	integer	No	Maximum time for payment completion. Default: 60

Supported Networks

Network	CAIP-2 Identifier	Environment
Solana Mainnet	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	Production
Solana Devnet	`solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`	Testing

Amount Calculation

Amounts are specified in atomic units (smallest denomination):

Human Amount	USDC Atomic Units	Calculation
$0.001	`1000`	0.001 x 10^6
$0.01	`10000`	0.01 x 10^6
$0.10	`100000`	0.1 x 10^6
$1.00	`1000000`	1 x 10^6

USDC uses 6 decimal places, so multiply the dollar amount by 1,000,000.

Constructing the Header

Step 2: Parse Payment Signature

When a client submits payment proof, they include it in the PAYMENT-SIGNATURE header as a base64-encoded JSON object.

Decoding the Header

Payment Payload Structure

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.yourcompany.com/premium-data",
    "description": "Premium data access",
    "mimeType": "application/json"
  },
  "accepted": {
    "scheme": "exact",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "amount": "1000",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payTo": "YourSolanaWalletAddress...",
    "maxTimeoutSeconds": 60
  },
  "payload": {
    "transaction": "BASE64_ENCODED_SOLANA_TRANSACTION..."
  }
}

Payment Payload Fields

Field	Type	Required	Description
`x402Version`	integer	Yes	Must be `2`
`resource`	object	No	Resource being accessed (echoed from requirements)
`accepted`	object	No	The payment method the client accepted
`payload`	object	Yes	Scheme-specific payment data
`payload.transaction`	string	Yes	Base64-encoded Solana transaction (for Solana exact scheme)
`extensions`	object	No	Protocol extensions

Step 3: Verify or Settle with Kobaru

Kobaru provides two endpoints for payment processing:

Endpoint	Purpose	When to Use
`POST /verify`	Validates payment without executing on-chain	Pre-authorization, checking transaction validity
`POST /settle`	Validates AND executes payment on-chain	Capturing funds when ready to deliver content

Request Schema

Both endpoints use the same request format:

{
  "paymentPayload": {
    "x402Version": 2,
    "resource": {
      "url": "https://api.yourcompany.com/premium-data",
      "description": "Premium data access",
      "mimeType": "application/json"
    },
    "accepted": {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "1000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "YourSolanaWalletAddress...",
      "maxTimeoutSeconds": 60
    },
    "payload": {
      "transaction": "BASE64_ENCODED_SOLANA_TRANSACTION..."
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "amount": "1000",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payTo": "YourSolanaWalletAddress...",
    "maxTimeoutSeconds": 60
  }
}

Request Fields

Field	Type	Required	Description
`paymentPayload`	object	Yes	The payment authorization from the client (decoded from PAYMENT-SIGNATURE header)
`paymentRequirements`	object	Yes	The payment requirements you originally specified

Payment Requirements Fields

Field	Type	Required	Description
`scheme`	string	Yes	Must be `exact`
`network`	string	Yes	CAIP-2 network identifier
`amount`	string	Yes	Payment amount in atomic units
`asset`	string	Yes	Token mint address
`payTo`	string	Yes	Your wallet address
`maxTimeoutSeconds`	integer	No	Maximum timeout in seconds (default: 60)

POST /verify

Validates the payment transaction structure and signatures without executing it on the blockchain. Use this when you want to pre-authorize a payment before delivering content.

cURL Example

Success Response (200 OK)

{
  "isValid": true,
  "payer": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Field	Type	Description
`isValid`	boolean	`true` if payment is valid
`payer`	string	Wallet address of the payer

Error Response (400 Bad Request)

{
  "isValid": false,
  "invalidReason": "invalid_exact_solana_payload_authorization_value",
  "payer": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Field	Type	Description
`isValid`	boolean	`false` if payment is invalid
`invalidReason`	string	Error code explaining why the payment is invalid
`payer`	string	Wallet address of the payer (if available)

Simulation Failure Response

When a transaction simulation fails, additional debugging information is provided:

{
  "isValid": false,
  "invalidReason": "simulation_failed",
  "simulationDetails": {
    "error": "Instruction 2: InsufficientFunds",
    "errorCode": "InsufficientFunds",
    "logs": [
      "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA invoke [1]",
      "Program log: Error: insufficient lamports",
      "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 3452 of 200000 compute units"
    ]
  }
}

Field	Type	Description
`simulationDetails`	object	Present only when `invalidReason` is `simulation_failed`
`simulationDetails.error`	string	Human-readable error message
`simulationDetails.errorCode`	string	Solana error code
`simulationDetails.logs`	array	Last 5 program log lines for debugging

POST /settle

Validates AND executes the payment on the blockchain. Use this when you are ready to capture funds and deliver content.

cURL Example

Success Response (200 OK)

{
  "success": true,
  "transaction": "5wHu1qwD7q4XJJnYZcPcqL8mPwRfzAQCHQ2X4KxEaJhbNgVbPjKtqZY8jW3xLqNpMdR9vS2KuHfA8yXtEcJgWmNr",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "payer": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}

Field	Type	Description
`success`	boolean	`true` if settlement succeeded
`transaction`	string	Solana transaction signature (can be viewed on Solana Explorer)
`network`	string	CAIP-2 network identifier where the transaction was executed
`payer`	string	Wallet address of the payer

Error Response (400 Bad Request)

{
  "success": false,
  "errorReason": "simulation_failed"
}

Field	Type	Description
`success`	boolean	`false` if settlement failed
`errorReason`	string	Error code explaining why settlement failed

Step 4: Return Payment Response

After successful verification or settlement, include the result in your response using the PAYMENT-RESPONSE header.

Success Response Format

Constructing the Header

Complete Node.js Example

Here is a complete, working example using Express:

Environment Variables

Error Codes

General Errors

Error Code	HTTP Status	Description	Troubleshooting
`invalid_x402_version`	400	x402Version is not 2	Ensure `x402Version: 2` in paymentPayload
`invalid_payload`	400	Missing, invalid, or malformed payload	Check JSON structure matches the schema
`invalid_payment_requirements`	400	Missing or invalid requirements	Verify all required fields are present
`invalid_network`	400	Invalid or unsupported network	Use valid CAIP-2 format (e.g., `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)
`unsupported_scheme`	400	Scheme not supported	Only `exact` scheme is currently supported
`capability_not_enabled`	400	Client lacks this capability	Enable the network/scheme/asset in Kobaru console
`duplicate_request`	400	Concurrent request in progress	Wait for the first request to complete
`unexpected_verify_error`	500	Server error during verification	Retry the request
`unexpected_settle_error`	500	Server error during settlement	Retry the request

Solana-Specific Errors

Error Code	HTTP Status	Description	Troubleshooting
`invalid_exact_solana_payload_authorization_value`	400	Amount does not match requirements	Ensure transaction transfers the exact amount
`invalid_exact_solana_payload_recipient_mismatch`	400	Wrong destination address	Verify `payTo` address matches
`invalid_asset_mismatch`	400	Wrong token mint	Use correct token address (USDC mint)
`invalid_fee_payer`	400	Fee payer is not the facilitator	Kobaru must be the fee payer
`invalid_transaction_format`	400	Cannot decode transaction	Ensure transaction is valid base64
`missing_compute_budget_limit`	400	Missing SetComputeUnitLimit instruction	Add compute budget instructions
`missing_compute_budget_price`	400	Missing SetComputeUnitPrice instruction	Add compute budget instructions
`priority_fee_exceeds_limit`	400	Priority fee too high	Reduce priority fee below limit
`invalid_instruction_count_topology`	400	Wrong instruction order	Follow required instruction order
`facilitator_cannot_be_payer`	400	Facilitator wallet is the source	Use a different source wallet
`simulation_failed`	400	Transaction simulation failed	Check payer has sufficient balance
`submission_failed`	400	Transaction broadcast failed	Retry the settlement

Best Practices

1. Validate Payment Requirements Match

Always verify that the accepted field in the payment payload matches what you required:

2. Use Idempotency for Retries

Kobaru's endpoints are idempotent. The same transaction will return the same result, making it safe to retry on network errors:

3. Handle Errors Gracefully

Provide meaningful error messages to clients:

4. Test on Devnet First

Always test your integration on Solana Devnet before going to production:

Get test USDC from spl-token-faucet.com for Devnet testing.

5. Secure Your API Key

Never expose your API key in client-side code:

Store API keys in environment variables

Use server-side calls to Kobaru's API only

Rotate keys if they are accidentally exposed

6. Log Payment Information

Log payment details for debugging and auditing:

HTTP Status Codes Summary

Status Code	Meaning	When Returned
200	OK	Payment verified/settled successfully
400	Bad Request	Invalid payment or malformed request
402	Payment Required	No payment provided or payment invalid
500	Internal Server Error	Unexpected server error

Transparent proxy integration - Zero-code integration option

Standard SDK integration - SDK-based integration for TypeScript

Advanced SDK - Sessions, budgets, and analytics (coming soon)

POST /v1/verify API reference - Complete verify endpoint documentation

POST /v1/settle API reference - Complete settle endpoint documentation

Error codes reference - Complete list of all error codes

Direct API integration

Direct API integration#

Overview#

Authentication#

Step 1: Return Payment Required (HTTP 402)#

Response Format#

Payment Required Structure#

Payment Required Fields#

Payment Method Fields (accepts array items)#

Supported Networks#

Amount Calculation#

Constructing the Header#

Step 2: Parse Payment Signature#

Decoding the Header#

Payment Payload Structure#

Payment Payload Fields#

Step 3: Verify or Settle with Kobaru#

Request Schema#

Request Fields#

Payment Requirements Fields#

POST /verify#

cURL Example#

Success Response (200 OK)#

Error Response (400 Bad Request)#

Simulation Failure Response#

POST /settle#

cURL Example#

Success Response (200 OK)#

Error Response (400 Bad Request)#

Step 4: Return Payment Response#

Success Response Format#

Constructing the Header#

Complete Node.js Example#

Environment Variables#

Error Codes#

General Errors#

Solana-Specific Errors#

Best Practices#

1. Validate Payment Requirements Match#

2. Use Idempotency for Retries#

3. Handle Errors Gracefully#

4. Test on Devnet First#

5. Secure Your API Key#

6. Log Payment Information#

HTTP Status Codes Summary#

Related documentation#

Direct API integration

Overview

Authentication

Step 1: Return Payment Required (HTTP 402)

Response Format

Payment Required Structure

Payment Required Fields

Payment Method Fields (accepts array items)

Supported Networks

Amount Calculation

Constructing the Header

Step 2: Parse Payment Signature

Decoding the Header

Payment Payload Structure

Payment Payload Fields

Step 3: Verify or Settle with Kobaru

Request Schema

Request Fields

Payment Requirements Fields

POST /verify

cURL Example

Success Response (200 OK)

Error Response (400 Bad Request)

Simulation Failure Response

POST /settle

cURL Example

Success Response (200 OK)

Error Response (400 Bad Request)

Step 4: Return Payment Response

Success Response Format

Constructing the Header

Complete Node.js Example

Environment Variables

Error Codes

General Errors

Solana-Specific Errors

Best Practices

1. Validate Payment Requirements Match

2. Use Idempotency for Retries

3. Handle Errors Gracefully

4. Test on Devnet First

5. Secure Your API Key

6. Log Payment Information

HTTP Status Codes Summary

Related documentation