# StartPay Response Reference

Every payment attempt returns a `StartPayResponse` union.

## Success

```ts
{
  status: "success",
  success: true,
  paymentId: "PAY_123456",
  orderId: "ORDER_1001",
  transactionId: "TXN_987654",
  amount: 1500,
  currency: "INR",
  gateway: "custom",
  message: "Payment completed successfully",
  rawResponse: {},
  metadata: {},
  timestamp: "2026-07-01T13:30:00.000Z"
}
```

## Failed

```ts
{
  status: "failed",
  success: false,
  paymentId: "PAY_123456",
  orderId: "ORDER_1001",
  transactionId: null,
  amount: 1500,
  currency: "INR",
  gateway: "custom",
  errorCode: "PAYMENT_FAILED",
  message: "Payment failed",
  rawResponse: {},
  metadata: {},
  timestamp: "2026-07-01T13:30:00.000Z"
}
```

## Pending

```ts
{
  status: "pending",
  success: false,
  paymentId: "PAY_123456",
  orderId: "ORDER_1001",
  transactionId: null,
  amount: 1500,
  currency: "INR",
  gateway: "custom",
  message: "Payment is pending",
  rawResponse: {},
  metadata: {},
  timestamp: "2026-07-01T13:30:00.000Z"
}
```

## Cancelled

```ts
{
  status: "cancelled",
  success: false,
  paymentId: null,
  orderId: "ORDER_1001",
  transactionId: null,
  errorCode: "PAYMENT_CANCELLED",
  message: "Payment cancelled by user",
  rawResponse: {},
  metadata: {},
  timestamp: "2026-07-01T13:30:00.000Z"
}
```

## Error

```ts
{
  status: "error",
  success: false,
  orderId: "ORDER_1001",
  errorCode: "SDK_ERROR",
  message: "Something went wrong while starting payment",
  details: {},
  timestamp: "2026-07-01T13:30:00.000Z"
}
```

## Callback Mapping

| Status | Advanced callback | Legacy callback |
| --- | --- | --- |
| `success` | `onPaymentAuthorized` | `onSuccess` |
| `failed` | `onPaymentDeclined` | `onFailure` |
| `pending` | `onPaymentPendingReview` | `onPending` |
| `cancelled` | `onPaymentAborted` | `onCancel` |
| `error` | `onPaymentException` | `onError` |
| any status | `onPaymentSettled` | none |