# OrionPay — Full LLM Context

This is the inline-form documentation for OrionPay's public API. It mirrors the
OpenAPI 3.1 spec and is suitable for pasting into LLM context windows.

For an index version: https://pay.orion.moe/llms.txt
For the canonical machine-readable spec: https://payapi.orion.moe/openapi.json
For the Streamable HTTP MCP server: https://payapi.orion.moe/mcp

Authentication: send your API key in the X-API-Key header (or Authorization: Bearer <key>).
Two key types: product keys (scoped to one product) and personal keys (productId=null, full account).


## Endpoints

## PIX

### POST /api/v1/pix/generate

**Operation ID**: `pix_generate`
**MCP tool**: `pix_generate`
**Auth**: api-key
**Rate limit**: none — No rate limit (critical payment generation).

Generates a PIX QR code for a product purchase. The product is identified by the API key (product key). On payment, a webhook is delivered (`payment.success`) and the buyer receives an access token.

**Request body** (`GeneratePixRequest`):
```
  amount?: number — BRL amount. Optional when product has a fixed price.
  description?: string — Optional description shown to payer.
  name!: string — Payer full name.
  email!: string — Payer email.
  phone?: string — Optional payer phone (E.164 or Brazilian).
  cpf?: string — Optional payer CPF (11 digits) or CNPJ (14 digits).
  ipAddress?: string — Optional payer IP for fraud scoring.
```


### POST /api/v1/pix/personal

**Operation ID**: `pix_personal`
**MCP tool**: `pix_personal_deposit`
**Auth**: personal-api-key
**Rate limit**: none — No rate limit (critical payment generation).

Generates a PIX QR code that credits the user's personal BRL wallet directly (no product). Requires a personal API key (productId=null).

**Request body** (`GeneratePixRequest`):
```
  amount?: number — BRL amount. Optional when product has a fixed price.
  description?: string — Optional description shown to payer.
  name!: string — Payer full name.
  email!: string — Payer email.
  phone?: string — Optional payer phone (E.164 or Brazilian).
  cpf?: string — Optional payer CPF (11 digits) or CNPJ (14 digits).
  ipAddress?: string — Optional payer IP for fraud scoring.
```


### GET /api/v1/pix/status/{id}

**Operation ID**: `pix_status`
**MCP tool**: `pix_status`
**Auth**: api-key
**Rate limit**: 2 / min — 2 requests per minute per ID per API key.

Polls the status of a PIX payment. The `id` parameter accepts purchaseId (numeric), transactionId (numeric), or eulenDepositId (UUID). Webhook delivery is preferred over polling.

**Parameters**:
- `id`! (path, string) — purchaseId, transactionId, or eulenDepositId (UUID).


## Card

### POST /api/v1/card/generate

**Operation ID**: `card_generate`
**Auth**: api-key
**Rate limit**: 100 / min

Charges a credit or debit card. CPF is required. Card data is sent over TLS and never stored. Returns immediately with status (synchronous capture).

**Request body** (`GenerateCardPaymentRequest`):
```
  amount!: number
  description?: string
  name!: string
  email!: string
  phone?: string
  cpf!: string — Required for card payments. 11 digits.
  ipAddress?: string
  cardNumber!: string
  cardHolderName!: string
  cardExpiryMonth!: string
  cardExpiryYear!: string
  cardCvv!: string
  billingAddressStreet?: string
  billingAddressNumber?: string
  billingAddressComplement?: string
  billingAddressDistrict?: string
  billingAddressCity?: string
  billingAddressState?: string
  billingAddressZipCode?: string
```


### GET /api/v1/card/status/{paymentId}

**Operation ID**: `card_status`
**MCP tool**: `card_status`
**Auth**: api-key
**Rate limit**: none

Returns the current status of a card payment.

**Parameters**:
- `paymentId`! (path, integer)


## Integration

### GET /integration/verify-access

**Operation ID**: `integration_verify_access`
**MCP tool**: `integration_verify_access`
**Auth**: api-key
**Rate limit**: 2 / min — 2 requests per minute per token/email per API key.

Checks whether a buyer (by email or accessToken) has paid access to the product associated with the API key.

**Parameters**:
- `email`? (query, string)
- `accessToken`? (query, string)


### GET /integration/buyers

**Operation ID**: `integration_list_buyers`
**MCP tool**: `integration_list_buyers`
**Auth**: api-key
**Rate limit**: 30 / min

Returns all buyers of the product associated with the API key. Filter by status optional.

**Parameters**:
- `status`? (query, string enum: PENDING|PAID|EXPIRED|CANCELED|REFUNDED)


### GET /integration/buyers/{purchaseId}

**Operation ID**: `integration_get_buyer`
**MCP tool**: `integration_get_buyer`
**Auth**: api-key
**Rate limit**: 30 / min

Returns details for a specific purchase belonging to the API key's product.

