# Payment intents

Immutable requests for payment.

## List payment intents

`GET /v1/payment-intents`

Your own payments, newest first, a page at a time, each with what clearing recorded for it. Only payments your keys created are listed. Needs a secret key with `payments:read`. Page with `nextCursor`: pass it back as `cursor`, exactly as it came.

### Query parameters

- `limit` `integer`
- `cursor` `string`
- `status` `string`
- `from` `string <date-time>`
- `to` `string <date-time>`
- `merchantReference` `string`

### Responses

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

Body (`application/json`):

- `paymentIntents` `object[]` _(required)_
  - `paymentIntent` `object` _(required)_
    - `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)_
  - `clearing` `object | null` _(required)_: What clearing recorded for the payment. `null` until it is confirmed.
    - `id` `string` _(required)_
    - `state` `string` _(required)_: Clearing transaction state.
    - `provider` `string` _(required)_
    - `providerReference` `string | null` _(required)_
    - `transactionHash` `string | null` _(required)_
    - `sourceAmount` `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.
    - `settlementAmount` `object & object | null` _(required)_
    - `fee` `object & object | null` _(required)_
    - `netAmount` `object & object | null` _(required)_
    - `rate` `object | null` _(required)_: The rate the engine locked for clearing. It is not always the price quoted to the payer: when the payer asset and the settlement asset are the same, it is 1:1. To show the payer's price for the priced currency, divide the deposit amount by `sourceAmount`.
      - `from` `string` _(required)_: Asset the rate converts from.
      - `to` `string` _(required)_: Asset the rate converts to.
      - `scaledRate` `string` _(required)_: Minor units of `to` per 1 whole unit of `from`, multiplied by 10^9. Divide by 10^9 and by 10^decimals of `to` for the whole-unit rate.
      - `source` `string` _(required)_: Where the rate came from.
      - `lockedAt` `string` _(required)_: When the rate was locked, ISO 8601.
    - `failure` `object | null` _(required)_
      - `reason` `string` _(required)_
      - `code` `string` _(required)_
      - `at` `string` _(required)_
    - `createdAt` `string` _(required)_
    - `updatedAt` `string` _(required)_
- `nextCursor` `string | null` _(required)_: Pass it as `cursor` for the next page. `null` on the last page.

#### `400`: A cursor this API did not issue, or a `limit` outside 1 to 100.

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`

#### `403`: The key lacks `payments:read`, or is publishable.

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-intents?limit=25&cursor=string&status=CREATED&from=1970-01-01T00:00:00.000Z&to=1970-01-01T00:00:00.000Z&merchantReference=string'
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-intents?limit=25&cursor=string&status=CREATED&from=1970-01-01T00:00:00.000Z&to=1970-01-01T00:00:00.000Z&merchantReference=string')
```

## Create a payment intent

`POST /v1/payment-intents`

Creates an immutable fiat-denominated payment request. Reusing an idempotency key with the same body returns the original intent; the same key with different parameters is a 409. The response also carries `payerToken` and `checkoutUrl`: the hosted payment page with the payer's token attached. Send that URL to the payer; the payment id alone opens nothing.

### Header parameters

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

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

- `qr` `string`
- `merchant` `object`
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object`
  - `amount` `string` _(required)_
  - `asset` `string` _(required)_
- `payment` `object`
  - `asset` `string` _(required)_
  - `chain` `string` _(required)_
  - `payerAddress` `string`
  - `returnAddress` `string`
- `settlementAsset` `string`
- `executionPath` `string`
- `escrow` `object | null`
  - `holdSeconds` `integer` _(required)_
  - `arbiter` `string`
  - `bondBps` `integer`
- `provider` `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`

### 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)_

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

#### `409`: Idempotency conflict or state conflict.

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-intents \
  --request POST \
  --header 'Idempotency-Key: string' \
  --header 'Content-Type: application/json' \
  --data '{
  "qr": "string",
  "merchant": {
    "id": "string",
    "name": "string",
    "city": "string",
    "countryCode": "string",
    "categoryCode": "string"
  },
  "amount": {
    "amount": "string",
    "asset": "IDR"
  },
  "payment": {
    "asset": "IDR",
    "chain": "ethereum",
    "payerAddress": "string",
    "returnAddress": "string"
  },
  "settlementAsset": "IDR",
  "executionPath": "deposit-match",
  "escrow": {
    "holdSeconds": 0,
    "arbiter": "string",
    "bondBps": 0
  },
  "provider": "string",
  "metadata": {},
  "merchantReference": "string",
  "ttlSeconds": 0
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-intents', {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'string',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    qr: 'string',
    merchant: {
      id: 'string',
      name: 'string',
      city: 'string',
      countryCode: 'string',
      categoryCode: 'string'
    },
    amount: {
      amount: 'string',
      asset: 'IDR'
    },
    payment: {
      asset: 'IDR',
      chain: 'ethereum',
      payerAddress: 'string',
      returnAddress: 'string'
    },
    settlementAsset: 'IDR',
    executionPath: 'deposit-match',
    escrow: {
      holdSeconds: 0,
      arbiter: 'string',
      bondBps: 0
    },
    provider: 'string',
    metadata: {},
    merchantReference: 'string',
    ttlSeconds: 0
  })
})
```

