Skip to main content
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

MethodDescription
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

FieldStripePagarMeMercadoPago
provider"stripe""pagar_me""mercado_pago"
source.currencyAny string"BRL""COP"
source.payment_method.idCard PM IDCard PM ID or omit—
source.payment_method.card_token—Required if no idRequired
source.expiry_date—Optional (PIX only)—
source.fraud_checkOptional (disabled)Required (card)—
destinationOptional (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"——
allocationsOptional 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:
FieldTypeDescription
idstringPayment ID
statusstringPayment status (e.g., "created", "confirmed", "cancelled")
typestringTransaction type (dynamically set)
created_atstringISO timestamp
updated_atstringISO timestamp
provider_responseobjectRaw provider response data
To issue a refund on a completed payment, see Refunds.