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.

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

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

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

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

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

const result = await payments.confirm('pay_abc123');

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

Cancel a payment

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:

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

const result = await payments.sandboxPaid('pay_abc123');

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

Simulate settling a payment

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.