## Validate a payment intent

`POST /v1/payment-intents/validate`

Runs the checks `createPaymentIntent` runs and creates nothing, so a form or a deploy check learns whether a body would be accepted without leaving an intent in the dashboard. A refused rail names the pairs the merchant does offer.

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

- `qr` `string`
- `merchant` `object`
  - `id` `string` _(required)_
  - `name` `string` _(required)_
  - `city` `string` _(required)_
  - `countryCode` `string` _(required)_
  - `categoryCode` `string`
- `amount` `object`
  - `amount` `string` _(required)_
  - `asset` `string` _(required)_
- `payment` `object`
  - `asset` `string` _(required)_
  - `chain` `string` _(required)_
  - `payerAddress` `string`
  - `returnAddress` `string`
- `settlementAsset` `string`
- `executionPath` `string`
- `escrow` `object | null`
  - `holdSeconds` `integer` _(required)_
  - `arbiter` `string`
  - `bondBps` `integer`
- `provider` `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`

### Responses

#### `200`: The body would be accepted.

Body (`application/json`):

- `valid` `boolean` _(required)_

#### `400`: The body would be refused; the error says why.

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-intents/validate \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "qr": "string",
  "merchant": {
    "id": "string",
    "name": "string",
    "city": "string",
    "countryCode": "string",
    "categoryCode": "string"
  },
  "amount": {
    "amount": "string",
    "asset": "IDR"
  },
  "payment": {
    "asset": "IDR",
    "chain": "ethereum",
    "payerAddress": "string",
    "returnAddress": "string"
  },
  "settlementAsset": "IDR",
  "executionPath": "deposit-match",
  "escrow": {
    "holdSeconds": 0,
    "arbiter": "string",
    "bondBps": 0
  },
  "provider": "string",
  "metadata": {},
  "merchantReference": "string",
  "ttlSeconds": 0
}'
```

```ts
fetch('https://api.mayarin.xyz/v1/payment-intents/validate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    qr: 'string',
    merchant: {
      id: 'string',
      name: 'string',
      city: 'string',
      countryCode: 'string',
      categoryCode: 'string'
    },
    amount: {
      amount: 'string',
      asset: 'IDR'
    },
    payment: {
      asset: 'IDR',
      chain: 'ethereum',
      payerAddress: 'string',
      returnAddress: 'string'
    },
    settlementAsset: 'IDR',
    executionPath: 'deposit-match',
    escrow: {
      holdSeconds: 0,
      arbiter: 'string',
      bondBps: 0
    },
    provider: 'string',
    metadata: {},
    merchantReference: 'string',
    ttlSeconds: 0
  })
})
```

## List the rails a merchant is paid on

`GET /v1/rails`

Every `(chain, asset)` pair the key's merchant can be paid on, with no payment link needed. The list `createPaymentIntent` checks a rail against. A publishable key may read it.

### Responses

#### `200`: The rails on offer.

Body (`application/json`):

- `rails` `object[]` _(required)_
  - `chain` `string` _(required)_
  - `asset` `string` _(required)_
  - `contract` `string | null` _(required)_: The token contract; null for a native asset.
  - `settlementAsset` `string` _(required)_: What the merchant receives on this chain.
- `settlementAsset` `string` _(required)_: The default settlement asset.

#### `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/rails
```

```ts
fetch('https://api.mayarin.xyz/v1/rails')
```

## Get a payment intent

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

Merchant read. Answers 404 for an intent that belongs to another merchant.

### Path parameters

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

### Responses

#### `200`: Current intent.

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)_

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

Body (`application/json`):

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

#### `404`: No intent 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-intents/string
```

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

## Confirm a payment intent

`POST /v1/payment-intents/{id}/confirm`

Confirms the intent and hands it to the clearing engine. Safe to retry: confirming an intent that is already clearing returns its current position rather than starting a second one.

