Moove Payment Links

Create a payment link, hand the payer its URL, take payment status from webhooks, and reconcile against the list endpoint.

Base URL https://api.moove.xyz. Generated against openapi.json.

Create a payment link

endpoint

required

Requires the payment_link:create scope.

Creates a payment link and returns its id and shareable checkout url — send the payer to that URL.

The link settles to the authenticated user’s default wallet, in that wallet’s chain and token. toAmount is denominated in that token. The destination cannot be specified by the caller.

Body

number | string

required

Amount to request, denominated in the settlement token of the authenticated user’s default wallet. Must be greater than 0.Send it as a string to avoid floating-point rounding.It must also fit the settlement token’s decimal precision. The amount is quantised to the token’s decimals; if that changes the value, the request is rejected with 422 INVALID_PAYMENT_LINK_AMOUNT.USDC has 6 decimals, so against a USDC wallet:

`toAmount`	Result
`"49.99"`	Accepted
`"49.999999"`	Accepted — exactly 6 decimals
`"49.9999999"`	Rejected — 7 decimals
`"100.0000000"`	Accepted — trailing zeros are not significant

Different tokens have different precision, and the limit is the destination wallet’s token, not yours. Read token.decimals from the list endpoint if you need to round before sending.

string

Shown to the payer on the checkout page. Maximum 500 characters.

integer

How many payments the link accepts before it completes. Minimum 1. Unlimited when omitted.

string

ISO 8601 timestamp, in the future. After it passes the link stops accepting payments. Never expires when omitted.

Request

curl -sS -X POST "https://api.moove.xyz/v1/payment-link" \
  -H "X-API-Key: $MOOVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toAmount": "49.99",
    "description": "INV-2026-0142",
    "maxUsage": 1,
    "expirationDate": "2026-12-31T23:59:59Z"
  }'

import httpx

res = httpx.post(
    "https://api.moove.xyz/v1/payment-link",
    headers={"X-API-Key": MOOVE_API_KEY},
    json={
        "toAmount": "49.99",
        "description": "INV-2026-0142",
        "maxUsage": 1,
        "expirationDate": "2026-12-31T23:59:59Z",
    },
)
res.raise_for_status()
link = res.json()

const res = await fetch('https://api.moove.xyz/v1/payment-link', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.MOOVE_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    toAmount: '49.99',
    description: 'INV-2026-0142',
    maxUsage: 1,
    expirationDate: '2026-12-31T23:59:59Z',
  }),
});

if (!res.ok) throw new Error(`${res.status}`);
const link = await res.json();

Response

string

required

The payment link’s id.

string

required

The shareable checkout URL. Send the payer here.

200

{
  "id": "0c8f2e5a-4b91-4c3e-9d17-2f6a8b0d1e34",
  "url": "https://moove.xyz/@yourhandle/pay/0c8f2e5a-4b91-4c3e-9d17-2f6a8b0d1e34"
}

Create returns only id and url — not the full record. Status, token and amounts require the list endpoint. This is deliberate: the caller’s job is to produce a link, and a second round-trip to learn the URL would accomplish nothing.

List payment links

endpoint

required

Requires the payment_link:read scope.

Returns the payment links belonging to the authenticated user, newest first, 10 per page.

A key sees every link its owner can see — including links created from the dashboard or by a sibling key. This is the endpoint to reconcile against.

Query parameters

string

Filter by status. One of active, inactive, completed. Omit for all.

integer

default:"0"

Page offset. Follow nextOffset from the previous response.

Request

curl -sS "https://api.moove.xyz/v1/payment-link?status=active&offset=0" \
  -H "X-API-Key: $MOOVE_API_KEY"

res = httpx.get(
    "https://api.moove.xyz/v1/payment-link",
    headers={"X-API-Key": MOOVE_API_KEY},
    params={"status": "active", "offset": 0},
)
res.raise_for_status()
page = res.json()

const url = new URL('https://api.moove.xyz/v1/payment-link');
url.searchParams.set('status', 'active');
url.searchParams.set('offset', '0');

const res = await fetch(url, {
  headers: { 'X-API-Key': process.env.MOOVE_API_KEY! },
});
const page = await res.json();

Response

PaymentLinkData[]

required

The page of results.

Show PaymentLinkData

string

required

The link’s id.

string

required

The owner’s user id.

string

required

Amount requested, in the settlement token.

string

required

The wallet address the link settles to.

string

required

The shareable checkout URL.

string

required

ISO 8601 creation timestamp.

TokenData

required

The settlement token, including its chain.

string

required

active, completed or inactive.

string | null

What the payer sees.

integer | null

Usage cap, if set.

string | null

Total paid against the link so far.

string | null

Expiry, if set.

string | null

Always null in list responses. Read it from retrieve.

integer

required

Results per page. Fixed at 10.

integer

required

The offset this page was fetched at.

integer | null

Offset for the next page. null at the end.

200

