# Tipos & enums

Referência de tipos, estados e métodos de pagamento da SDK.

A SDK é tipada em TypeScript. Os tipos abaixo refletem `src/@types/api.ts`.

## Enums

### PaymentStatus

```ts
enum PaymentStatus {
  CREATED   = "created",
  PENDING   = "pending",
  CANCELLED = "cancelled",
  CONFIRMED = "confirmed",
}
```

<Note>
A SDK (frontend) usa estes valores textuais. A **API** usa os códigos curtos
`PEN` / `CON` / `CAN` (ver [Referência da API](/pt/api-reference/introduction)).
</Note>

### PaymentMethod

```ts
enum PaymentMethod {
  FPMCXEXPRSS = "FPMCXEXPRSS", // Multicaixa Express
  FPSOLPG     = "FPSOLPG",     // FaciPay (direto) — sempre disponível
  FPSOLPGEXT  = "FPSOLPGEXT",  // Referência EMIS
}
```

<Info>
Por omissão em `constants.js`: `allowedPaymentMethods = ["FPMCXEXPRSS","FPSOLPGEXT","FPSOLPG"]`,
`defaultPaymentMethod = "FPMCXEXPRSS"`. Confirme os rótulos exatos com a equipa (há divergência
entre material web e mobile).
</Info>

### PaymentType

```ts
enum PaymentType { DIR = "dir", MCX = "mcx", REF = "ref" }
```

### Theme / ButtonShape / Language

```ts
enum Theme       { LIGHT = "light", DARK = "dark" }
enum ButtonShape { RECT = "rect", PILL = "pill" }
enum Language    { PT = "pt", EN = "en" }
```

### ApiKeyStatus

```ts
type ApiKeyStatus = 'idle' | 'loading' | 'valid' | 'invalid' | 'empty';
```

## Dados dos callbacks

### PaymentApprovalData

```ts
interface PaymentApprovalData {
  transactionId: string;
  externalTransactionId: string;
  status: PaymentStatus.CONFIRMED;
  amount: number;
  currency: string;          // "AOA"
  paymentMethod: PaymentMethod;
  timestamp: string;
}
```

### PaymentPendingData

```ts
interface PaymentPendingData {
  transactionId: string;
  externalTransactionId: string;
  status: PaymentStatus.PENDING;
  amount: number;
  currency: string;
  paymentMethod: PaymentMethod;
  timestamp: string;
}
```

### PaymentCancelData

```ts
interface PaymentCancelData {
  transactionId?: string;
  externalTransactionId?: string;
  status: PaymentStatus.CANCELLED;
  reason?: string;
  timestamp: string;
}
```

### PaymentError

```ts
interface PaymentError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
  timestamp: string;
}
```

## Configuração

### ButtonOptions

```ts
interface ButtonOptions {
  style?: { width?: string | number; shape?: ButtonShape };
  config?: { lang?: Language; showAmount?: boolean };
  paymentConfig?: PaymentConfig;
}

interface PaymentConfig {
  theme?: Theme;
  defaultPaymentMethod?: PaymentMethod;
  allowedPaymentMethods?: PaymentMethod[];
  showUIOfProcessingInfo?: boolean;
  referencePaymentLifeSpan?: number;     // minutos
  customerInfo?: { name?: string; phone?: string; email?: string }; // email é ignorado pela SDK
}
```

### GenerateButtonParams

```ts
interface GenerateButtonParams {
  createOrder?: () => Promise<string | null>;
  onApprove?: (data: PaymentApprovalData, actions) => Promise<void>;
  onCancel?: (data: PaymentCancelData) => Promise<void>;
  onError?: (error: PaymentError) => Promise<void>;
  onPending?: (data: PaymentPendingData, actions) => Promise<void>;
  onInit?: (actions) => Promise<void>;
  onClick?: (data, actions) => Promise<void>;
  options?: ButtonOptions;
}
```

<Warning>
Estas definições derivam dos ficheiros **TypeScript** do repositório, que estão
**desatualizados**. A implementação **JavaScript** (`Button.js`) é a fonte autoritativa: por
exemplo, `onApprove`/`onPending` recebem `{ payment: { orderId, status, type, data } }` e o
2.º argumento `actions` só expõe `onPopupWindowClosed`. Ver [Callbacks](/pt/sdk/callbacks) e
[Objeto Button](/pt/sdk/button-object) para o contrato real.
</Warning>