**Parameters**:
- `purchaseId`! (path, integer)


### GET /integration/content

**Operation ID**: `integration_get_content`
**MCP tool**: `integration_get_content`
**Auth**: api-key
**Rate limit**: 30 / min

Returns the product content (files, lessons, etc.) accessible to the buyer who owns the supplied accessToken.

**Parameters**:
- `accessToken`! (query, string)


### POST /integration/grant-access

**Operation ID**: `integration_grant_access`
**MCP tool**: `integration_grant_access`
**Auth**: api-key

Grants access to a buyer without a payment (e.g. for refunds resolution, comp tickets, or migrations). An access token is generated.

**Request body** (`GrantAccessRequest`):
```
  buyerEmail!: string
  buyerName?: string
  price?: number — Optional recorded price (no charge is made).
  expiresAt?: string — Optional access expiry.
```


### DELETE /integration/revoke-access/{purchaseId}

**Operation ID**: `integration_revoke_access`
**MCP tool**: `integration_revoke_access`
**Auth**: api-key

Revokes a buyer's access. The access token is invalidated.

**Parameters**:
- `purchaseId`! (path, integer)


### POST /api/v1/integration/deposit/pix

**Operation ID**: `integration_deposit_pix`
**MCP tool**: `integration_deposit_pix`
**Auth**: api-key
**Rate limit**: 10 / min

Generates a PIX QR code for product deposit, recording the payer's CPF. Used when CPF must be captured up-front (compliance, KYC, or chargeback defense).

**Request body** (`CreatePixDepositRequest`):
```
  cpf!: string — Payer CPF (11 digits) or CNPJ (14 digits).
  buyerName?: string
  buyerEmail?: string
  amount?: number
```


## Personal

### GET /api/v1/personal/balance

**Operation ID**: `personal_balance`
**MCP tool**: `personal_balance`
**Auth**: personal-api-key
**Rate limit**: 60 / hour

Returns BRL balance and all crypto balances (Liquid Network, Bitcoin, Polygon, etc.).


### GET /api/v1/personal/limits

**Operation ID**: `personal_limits`
**MCP tool**: `personal_limits`
**Auth**: personal-api-key
**Rate limit**: 30 / hour

Returns the user's daily/monthly/per-transaction withdrawal limits and remaining usage.


### GET /api/v1/personal/transactions

**Operation ID**: `personal_transactions`
**MCP tool**: `personal_transactions`
**Auth**: personal-api-key
**Rate limit**: 60 / hour

Returns the user's transaction history (deposits, withdrawals, swaps), most recent first.

**Parameters**:
- `limit`? (query, integer)
- `offset`? (query, integer)
- `type`? (query, string enum: DEPOSIT|WITHDRAWAL|SWAP)


### POST /api/v1/personal/withdraw/pix

**Operation ID**: `personal_withdraw_pix`
**MCP tool**: `personal_withdraw_pix`
**Auth**: personal-api-key
**Rate limit**: 10 / hour

Queues a PIX withdrawal from the user's BRL wallet. Requires API withdrawals to be enabled (see /enable-withdrawals). 7-day hold applies to API deposits.

**Request body** (`PixWithdrawRequest`):
```
  amount!: number — BRL amount.
  pixKey!: string — PIX key (CPF/CNPJ/email/phone/random).
  pixKeyType?: string (CPF|CNPJ|EMAIL|PHONE|EVP) — Optional; auto-detected if omitted.
  description?: string
  taxNumber?: string — Tax number of the recipient (CPF/CNPJ).
  euid?: string — Optional Eulen user identifier override.
```


### POST /api/v1/personal/withdraw/crypto

**Operation ID**: `personal_withdraw_crypto`
**MCP tool**: `personal_withdraw_crypto`
**Auth**: personal-api-key
**Rate limit**: 10 / hour

Queues a crypto withdrawal. Supports L-BTC, BTC-PEGOUT (Bitcoin mainnet via peg-out), DePix, USDt, USDC. Network parameter routes via SideShift for cross-chain.

**Request body** (`CryptoWithdrawRequest`):
```
  amount!: number — Amount in the asset's native unit.
  toAddress!: string — Destination wallet address.
  assetTicker!: string (L-BTC|BTC-PEGOUT|DePix|USDt|USDC) — BTC-PEGOUT: peg-out to Bitcoin mainnet (min 0.00025 BTC).
  network?: string (liquid|bitcoin|ethereum|tron|bsc|solana|ton|avalanche|polygon|optimism) — Optional network override (e.g. for SideShift cross-chain routing).
  memo?: string — Required for TON.
```


### GET /api/v1/personal/withdraw/status/{id}

**Operation ID**: `personal_withdraw_status`
**MCP tool**: `personal_withdraw_status`
**Auth**: personal-api-key
**Rate limit**: 120 / hour

Returns the status, settlement details, and txHash of a withdrawal by transaction ID.

