# Platform

## List your merchants

`GET /v1/platform/merchants`

Your merchants, newest first, a page at a time. Needs a secret key that holds `merchants:provision`, and only reaches merchants you created. A merchant that is another platform's answers 404, like one that does not exist.

### Query parameters

- `limit` `integer`
- `cursor` `string`

### Responses

#### `200`: A page of merchants.

Body (`application/json`):

- `merchants` `object[]` _(required)_
  - `id` `string` _(required)_
  - `externalId` `string` _(required)_: Your own id for this merchant.
  - `name` `string` _(required)_
  - `city` `string | null` _(required)_
  - `countryCode` `string | null` _(required)_
  - `displayCurrency` `string | null` _(required)_
  - `settlementAsset` `string` _(required)_
  - `settlementAddress` `string | null` _(required)_: Where the merchant is paid. `null` until a signed proof has set it.
  - `disabled` `boolean` _(required)_: Mayarin turned the merchant off: it takes no new payment.
  - `createdAt` `string` _(required)_
- `nextCursor` `string | null` _(required)_: Pass it as `cursor` for the next page.

#### `403`: The key lacks `merchants:provision`.

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/platform/merchants?limit=25&cursor=string'
```

```ts
fetch('https://api.mayarin.xyz/v1/platform/merchants?limit=25&cursor=string')
```

## Create a merchant

`POST /v1/platform/merchants`

Creates a merchant of your own: a creator on a donation platform, a shop on a marketplace. Needs a secret key that holds `merchants:provision`, and only reaches merchants you created. A merchant that is another platform's answers 404, like one that does not exist. Give your own id as `externalId`, unique among your merchants. Without `settlement` the merchant cannot take a payment yet: the payout address is set only with a proof signed by a wallet at that address, so a platform cannot repoint a payout by itself. Build the proof with the SDK's `settlementProofRequest`.

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

- `externalId` `string` _(required)_
- `name` `string` _(required)_
- `city` `string` _(required)_
- `countryCode` `string` _(required)_
- `displayCurrency` `string`
- `settlement` `object`
  - `address` `string` _(required)_
  - `expiresAt` `string` _(required)_
  - `nonce` `string` _(required)_
  - `signature` `string` _(required)_

### Responses

#### `201`: The merchant.

Body (`application/json`):

- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `externalId` `string` _(required)_: Your own id for this merchant.
  - `name` `string` _(required)_
  - `city` `string | null` _(required)_
  - `countryCode` `string | null` _(required)_
  - `displayCurrency` `string | null` _(required)_
  - `settlementAsset` `string` _(required)_
  - `settlementAddress` `string | null` _(required)_: Where the merchant is paid. `null` until a signed proof has set it.
  - `disabled` `boolean` _(required)_: Mayarin turned the merchant off: it takes no new payment.
  - `createdAt` `string` _(required)_

#### `400`: A malformed field, a proof that does not match, has expired or runs for more than an hour, or the platform's limit of merchants.

Body (`application/json`):

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

#### `403`: The key lacks `merchants:provision`.

Body (`application/json`):

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

#### `409`: You already have a merchant with this `externalId`. `details.merchantId` is it.

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/platform/merchants \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "externalId": "string",
  "name": "string",
  "city": "string",
  "countryCode": "string",
  "displayCurrency": "string",
  "settlement": {
    "address": "string",
    "expiresAt": "string",
    "nonce": "string",
    "signature": "string"
  }
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/platform/merchants', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalId: 'string',
    name: 'string',
    city: 'string',
    countryCode: 'string',
    displayCurrency: 'string',
    settlement: {
      address: 'string',
      expiresAt: 'string',
      nonce: 'string',
      signature: 'string'
    }
  })
})
```

## Get a merchant

`GET /v1/platform/merchants/{id}`

Needs a secret key that holds `merchants:provision`, and only reaches merchants you created. A merchant that is another platform's answers 404, like one that does not exist.

### Path parameters

- `id` `string` _(required)_: The merchant id, `mrc_…`.

### Responses

#### `200`: The merchant.

Body (`application/json`):

- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `externalId` `string` _(required)_: Your own id for this merchant.
  - `name` `string` _(required)_
  - `city` `string | null` _(required)_
  - `countryCode` `string | null` _(required)_
  - `displayCurrency` `string | null` _(required)_
  - `settlementAsset` `string` _(required)_
  - `settlementAddress` `string | null` _(required)_: Where the merchant is paid. `null` until a signed proof has set it.
  - `disabled` `boolean` _(required)_: Mayarin turned the merchant off: it takes no new payment.
  - `createdAt` `string` _(required)_

