Payments

Module role in sales flow

payments is the final checkout module before order completion.

• Depends on invoice credentials (invoices.create must run first).
• Supports redirect/post gateways and manual step-based flows like card-to-card upload/code verification.
• When payment reaches showOrder, SDK runs checkout finalization automatically.

V2 contract notes

• payments.getMethods sends the current invoice identifier to /api/v2/payments/list.
• /api/v2/payments/{id}/process_payment_step behavior depends on exact Content-Type.
• JSON mode must use exact application/json when top-level paymentIdentifier is needed.
• Use form mode for gateways that post callback/form payloads.

Methods

Get Methods

Use: payments.getMethods(options?).

Returns available payment methods for current invoice credentials.

const methodsRes = await client.payments.getMethods();

Create

Use: payments.create(paymentTypeId, options?).

Returns: SazitoResponse<Payment>.

const methodsRes = await client.payments.getMethods();
if (methodsRes.data?.length) {
  await client.payments.create(methodsRes.data[0].id);
}

Initialize

Use: payments.initialize(options?).

Initializes current payment and returns next action.

Returns: SazitoResponse<PaymentAction>.

When payment verification succeeds (action === 'showOrder'), the SDK automatically calls POST /api/v1/pinch/order as part of checkout completion.

const actionRes = await client.payments.initialize();

if (actionRes.data?.action === 'REDIRECT') {
  console.log('Redirect to:', actionRes.data.address);
}

Process Step

Use: payments.processStep(input, options?).

Use this for JSON-mode step requests (commonly cardtocardpayment) after create/initialize.

const cardToCardStep = await client.payments.processStep({
  imageUrl: 'https://cdn.example.com/payment-proof.png',
  code: '894512',
});

Process Step (Form Mode)

Use: payments.processStepForm(input, options?).

Use this when gateway flow requires non-JSON form payload handling for /api/v2/payments/{id}/process_payment_step.

const stepRes = await client.payments.processStepForm({
  code: '894512',
  imageUrl: 'https://cdn.example.com/payment-proof.png',
});

Poll Until Settled

Use: payments.pollUntilSettled(options?, intervalMs?).

Polls payment state via process_payment_step every 15 seconds by default until action !== 'pending'.

const finalAction = await client.payments.pollUntilSettled(undefined, 5000);

Clear Payment

Use: payments.clearPayment().

Clears persisted payment credentials.

client.payments.clearPayment();

Response key fields

Payment Method

Payment Action

Known errors

Examples

// app/lib/sazito-client.ts
import { createSazitoClient } from '@sazito/client-sdk';

export const sazito = createSazitoClient({
  domain: process.env.NEXT_PUBLIC_SAZITO_DOMAIN!,
});

// app/[lang]/(home)/page.tsx
'use client';
import { useEffect, useState } from 'react';
import { sazito } from '@/app/lib/sazito-client';

export default function Example() {
  const [data, setData] = useState<any>(null);

  useEffect(() => {
    (async () => {
      await sazito.cart.addItem(12001, 1);
      await sazito.invoices.create();
      const methods = await sazito.payments.getMethods();

      if (!methods.data?.length) {
        setData({ message: 'No payment methods available' });
        return;
      }

      await sazito.payments.create(methods.data[0].id);
      const action = await sazito.payments.initialize();
      setData(action.data ?? null);
    })();
  }, []);

  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Type Details

The following tables are generated from SDK TypeScript types and include nested object fields.

PaymentMethod

Source: src/types/payment.ts

Payment

Source: src/types/payment.ts

PaymentAction

Source: src/types/payment.ts

PaymentStepInput

Source: src/types/payment.ts