**Parameters**:
- `id`! (path, integer)


### POST /api/v1/personal/swap/quote

**Operation ID**: `personal_swap_quote`
**MCP tool**: `personal_swap_quote`
**Auth**: personal-api-key
**Rate limit**: 120 / hour

Returns a quote for swapping between supported assets (DePix, L-BTC, USDt, EURx). Quote is valid for ~30 seconds.

**Request body** (`SwapRequest`):
```
  fromCurrency!: string (DePix|L-BTC|USDt|EURx)
  toCurrency!: string (DePix|L-BTC|USDt|EURx)
  amount!: number
```


### POST /api/v1/personal/swap/execute

**Operation ID**: `personal_swap_execute`
**MCP tool**: `personal_swap_execute`
**Auth**: personal-api-key
**Rate limit**: 20 / hour

Executes a swap. Re-quotes internally before locking funds; if the rate moved beyond tolerance the swap is rejected.

**Request body** (`SwapRequest`):
```
  fromCurrency!: string (DePix|L-BTC|USDt|EURx)
  toCurrency!: string (DePix|L-BTC|USDt|EURx)
  amount!: number
```


### GET /api/v1/personal/withdraw-enabled

**Operation ID**: `personal_withdraw_enabled`
**MCP tool**: `personal_withdraw_enabled`
**Auth**: personal-api-key
**Rate limit**: 60 / hour

Returns whether API-driven withdrawals are enabled and the deposit hold period.


### POST /api/v1/personal/enable-withdrawals

**Operation ID**: `personal_enable_withdrawals`
**Auth**: personal-api-key
**Rate limit**: 5 / hour

Enables withdrawal endpoints for this account. Imposes a 7-day hold on every API deposit thereafter (anti-fraud). Requires explicit acceptance of the terms.

**Request body** (`EnableWithdrawalsRequest`):
```
  acceptTerms!: boolean — Must be true; acknowledges 7-day hold on API deposits.
```


## Webhooks

Outbound HTTPS POST to URLs configured at /dashboard/api-webhooks. Each delivery includes `X-OrionPay-Signature: sha256=<hex>` (HMAC-SHA256 of raw body), `X-OrionPay-Event`, and `X-OrionPay-Delivery` (UUID for idempotency). Respond 2xx to ACK.

### Event: `payment.success`

**Payload**:
```
  event?: string
  productId?: integer
  purchaseId?: integer
  transactionId?: integer
  buyerEmail?: string
  buyerName?: string
  amount?: number
  paidAt?: string
  accessToken?: string
  timestamp?: integer — Unix milliseconds.
```

### Event: `purchase.created`

**Payload**:
```
  event?: string
  productId?: integer
  purchaseId?: integer
  buyerEmail?: string
  amount?: number
  status?: string (PENDING)
  timestamp?: integer
```

### Event: `access.granted`

**Payload**:
```
  event?: string
  productId?: integer
  purchaseId?: integer
  buyerEmail?: string
  grantedManually?: boolean
  accessToken?: string
  expiresAt?: string
  timestamp?: integer
```

### Event: `payment.refunded_med`

**Payload**:
```
  event?: string
  productId?: integer
  purchaseId?: integer
  transactionId?: integer
  buyerEmail?: string
  amount?: number
  refundedAt?: string
  reason?: string — MED (fraud challenge) reason from BACEN.
  timestamp?: integer
```

### Event: `med.created`

**Payload**:
```
  event?: string
  transactionId?: integer
  purchaseId?: integer
  buyerEmail?: string
  amount?: number
  contestedAt?: string
  timestamp?: integer
```

### Event: `webhook.test`

**Payload**:
```
  event?: string
  message?: string
  timestamp?: integer
```

### Event: `withdrawal.completed`

**Payload**:
```
  event?: string
  transactionId?: integer
  asset?: string
  amount?: number
  toAddress?: string
  txHash?: string
  completedAt?: string
  timestamp?: integer
```

### Event: `withdrawal.settled`

**Payload**:
```
  event?: string
  transactionId?: integer
  asset?: string
  amount?: number
  toAddress?: string
  txHash?: string
  settledAt?: string
  timestamp?: integer
```

### Event: `withdrawal.failed`

**Payload**:
```
  event?: string
  transactionId?: integer
  asset?: string
  amount?: number
  reason?: string
  failedAt?: string
  timestamp?: integer
```

### Event: `swap.completed`

**Payload**:
```
  event?: string
  transactionId?: integer
  fromCurrency?: string
  toCurrency?: string
  fromAmount?: number
  toAmount?: number
  rate?: number
  completedAt?: string
  timestamp?: integer
```

### Event: `swap.failed`

**Payload**:
```
  event?: string
  transactionId?: integer
  fromCurrency?: string
  toCurrency?: string
  fromAmount?: number
  reason?: string
  failedAt?: string
  timestamp?: integer
```