### 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`: Current payment and clearing state.

Body (`application/json`):

- `paymentIntent` `object` _(required)_
  - `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)_
- `clearing` `object | null` _(required)_: What clearing recorded for the payment. `null` until it is confirmed.
  - `id` `string` _(required)_
  - `state` `string` _(required)_: Clearing transaction state.
  - `provider` `string` _(required)_
  - `providerReference` `string | null` _(required)_
  - `transactionHash` `string | null` _(required)_
  - `sourceAmount` `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.
  - `settlementAmount` `object & object | null` _(required)_
  - `fee` `object & object | null` _(required)_
  - `netAmount` `object & object | null` _(required)_
  - `rate` `object | null` _(required)_: The rate the engine locked for clearing. It is not always the price quoted to the payer: when the payer asset and the settlement asset are the same, it is 1:1. To show the payer's price for the priced currency, divide the deposit amount by `sourceAmount`.
    - `from` `string` _(required)_: Asset the rate converts from.
    - `to` `string` _(required)_: Asset the rate converts to.
    - `scaledRate` `string` _(required)_: Minor units of `to` per 1 whole unit of `from`, multiplied by 10^9. Divide by 10^9 and by 10^decimals of `to` for the whole-unit rate.
    - `source` `string` _(required)_: Where the rate came from.
    - `lockedAt` `string` _(required)_: When the rate was locked, ISO 8601.
  - `failure` `object | null` _(required)_
    - `reason` `string` _(required)_
    - `code` `string` _(required)_
    - `at` `string` _(required)_
  - `createdAt` `string` _(required)_
  - `updatedAt` `string` _(required)_
- `deposit` `object | null` _(required)_
  - `address` `string` _(required)_
  - `chain` `string` _(required)_
  - `asset` `string` _(required)_
  - `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.
  - `uri` `string | null` _(required)_: EIP-681 payment URI for a QR, or null when none can be built safely.
  - `received` `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.
  - `required` `integer` _(required)_
  - `reviewRequired` `boolean` _(required)_
  - `deposits` `object[]` _(required)_
    - `txHash` `string | null` _(required)_
    - `logIndex` `integer` _(required)_
    - `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.
    - `status` `string` _(required)_
    - `confirmations` `integer` _(required)_
    - `firstSeenAt` `string` _(required)_
- `timeline` `object[]` _(required)_
  - `sequence` `integer` _(required)_
  - `state` `string` _(required)_
  - `from` `string | null` _(required)_
  - `occurredAt` `string` _(required)_

#### `404`: No intent 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-intents/string/confirm \
  --request POST \
  --header 'Idempotency-Key: string'
```

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

## Cancel a payment intent

`POST /v1/payment-intents/{id}/cancel`

Voids an intent the payer has not paid, so it stops waiting for expiry. Allowed before confirm and while clearing still waits for funds; a payment already under way is a 409. Cancelling twice is safe. A transfer that arrives afterwards is not lost: the payment reopens and settles. Needs the owning merchant's secret key.

### Path parameters

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

### Responses

#### `200`: The payment after cancelling: `EXPIRED` before confirm, `FAILED` after.

Body (`application/json`):

- `paymentIntent` `object` _(required)_
  - `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)_
- `clearing` `object | null` _(required)_: What clearing recorded for the payment. `null` until it is confirmed.
  - `id` `string` _(required)_
  - `state` `string` _(required)_: Clearing transaction state.
  - `provider` `string` _(required)_
  - `providerReference` `string | null` _(required)_
  - `transactionHash` `string | null` _(required)_
  - `sourceAmount` `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.
  - `settlementAmount` `object & object | null` _(required)_
  - `fee` `object & object | null` _(required)_
  - `netAmount` `object & object | null` _(required)_
  - `rate` `object | null` _(required)_: The rate the engine locked for clearing. It is not always the price quoted to the payer: when the payer asset and the settlement asset are the same, it is 1:1. To show the payer's price for the priced currency, divide the deposit amount by `sourceAmount`.
    - `from` `string` _(required)_: Asset the rate converts from.
    - `to` `string` _(required)_: Asset the rate converts to.
    - `scaledRate` `string` _(required)_: Minor units of `to` per 1 whole unit of `from`, multiplied by 10^9. Divide by 10^9 and by 10^decimals of `to` for the whole-unit rate.
    - `source` `string` _(required)_: Where the rate came from.
    - `lockedAt` `string` _(required)_: When the rate was locked, ISO 8601.
  - `failure` `object | null` _(required)_
    - `reason` `string` _(required)_
    - `code` `string` _(required)_
    - `at` `string` _(required)_
  - `createdAt` `string` _(required)_
  - `updatedAt` `string` _(required)_
