Stellar Smart Account Payments

Stellar Contract Payments enable payments from Stellar to EVM and Solana chains via Soroban smart contract addresses (C-addresses). Users pay by invoking a contract's pay() function with a unique memo, and the system triggers cross-chain payout once payment is detected.

API Host: https://intentapiv4.rozo.ai/functions/v1

Supported Routes

Source Chain	Source Token	Destination Chain	Destination Token
Stellar (1500)	USDC	Base (8453)	USDC
Stellar (1500)	USDC	BNB Chain (56)	USDT
Stellar (1500)	USDC	BNB Chain (56)	USDC
Stellar (1500)	USDC	Ethereum (1)	USDT
Stellar (1500)	USDC	Ethereum (1)	USDC
Stellar (1500)	USDC	Arbitrum (42161)	USDC
Stellar (1500)	USDC	Polygon (137)	USDC
Stellar (1500)	USDC	Solana (501)	USDC

Overview

When using stellar_payin_contracts intent:

1. A unique Soroban contract address (receiverAddressContract) and memo (receiverMemoContract) are generated

2. User invokes the contract's pay() function with the amount and memo

3. System monitors the contract for the payment

4. Cross-chain payout is triggered once payment is detected

Payment Intent Types

Intent	Description
stellar_payin_contracts	User pays by invoking a Soroban contract's pay() function with a unique memo.

Create Payment with Contract Intent

Request

curl --location --request POST 'https://intentapiv4.rozo.ai/functions/v1/payment-api/payments' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "yourAppId",
    "intent": "stellar_payin_contracts",
    "type": "exactOut",
    "display": {
        "title": "Order #12345",
        "currency": "USD"
    },
    "source": {
        "senderAddress": "CBHKUT4SOTRYXJBQIOKXSW47CU2PF56OWXCML4XBQZAZLRX6R7TTNE4R",
        "chainId": 1500,
        "tokenSymbol": "USDC"
    },
    "destination": {
        "receiverAddress": "0x5772FBe7a7817ef7F586215CA8b23b8dD22C8897",
        "chainId": 8453,
        "tokenSymbol": "USDC",
        "amount": "1"
    }
}'

Response

{
    "id": "ae718e1b-74d3-485b-bebc-c5208850b400",
    "appId": "yourAppId",
    "orderId": null,
    "status": "payment_unpaid",
    "errorCode": null,
    "type": "exactOut",
    "createdAt": "2026-04-04T14:56:21.279+00:00",
    "updatedAt": "2026-04-04T14:56:21.279+00:00",
    "expiresAt": "2026-04-04T15:56:21.279+00:00",
    "display": {
        "title": "Order #12345",
        "description": null,
        "currency": "USD"
    },
    "source": {
        "chainId": "1500",
        "tokenSymbol": "USDC",
        "tokenAddress": "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",
        "amount": "1.01",
        "receiverAddress": "CC4ING2NYT2ZKA5RGSJYPQFLWW4BTSBVADFXNBFMYBJ7GNPZVF4A6FFB",
        "receiverMemo": null,
        "fee": "0.01",
        "senderAddress": null,
        "txHash": null,
        "amountReceived": null,
        "confirmedAt": null,
        "receiverAddressContract": "CAQPKW5AUPEA4C7OERZRUCBWT5RZDSETO4PR5REVRC5MT4CF3PBSKXQC",
        "receiverMemoContract": "memo_1775314581279"
    },
    "destination": {
        "chainId": "8453",
        "receiverAddress": "0x5772FBe7a7817ef7F586215CA8b23b8dD22C8897",
        "receiverMemo": null,
        "tokenSymbol": "USDC",
        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "1.00",
        "txHash": null,
        "confirmedAt": null
    }
}

Key Response Fields

Field	Description
source.receiverAddressContract	The Soroban contract address to invoke pay() on
source.receiverMemoContract	The unique memo to pass to the pay() function
source.amount	Total amount to pay (includes fee)
source.fee	Fee amount deducted from the source payment
destination.amount	Amount the receiver will get on the destination chain

How to Pay

After creating a payment, the user invokes the Soroban contract's pay() function:

pay(sender, amount, memo)

Parameter	Value	Example
Contract	source.receiverAddressContract	CAQPKW5AUPEA4C7OERZRUCBWT5RZDSETO4PR5REVRC5MT4CF3PBSKXQC
sender	The user's Stellar address	CBHK...NE4R
amount	source.amount in stroops (multiply by 10^7)	10100000 for 1.01 USDC
memo	source.receiverMemoContract	memo_1775314581279

On-chain, the invocation looks like:

invoked contract CAQP…KXQC pay(CBHK…NE4R, 10100000i128, "memo_1775314581279"str)

The system detects this contract invocation and triggers the cross-chain payout to the destination address.

Combining with Any Amount

You can combine Stellar Contract Payments with Any Amount for flexible top-up flows:

curl --location --request POST 'https://intentapiv4.rozo.ai/functions/v1/payment-api/payments' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "yourAppId",
    "type": "anyAmount",
    "intent": "stellar_payin_contracts",
    "display": {
        "title": "Flexible Top-up",
        "currency": "USD"
    },
    "source": {
        "chainId": 1500,
        "tokenSymbol": "USDC"
    },
    "destination": {
        "chainId": 8453,
        "receiverAddress": "0x1234567890abcdef1234567890abcdef12345678",
        "tokenSymbol": "USDC"
    }
}'

When using anyAmount with contract payments, any amount between $0.02 - $10,000 USDC is accepted.

Register Transaction Hash (Optional)

For faster payment tracking and accurate sender information, you can pre-register the transaction hash and sender address after the user submits their payment:

Request

curl --location --request POST 'https://intentapiv4.rozo.ai/functions/v1/payment-api/payments/{paymentId}/payin' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "txHash": "abc123def456...",
    "fromAddress": "GABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890ABCDEFGH"
}'

Response

{
  "success": true,
  "message": "Transaction hash registered successfully",
  "payment": {
    "id": "abc123-def456-789",
    "status": "payment_unpaid",
    "source": {
      "txHash": "abc123def456...",
      "senderAddress": "GABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890ABCDEFGH"
    }
  }
}

Payment Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Create    │     │    User     │     │   System    │     │   Payout    │
│   Payment   │────▶│  Invokes    │────▶│   Detects   │────▶│  Triggered  │
│             │     │   pay()     │     │  Contract   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │                   │
       ▼                   ▼                   ▼                   ▼
  Contract addr       User calls          Contract            Funds sent
  and memo are       pay(sender,         invocation          cross-chain
  returned           amount, memo)       is detected         to destination

Supported Tokens

Currently only USDC is supported as the source token on Stellar for contract payments.

Token	Contract Address
USDC	CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75

Error Handling

Error Code	Description
paymentNotFound	Payment ID does not exist
paymentNotUpdatable	Payment is not in a status that allows updates
invalidRequest	Missing or invalid request parameters

Best Practices

1. Pre-register transactions: Use the /payin endpoint to register txHash and fromAddress immediately after the user submits their payment. This ensures accurate tracking.

2. Poll for status: After creating a payment, poll GET /payments/{id} to check for status updates. Look for payment_payin_completed and payment_payout_completed.

3. Handle expiration: Payments expire after 1 hour. Ensure your UI communicates this to users.