{
  "data": [
    {
      "id": "0c8f2e5a-4b91-4c3e-9d17-2f6a8b0d1e34",
      "userId": "9b1d4c77-0a3e-4f52-8c61-77ab2d90ef15",
      "toAmount": "49.99",
      "destinationAddress": "0x5f3a...c81b",
      "url": "https://moove.xyz/@yourhandle/pay/0c8f2e5a-4b91-4c3e-9d17-2f6a8b0d1e34",
      "dateCreated": "2026-08-14T09:21:03Z",
      "token": {
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "decimals": 6,
        "symbol": "USDC",
        "name": "USD Coin",
        "logo": "https://cdn.moove.xyz/assets/images/tokens/usdc.svg",
        "isNative": false,
        "isStablecoin": true,
        "isVerified": true,
        "currencyCode": "USD",
        "commodityCode": null,
        "priceUsd": "1.0001",
        "chain": {
          "id": "8453",
          "name": "Base",
          "symbol": "BAS",
          "chainType": "EVM",
          "logo": "https://…"
        }
      },
      "status": "active",
      "description": "INV-2026-0142",
      "maxUsage": 1,
      "receivedAmount": null,
      "expirationDate": "2026-12-31T23:59:59Z",
      "transactionUrl": null
    }
  ],
  "limit": 10,
  "offset": 0,
  "nextOffset": null
}

Pagination →

Retrieve a payment link

endpoint

required

No authentication. This endpoint is public.

Returns a single payment link by id, enriched with its owner’s public profile.

This endpoint is unauthenticated by design, and its response is public.It is what the hosted checkout page calls to render a link: the payer has no Moove account and no API key, so requiring either would make the link unpayable. Anyone holding a link id can read it.It returns the owner’s public profile — handle, username, profile image — the same fields their Moove Profile already shows. It does not expose anything private to the account. Treat a link id as a shareable secret: it is not a credential, but it does identify a request for payment.

Request

curl -sS "https://api.moove.xyz/v1/payment-link/0c8f2e5a-4b91-4c3e-9d17-2f6a8b0d1e34"

res = httpx.get(
    f"https://api.moove.xyz/v1/payment-link/{link_id}",
)
res.raise_for_status()
link = res.json()

const res = await fetch(
  `https://api.moove.xyz/v1/payment-link/${linkId}`,
);
if (!res.ok) throw new Error(`${res.status}`);
const link = await res.json();

Response

Every field of PaymentLinkData — as returned by list — plus:

UserData

required

The link owner’s public profile.

Show UserData

string

required

The owner’s user id.

string

required

Their Moove Handle, without the @.

string

required

Their display name.

string

required

ISO 8601 timestamp the account was created.

string | null

Profile image URL.

string | null

Their bio.

string | null

Profile background image URL.

string | null

Profile background colour.

string[] | null

Links shown on their profile.

boolean | null

Whether the owner has a Moove account.

object | null

Contact relationship with the caller. Always null here — this endpoint has no caller.

object[] | null

Profile badges.

UserWalletData

required

The wallet the link settles to.

Show UserWalletData

string

required

The wallet address.

object

required

The settlement token: id plus a token object shaped like TokenData.

string

required

The chain family, such as EVM.

boolean

required

Whether this is the owner’s default wallet.

boolean

required

Whether this is the default wallet for its chain.

string | null

The wallet provider, if known.

string | null

A PaymentLinkData field, populated only here. null until the link is completed; then the moove.xyz page for its most recent settled payment, https://moove.xyz/tx/{id}. Not a block-explorer link.

Use this to build your own checkout page against a link you created. For reconciliation across many links, use list — it is scoped to your key and pages properly.

Errors

Status	`code`	Meaning
`404`	`CANNOT_FIND_PAYMENT_LINK`	No link with that id

Errors

Branch on code, never on message.

Status	`code`	Meaning	Retry?
`401`	`UNAUTHENTICATED`	No `X-API-Key` header	No
`401`	`INVALID_API_KEY`	Unknown, revoked or deactivated key	No
`401`	`EXPIRED_API_KEY`	The key is past its expiry	No
`403`	`INSUFFICIENT_API_SCOPE`	Key lacks the scope this endpoint needs	No
`404`	`CANNOT_FIND_PAYMENT_LINK`	Retrieve: no link with that id. List: the lookup failed unexpectedly	Retrieve: no. List: yes, with backoff
`409`	`PAYMENT_LINK_ACCOUNT_NOT_READY`	Owner has no default wallet, or no handle	No
`422`	`INVALID_PAYMENT_LINK_AMOUNT`	`toAmount` exceeds the settlement token’s decimals	No
`429`	`429`	Rate limited, per key and per IP	Yes, with backoff
`500`	`CANNOT_CREATE_PAYMENT_LINK`	Creation failed	Yes, with backoff

A malformed body is also a 422, raised by request validation before it reaches any of the above. errors carries one entry per problem: message describes the rule that failed and code is a validation type such as missing, greater_than or json_invalid. The field is not named.

422

{ "errors": [{ "message": "Field required", "code": "missing" }] }

INVALID_API_KEY deliberately covers unknown, revoked and deactivated keys with one message. Distinguishing them would tell an attacker whether a guessed key ever existed.

A 409 means the key owner has no default wallet or no handle. Nothing in your code can fix it — surface it to the user.

Errors →

Get paid without polling

Webhooks

Register an HTTPS endpoint and Moove POSTs a signed body when a link is paid, and again when a payment completes it. Deactivation and expiry send no event. Keep GET /v1/payment-link for reconciling those, and anything a delivery missed.

Not in the API

Deactivating a link is a dashboard action, not an API call. Manage links at moove.xyz/dashboard/payment-link.Registering a webhook endpoint is also a console action, at moove.xyz/business/manage/webhooks. Both are done by a signed-in person, not by a key.

Pagination

Page through every link.

Moove Agentic Payments

Build the integration with a prompt.