- `deposit` `object | null` _(required)_
  - `address` `string` _(required)_
  - `chain` `string` _(required)_
  - `asset` `string` _(required)_
  - `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.
  - `uri` `string | null` _(required)_: EIP-681 payment URI for a QR, or null when none can be built safely.
  - `received` `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.
  - `required` `integer` _(required)_
  - `reviewRequired` `boolean` _(required)_
  - `deposits` `object[]` _(required)_
    - `txHash` `string | null` _(required)_
    - `logIndex` `integer` _(required)_
    - `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.
    - `status` `string` _(required)_
    - `confirmations` `integer` _(required)_
    - `firstSeenAt` `string` _(required)_
- `timeline` `object[]` _(required)_
  - `sequence` `integer` _(required)_
  - `state` `string` _(required)_
  - `from` `string | null` _(required)_
  - `occurredAt` `string` _(required)_

#### `404`: No intent of yours with that id.

Body (`application/json`):

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

#### `409`: The payment is already under way.

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-intents/string/cancel \
  --request POST
```

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

## Simulate a deposit (testnet only)

`POST /v1/payment-intents/{id}/simulate-deposit`

Asks for the intent's amount to be sent to its deposit address from the operator wallet, so a test can reach `COMPLETED` without a wallet. The request is filed and answered at once; the chain worker sends the transfer within a few seconds, so follow with a read or a webhook. The intent must be confirmed on a deposit-match rail. The route exists only on a deployment with no mainnet chain: on mainnet it is a 404. Needs the owning merchant's secret key.

### Path parameters

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

### Responses

#### `202`: The request is filed; the payment as it stands.

Body (`application/json`):

- `paymentIntent` `object` _(required)_
  - `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)_
- `clearing` `object | null` _(required)_: What clearing recorded for the payment. `null` until it is confirmed.
  - `id` `string` _(required)_
  - `state` `string` _(required)_: Clearing transaction state.
  - `provider` `string` _(required)_
  - `providerReference` `string | null` _(required)_
  - `transactionHash` `string | null` _(required)_
  - `sourceAmount` `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.
  - `settlementAmount` `object & object | null` _(required)_
  - `fee` `object & object | null` _(required)_
  - `netAmount` `object & object | null` _(required)_
  - `rate` `object | null` _(required)_: The rate the engine locked for clearing. It is not always the price quoted to the payer: when the payer asset and the settlement asset are the same, it is 1:1. To show the payer's price for the priced currency, divide the deposit amount by `sourceAmount`.
    - `from` `string` _(required)_: Asset the rate converts from.
    - `to` `string` _(required)_: Asset the rate converts to.
    - `scaledRate` `string` _(required)_: Minor units of `to` per 1 whole unit of `from`, multiplied by 10^9. Divide by 10^9 and by 10^decimals of `to` for the whole-unit rate.
    - `source` `string` _(required)_: Where the rate came from.
    - `lockedAt` `string` _(required)_: When the rate was locked, ISO 8601.
  - `failure` `object | null` _(required)_
    - `reason` `string` _(required)_
    - `code` `string` _(required)_
    - `at` `string` _(required)_
  - `createdAt` `string` _(required)_
  - `updatedAt` `string` _(required)_
- `deposit` `object | null` _(required)_
  - `address` `string` _(required)_
  - `chain` `string` _(required)_
  - `asset` `string` _(required)_
  - `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.
  - `uri` `string | null` _(required)_: EIP-681 payment URI for a QR, or null when none can be built safely.
  - `received` `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.
  - `required` `integer` _(required)_
  - `reviewRequired` `boolean` _(required)_
  - `deposits` `object[]` _(required)_
    - `txHash` `string | null` _(required)_
    - `logIndex` `integer` _(required)_
    - `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.
    - `status` `string` _(required)_
    - `confirmations` `integer` _(required)_
    - `firstSeenAt` `string` _(required)_
- `timeline` `object[]` _(required)_
  - `sequence` `integer` _(required)_
  - `state` `string` _(required)_
  - `from` `string | null` _(required)_
  - `occurredAt` `string` _(required)_

#### `400`: The intent has no EVM deposit address to fund.

Body (`application/json`):

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

#### `404`: No intent of yours with that id, or this deployment does not simulate deposits.

Body (`application/json`):

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

#### `409`: The payment is no longer waiting for funds.

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-intents/string/simulate-deposit \
  --request POST
```

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