# Payment intents (https://dev.cosmospay.lat/docs/sdk/server/payment-intents/)

> Create, fetch, list, edit, cancel, delete and validate payment intents on Stellar (SEP-7), Solana (Solana Pay) and Monad (EIP-681).

A payment intent represents one payment you want a user to make. It is the core resource of the API and the manager you will reach for most often.

`client.paymentIntents` — payment intents on Stellar, Solana and Monad. Two kinds:

- **`pay` intent** — no source. The payer's wallet picks the source account.
  Produces a payment link + QR (no XDR): `web+stellar:pay?...` on Stellar (the default),
  a Solana Pay link with `chain: 'solana'`, an EIP-681 link with `chain: 'monad'`.
- **`tx` intent** — source known (Stellar only). Produces an unsigned XDR +
  `web+stellar:tx?...` URI + QR.

## Create

```ts
import { Assets, TestnetAssets } from '@cosmosapp/pay_sdk';

const usdc = process.env.COSMOS_PAY_API_KEY?.startsWith('prod_')
  ? Assets.USDC
  : TestnetAssets.USDC;

// pay (no source)
const pay = await client.paymentIntents.createPay({
  destination: 'G...',          // required — payee (or an address-book name)
  amount: '10',                 // optional — omit for an open amount (donations)
  asset: usdc,                  // issuer matches the API key network
  // assetCode: 'USDC', assetIssuer: 'G...',  // …or set them explicitly
  // omit asset entirely for native lumens (XLM)
  memo: '123456789',            // optional MEMO_ID (uint64) — auto-generated if omitted
  msg: 'Order #24',             // optional, ≤ 300 chars, shown in the wallet
  callback: 'url:https://...',  // optional SEP-7 callback for the signed XDR
});

// pay on Solana or Monad: name the chain; the destination is an address on that chain
const sol = await client.paymentIntents.createPay({
  chain: 'solana',              // 'stellar' (default) | 'solana' | 'monad'
  destination: '7xKX...',       // Solana address (Monad: 0x...)
  amount: '25',                 // required on Monad
  assetCode: 'USDC',            // a token by code + issuer (SPL mint / ERC-20 contract)
  assetIssuer: 'EPjF...Dt1v',
});
console.log(sol.chain, sol.uri); // 'solana', 'solana:...'

// tx (source known)
const tx = await client.paymentIntents.createTx({
  source: 'G...PAYER',          // required (extra vs pay)
  destination: 'G...MERCHANT',
  amount: '25.5',
});
console.log(tx.xdr, tx.uri, tx.qr);
```

> Amounts are **decimal strings**, max 7 decimals. Asset issuers are
> network-specific (mainnet vs testnet).

## Fetch / list

```ts
const intent = await client.paymentIntents.fetch('pi_123');

const page = await client.paymentIntents.list({
  status: 'SUCCEEDED', // optional filter (PaymentIntentStatus)
  chain: 'solana',     // optional: 'stellar' | 'solana' | 'monad'
  createdFrom: new Date('2026-11-01'), // optional: created at or after (Date or ISO 8601)
  take: 50,            // page size, max 100, default 20
  skip: 0,             // offset
});
// page → { items: PaymentIntent[], total, take, skip }
```

## Update / cancel / delete

```ts
await intent.edit({ reference: 'order_1234' }); // status / txHash / reference
await intent.cancel();                          // → status CANCELLED
await intent.delete();
// manager forms: client.paymentIntents.update(id, {...}) / .delete(id)
```

## Validate (finalize)

```ts
const outcome = await intent.validate('<txHash>');
// → { valid, status, reason, paymentIntent }
if (outcome.valid) console.log('settled', outcome.status);
// manager form: client.paymentIntents.validate(id, { txHash })
```

Validation checks tx success + destination + amount + memo, finalizes the status
server-side, and fires the webhook.

## Structure accessors (on a `PaymentIntent`)

`id`, `kind`, `status`, `chain`, `network`, `source`, `destination`, `amount`, `asset`,
`assetIssuer`, `memo`, `msg`, `callback`, `xdr`, `uri`, `qr`, `txHash`,
`reference`, `createdAt`, `updatedAt`. Helpers: `isTx`, `isPay`, `isSucceeded`,
`isPending`, `assetLabel` (the chain's coin for native: `'XLM'`, `'SOL'` or `'MON'`). Methods: `fetch()`, `edit()`,
`validate(txHash)`, `cancel()`, `delete()`, `toJSON()`.

## References

- [Assets](https://dev.cosmospay.lat/docs/sdk/web/assets-wallets-addresses/): Typed asset / wallet catalog or address helper.
- [PaymentIntent](https://dev.cosmospay.lat/docs/sdk/definitions/server/payment-intent/): A Stellar SEP-7 payment intent
- [TestnetAssets](https://dev.cosmospay.lat/docs/sdk/web/assets-wallets-addresses/): Typed asset / wallet catalog or address helper.
