# 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

```bash
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

```json
{
    "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:

```bash
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

```bash
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

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rozo.ai/integration/api-doc/api-for-advanced-used/stellar-contract-payments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.