> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oaknetwork.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

A payment represents a charge against a customer's payment method. The SDK routes payments through your configured provider (Stripe, PagarMe, or MercadoPago) and returns a unified response regardless of which provider processes it. Payments can be created with immediate confirmation or held in a pending state for manual confirmation.

```typescript theme={null}
import { createOakClient, createPaymentService } from '@oaknetwork/payments-sdk';

const client = createOakClient({ ... });
const payments = createPaymentService(client);
```

## Methods

| Method                     | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| `create(payment)`          | Create a new payment                                         |
| `confirm(paymentId)`       | Confirm a pending payment                                    |
| `cancel(paymentId)`        | Cancel a pending payment                                     |
| `capture(paymentId)`       | Capture a payment authorized with `capture_method: "manual"` |
| `sandboxPaid(paymentId)`   | Simulate a paid payment (sandbox only)                       |
| `sandboxSettle(paymentId)` | Simulate settling a payment (sandbox only)                   |

## Create a payment

Payment requests are provider-specific. Pass the `provider` field to select the request shape.

### Stripe

```typescript theme={null}
const result = await payments.create({
  provider: 'stripe',
  source: {
    amount: 5000,
    currency: 'usd',
    customer: { id: 'cus_abc123' },
    payment_method: { type: 'card', id: 'pm_xyz789' },
    capture_method: 'automatic',
  },
  confirm: true,
});

if (result.ok) {
  console.log('Payment ID:', result.value.data.id);
  console.log('Status:', result.value.data.status);
}
```

### PagarMe

```typescript theme={null}
const result = await payments.create({
  provider: 'pagar_me',
  source: {
    amount: 10000,
    currency: 'BRL',
    customer: { id: 'cus_abc123' },
    payment_method: {
      type: 'card',
      card_token: 'tok_xyz',
      billing_address: {
        house_number: '100',
        street_number: '1',
        street_name: 'Rua Example',
        postal_code: '01001000',
        city: 'Sao Paulo',
        state: 'SP',
        country_code: 'BR',
      },
    },
    capture_method: 'automatic', // or 'manual' for two-step capture
    fraud_check: {
      enabled: true,
      provider: 'konduto',
      config: { sequence: 'fraud_before_auth', threshold: 'medium', action_on_fail: 'CANCEL_AUTH' },
      data: {
        last_four_digits: '4242',
        card_expiration_date: '12/2027',
        card_holder_name: 'Alice Smith',
      },
    },
  },
  confirm: true,
});
```

### PagarMe PIX

```typescript theme={null}
const result = await payments.create({
  provider: 'pagar_me',
  source: {
    amount: 5000,
    currency: 'BRL',
    customer: { id: 'cus_abc123' },
    payment_method: { type: 'pix' },
    capture_method: 'automatic',
    expiry_date: '2026-05-01T23:59:59Z',
  },
  confirm: true,
});
```

### MercadoPago

```typescript theme={null}
const result = await payments.create({
  provider: 'mercado_pago',
  source: {
    amount: 25000,
    currency: 'COP',
    customer: { id: 'cus_abc123' },
    payment_method: { type: 'card', card_token: 'tok_xyz' },
    capture_method: 'automatic',
  },
  confirm: true,
});
```

## Provider request fields

| Field                                      | Stripe                          | PagarMe                          | MercadoPago               |
| ------------------------------------------ | ------------------------------- | -------------------------------- | ------------------------- |
| `provider`                                 | `"stripe"`                      | `"pagar_me"`                     | `"mercado_pago"`          |
| `source.currency`                          | Any string                      | `"BRL"`                          | `"COP"`                   |
| `source.payment_method.id`                 | Card PM ID                      | Card PM ID or omit               | —                         |
| `source.payment_method.card_token`         | —                               | Required if no `id`              | Required                  |
| `source.expiry_date`                       | —                               | Optional (PIX only)              | —                         |
| `source.fraud_check`                       | Optional (disabled)             | Required (card)                  | —                         |
| `destination`                              | Optional (connected accounts)   | —                                | —                         |
| `source.capture_method`                    | `"automatic" \| "manual"`       | `"automatic" \| "manual"`        | `"automatic" \| "manual"` |
| `source.fraud_check.config.action_on_fail` | —                               | `"RETAIN_AUTH" \| "CANCEL_AUTH"` | —                         |
| `flow`                                     | `"platform"` or `"destination"` | —                                | —                         |
| `allocations`                              | Optional split payments         | —                                | —                         |

## Confirm a payment

```typescript theme={null}
const result = await payments.confirm('pay_abc123');

if (result.ok) {
  console.log('Confirmed. Status:', result.value.data.status);
}
```

## Cancel a payment

```typescript theme={null}
const result = await payments.cancel('pay_abc123');

if (result.ok) {
  console.log('Cancelled. Status:', result.value.data.status);
}
```

## Capture a payment

If a payment was created with `capture_method: "manual"`, you must explicitly capture it to collect funds:

```typescript theme={null}
const result = await payments.capture('pay_abc123');

if (result.ok) {
  console.log('Captured. Status:', result.value.data.status);
}
```

## Sandbox test helpers

The SDK provides sandbox-only methods to simulate payment state transitions during development.

### Simulate a paid payment

```typescript theme={null}
const result = await payments.sandboxPaid('pay_abc123');

if (result.ok) {
  console.log('Payment marked as paid');
}
```

### Simulate settling a payment

```typescript theme={null}
const result = await payments.sandboxSettle('pay_abc123');

if (result.ok) {
  console.log('Payment settled');
}
```

> `sandboxPaid()` and `sandboxSettle()` are restricted to the sandbox environment. Calling them in production returns an `EnvironmentViolationError`.

## Response type

All three methods return `Result<Payment.Response>`. The response data extends the original request with additional fields:

| Field               | Type     | Description                                                      |
| ------------------- | -------- | ---------------------------------------------------------------- |
| `id`                | `string` | Payment ID                                                       |
| `status`            | `string` | Payment status (e.g., `"created"`, `"confirmed"`, `"cancelled"`) |
| `type`              | `string` | Transaction type (dynamically set)                               |
| `created_at`        | `string` | ISO timestamp                                                    |
| `updated_at`        | `string` | ISO timestamp                                                    |
| `provider_response` | `object` | Raw provider response data                                       |

> To issue a refund on a completed payment, see [Refunds](/sdk/refunds).