#### `404`: No such merchant of yours.

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/platform/merchants/string
```

```ts
fetch('https://api.mayarin.xyz/v1/platform/merchants/string')
```

## Update a merchant

`PATCH /v1/platform/merchants/{id}`

Renames a merchant, edits its profile, or repoints its payout. Needs a secret key that holds `merchants:provision`, and only reaches merchants you created. A merchant that is another platform's answers 404, like one that does not exist. Changing `settlement` needs a proof signed by a wallet at the new address, and every change is written to the merchant's change history under your platform.

### Path parameters

- `id` `string` _(required)_: The merchant id, `mrc_…`.

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

- `name` `string`
- `city` `string`
- `countryCode` `string`
- `displayCurrency` `string`
- `settlement` `object`
  - `address` `string` _(required)_
  - `expiresAt` `string` _(required)_
  - `nonce` `string` _(required)_
  - `signature` `string` _(required)_

### Responses

#### `200`: The merchant after the change.

Body (`application/json`):

- `merchant` `object` _(required)_
  - `id` `string` _(required)_
  - `externalId` `string` _(required)_: Your own id for this merchant.
  - `name` `string` _(required)_
  - `city` `string | null` _(required)_
  - `countryCode` `string | null` _(required)_
  - `displayCurrency` `string | null` _(required)_
  - `settlementAsset` `string` _(required)_
  - `settlementAddress` `string | null` _(required)_: Where the merchant is paid. `null` until a signed proof has set it.
  - `disabled` `boolean` _(required)_: Mayarin turned the merchant off: it takes no new payment.
  - `createdAt` `string` _(required)_

#### `400`: A malformed field, or a proof that does not match or has expired.

Body (`application/json`):

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

#### `404`: No such merchant of yours.

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/platform/merchants/string \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "string",
  "city": "string",
  "countryCode": "string",
  "displayCurrency": "string",
  "settlement": {
    "address": "string",
    "expiresAt": "string",
    "nonce": "string",
    "signature": "string"
  }
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/platform/merchants/string', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'string',
    city: 'string',
    countryCode: 'string',
    displayCurrency: 'string',
    settlement: {
      address: 'string',
      expiresAt: 'string',
      nonce: 'string',
      signature: 'string'
    }
  })
})
```

## List a merchant's keys

`GET /v1/platform/merchants/{id}/keys`

The keys a merchant holds, never their secrets. Needs a secret key that holds `merchants:provision`, and only reaches merchants you created. A merchant that is another platform's answers 404, like one that does not exist.

### Path parameters

- `id` `string` _(required)_: The merchant id, `mrc_…`.

### Responses

#### `200`: The keys.

Body (`application/json`):

- `apiKeys` `object[]` _(required)_
  - `id` `string` _(required)_
  - `kind` `string` _(required)_
  - `name` `string` _(required)_
  - `prefix` `string` _(required)_: First characters of the key, to tell two apart.
  - `active` `boolean` _(required)_
  - `lastUsedAt` `string | null` _(required)_
  - `createdAt` `string` _(required)_

#### `404`: No such merchant of yours.

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/platform/merchants/string/keys
```

```ts
fetch('https://api.mayarin.xyz/v1/platform/merchants/string/keys')
```

## Mint a key for a merchant

`POST /v1/platform/merchants/{id}/keys`

Mints a `publishable` key (for a checkout page) or an `alert` key (for a livestream overlay) that belongs to the merchant. The secret is in the response once and never again. A secret key is never minted here: to act for the merchant with your own key, send the `Mayarin-Merchant` header on any merchant route. Needs a secret key that holds `merchants:provision`, and only reaches merchants you created. A merchant that is another platform's answers 404, like one that does not exist. A merchant may hold 20 active keys.

### Path parameters

- `id` `string` _(required)_: The merchant id, `mrc_…`.

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

- `kind` `string` _(required)_
- `name` `string` _(required)_

### Responses

#### `201`: The key, and its secret.

Body (`application/json`):

- `apiKey` `object` _(required)_
  - `id` `string` _(required)_
  - `kind` `string` _(required)_
  - `name` `string` _(required)_
  - `prefix` `string` _(required)_: First characters of the key, to tell two apart.
  - `active` `boolean` _(required)_
  - `lastUsedAt` `string | null` _(required)_
  - `createdAt` `string` _(required)_
- `secret` `string` _(required)_: Shown once.

#### `400`: An unknown kind, or the merchant already holds 20 active keys.

Body (`application/json`):

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

#### `404`: No such merchant of yours.

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/platform/merchants/string/keys \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "kind": "publishable",
  "name": "string"
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/platform/merchants/string/keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    kind: 'publishable',
    name: 'string'
  })
})
```

## Deactivate a merchant's key

`POST /v1/platform/merchants/{id}/keys/{keyId}/deactivate`

Stops a key at once. A livestream overlay on that key ends at its next reconnect. Needs a secret key that holds `merchants:provision`, and only reaches merchants you created. A merchant that is another platform's answers 404, like one that does not exist.

### Path parameters

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

### Responses

#### `200`: The key, now inactive.

Body (`application/json`):

- `apiKey` `object` _(required)_
  - `id` `string` _(required)_
  - `kind` `string` _(required)_
  - `name` `string` _(required)_
  - `prefix` `string` _(required)_: First characters of the key, to tell two apart.
  - `active` `boolean` _(required)_
  - `lastUsedAt` `string | null` _(required)_
  - `createdAt` `string` _(required)_

#### `404`: No such merchant of yours, or no such 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/platform/merchants/string/keys/string/deactivate \
  --request POST
```

```ts
fetch('https://api.mayarin.xyz/v1/platform/merchants/string/keys/string/deactivate', {
  method: 'POST'
})
```