# Payment links

Shareable hosted checkout links.

## List payment links

`GET /v1/payment-links`

### Query parameters

- `merchantId` `string`

### Responses

#### `200`: Payment links.

Body (`application/json`):

- `id` `string` _(required)_
- `kind` `string` _(required)_: fixed, open, or catalog
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object & object | null` _(required)_
- `currency` `string | null` _(required)_
- `lines` `array | null` _(required)_
- `title` `string | null` _(required)_
- `merchantReference` `string | null` _(required)_
- `metadata` `object` _(required)_
- `url` `string` _(required)_
- `payable` `boolean` _(required)_
- `listed` `boolean` _(required)_: Whether it appears in the public x402 payable index.
- `expiresAt` `string | null` _(required)_
- `disabledAt` `string | null` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `401`: Missing or unknown API key.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl 'https://api.mayarin.xyz/v1/payment-links?merchantId=string'
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-links?merchantId=string')
```

## Create a payment link

`POST /v1/payment-links`

### Header parameters

- `Idempotency-Key` `string` _(required)_: Stable unique key for this logical write. Keep it unchanged when retrying.

### Request body (`application/json`)

- `kind` `string` _(required)_
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object`
  - `amount` `string` _(required)_
  - `asset` `string` _(required)_
- `currency` `string`
- `lines` `object[]`
  - `productId` `string` _(required)_
  - `quantity` `integer` _(required)_
- `title` `string`
- `merchantReference` `string`
- `metadata` `object`: Your own string pairs, sent back in webhooks. At most 20 keys of up to 64 characters, values of up to 1000, and 8 KB in all.
- `expiresAt` `string <date-time>`
- `listed` `boolean`
- `rails` `object[]`
  - `chain` `string` _(required)_
  - `asset` `string` _(required)_

### Responses

#### `201`: Payment link created.

Body (`application/json`):

- `id` `string` _(required)_
- `kind` `string` _(required)_: fixed, open, or catalog
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object & object | null` _(required)_
- `currency` `string | null` _(required)_
- `lines` `array | null` _(required)_
- `title` `string | null` _(required)_
- `merchantReference` `string | null` _(required)_
- `metadata` `object` _(required)_
- `url` `string` _(required)_
- `payable` `boolean` _(required)_
- `listed` `boolean` _(required)_: Whether it appears in the public x402 payable index.
- `expiresAt` `string | null` _(required)_
- `disabledAt` `string | null` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `400`: Validation error.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

#### `401`: Missing or unknown API key.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/payment-links \
  --request POST \
  --header 'Idempotency-Key: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "kind": "fixed",
  "merchant": {
    "id": "string",
    "name": "string",
    "city": "string",
    "countryCode": "string",
    "categoryCode": "string"
  },
  "amount": {
    "amount": "string",
    "asset": "IDR"
  },
  "currency": "IDR",
  "lines": [
    {
      "productId": "string",
      "quantity": 0
    }
  ],
  "title": "string",
  "merchantReference": "string",
  "metadata": {},
  "expiresAt": "1970-01-01T00:00:00.000Z",
  "listed": true,
  "rails": [
    {
      "chain": "ethereum",
      "asset": "IDR"
    }
  ]
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-links', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    kind: 'fixed',
    merchant: {
      id: 'string',
      name: 'string',
      city: 'string',
      countryCode: 'string',
      categoryCode: 'string'
    },
    amount: {
      amount: 'string',
      asset: 'IDR'
    },
    currency: 'IDR',
    lines: [
      {
        productId: 'string',
        quantity: 0
      }
    ],
    title: 'string',
    merchantReference: 'string',
    metadata: {},
    expiresAt: '1970-01-01T00:00:00.000Z',
    listed: true,
    rails: [
      {
        chain: 'ethereum',
        asset: 'IDR'
      }
    ]
  })
})
```

## Get a payment link

`GET /v1/payment-links/{id}`

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: Payment link.

Body (`application/json`):

- `id` `string` _(required)_
- `kind` `string` _(required)_: fixed, open, or catalog
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object & object | null` _(required)_
- `currency` `string | null` _(required)_
- `lines` `array | null` _(required)_
- `title` `string | null` _(required)_
- `merchantReference` `string | null` _(required)_
- `metadata` `object` _(required)_
- `url` `string` _(required)_
- `payable` `boolean` _(required)_
- `listed` `boolean` _(required)_: Whether it appears in the public x402 payable index.
- `expiresAt` `string | null` _(required)_
- `disabledAt` `string | null` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `404`: No link with that id.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/payment-links/string
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-links/string')
```

## Disable a payment link

`POST /v1/payment-links/{id}/disable`

### Path parameters

- `id` `string` _(required)_

### Header parameters

- `Idempotency-Key` `string` _(required)_: Stable unique key for this logical write. Keep it unchanged when retrying.

### Responses

#### `200`: Disabled payment link.

Body (`application/json`):

- `id` `string` _(required)_
- `kind` `string` _(required)_: fixed, open, or catalog
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object & object | null` _(required)_
- `currency` `string | null` _(required)_
- `lines` `array | null` _(required)_
- `title` `string | null` _(required)_
- `merchantReference` `string | null` _(required)_
- `metadata` `object` _(required)_
- `url` `string` _(required)_
- `payable` `boolean` _(required)_
- `listed` `boolean` _(required)_: Whether it appears in the public x402 payable index.
- `expiresAt` `string | null` _(required)_
- `disabledAt` `string | null` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `404`: No link with that id.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/payment-links/string/disable \
  --request POST \
  --header 'Idempotency-Key: string'
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-links/string/disable', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string'
  }
})
```

## List a payment link in the public payable index

`POST /v1/payment-links/{id}/list`

Opts the link into the public x402 payable index, where agents discover and pay it. The link stays payable by anyone holding its URL either way; listing only decides whether a discovery reader is shown it.

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: Listed payment link.

Body (`application/json`):

- `id` `string` _(required)_
- `kind` `string` _(required)_: fixed, open, or catalog
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object & object | null` _(required)_
- `currency` `string | null` _(required)_
- `lines` `array | null` _(required)_
- `title` `string | null` _(required)_
- `merchantReference` `string | null` _(required)_
- `metadata` `object` _(required)_
- `url` `string` _(required)_
- `payable` `boolean` _(required)_
- `listed` `boolean` _(required)_: Whether it appears in the public x402 payable index.
- `expiresAt` `string | null` _(required)_
- `disabledAt` `string | null` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `404`: No link with that id, or not this merchant's.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/payment-links/string/list \
  --request POST
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-links/string/list', {
  method: 'POST'
})
```

## Remove a payment link from the public payable index

`POST /v1/payment-links/{id}/unlist`

### Path parameters

- `id` `string` _(required)_

### Responses

#### `200`: Unlisted payment link.

Body (`application/json`):

- `id` `string` _(required)_
- `kind` `string` _(required)_: fixed, open, or catalog
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object & object | null` _(required)_
- `currency` `string | null` _(required)_
- `lines` `array | null` _(required)_
- `title` `string | null` _(required)_
- `merchantReference` `string | null` _(required)_
- `metadata` `object` _(required)_
- `url` `string` _(required)_
- `payable` `boolean` _(required)_
- `listed` `boolean` _(required)_: Whether it appears in the public x402 payable index.
- `expiresAt` `string | null` _(required)_
- `disabledAt` `string | null` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `version` `integer` _(required)_

#### `404`: No link with that id, or not this merchant's.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/payment-links/string/unlist \
  --request POST
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-links/string/unlist', {
  method: 'POST'
})
```

## Check out a payment link

`POST /v1/payment-links/{id}/checkout`

### Path parameters

- `id` `string` _(required)_

### Header parameters

- `Idempotency-Key` `string` _(required)_: Stable unique key for this logical write. Keep it unchanged when retrying.

### Request body (`application/json`)

- `settlementAsset` `string`
- `provider` `string`
- `payment` `object`
  - `asset` `string` _(required)_
  - `chain` `string` _(required)_
  - `payerAddress` `string`
  - `returnAddress` `string`
- `executionPath` `string`
- `metadata` `object`: Your own string pairs, sent back in webhooks. At most 20 keys of up to 64 characters, values of up to 1000, and 8 KB in all.
- `merchantReference` `string`
- `ttlSeconds` `integer`
- `amount` `object`
  - `amount` `string` _(required)_
  - `asset` `string` _(required)_

### Responses

#### `201`: Payment intent created.

Body (`application/json`):

- `id` `string` _(required)_
- `status` `string` _(required)_: Payment intent lifecycle state.
- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object` _(required)_
  - `amount` `string` _(required)_: Exact minor units. Calculate with this value.
  - `asset` `string` _(required)_: ISO asset code, e.g. IDR, USD, USDC.
  - `formatted` `string` _(required)_: Machine decimal; ungrouped and dot-separated.
  - `display` `string` _(required)_: Localized display text. Never parse this value.
- `settlementAsset` `string` _(required)_
- `provider` `string | null` _(required)_
- `payment` `object | null` _(required)_
  - `asset` `string` _(required)_
  - `chain` `string` _(required)_
  - `payerAddress` `string`
- `executionPath` `string | null` _(required)_
- `escrow` `object | null` _(required)_: Buyer-protection escrow terms; null for an ordinary payment.
  - `holdSeconds` `integer` _(required)_
  - `arbiter` `string`
- `source` `string` _(required)_
- `metadata` `object` _(required)_
- `merchantReference` `string | null` _(required)_
- `clearingTransactionId` `string | null` _(required)_
- `failureReason` `string | null` _(required)_
- `createdAt` `string` _(required)_
- `updatedAt` `string` _(required)_
- `expiresAt` `string` _(required)_
- `confirmedAt` `string | null` _(required)_
- `completedAt` `string | null` _(required)_

#### `404`: No link with that id.

Body (`application/json`):

- `error` `object` _(required)_
  - `code` `string` _(required)_
  - `message` `string` _(required)_
  - `retryable` `boolean` _(required)_
  - `details` `object`

### Example request

```bash
curl https://api.mayarin.xyz/v1/payment-links/string/checkout \
  --request POST \
  --header 'Idempotency-Key: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "settlementAsset": "IDR",
  "provider": "string",
  "payment": {
    "asset": "IDR",
    "chain": "ethereum",
    "payerAddress": "string",
    "returnAddress": "string"
  },
  "executionPath": "deposit-match",
  "metadata": {},
  "merchantReference": "string",
  "ttlSeconds": 0,
  "amount": {
    "amount": "string",
    "asset": "IDR"
  }
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-links/string/checkout', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    settlementAsset: 'IDR',
    provider: 'string',
    payment: {
      asset: 'IDR',
      chain: 'ethereum',
      payerAddress: 'string',
      returnAddress: 'string'
    },
    executionPath: 'deposit-match',
    metadata: {},
    merchantReference: 'string',
    ttlSeconds: 0,
    amount: {
      amount: 'string',
      asset: 'IDR'
    }
  })
})
```