packages/payments/core/interface.ts

   1 import type {
   2     BinData,
   3     CardFormRenderMode,
   4     ChargebeeSavedCardAuthorizationSuccess,
   5     ChargebeeSubmitDirectDebitEventPayload,
   6     ChargebeeSubmitEventPayload,
   7     ChargebeeSubmitEventResponse,
   8     ChargebeeVerifySavedCardEventPayload,
   9     FormValidationErrors,
  10     GetHeightResponse,
  11     MessageBusResponse,
  12     MessageBusResponseSuccess,
  13     PaymentIntent,
  14     PaypalAuthorizedPayload,
  15     SetPaypalPaymentIntentPayload,
  16     ThreeDsChallengePayload,
  17 } from '@proton/chargebee/lib';
  18 import type { PaymentProcessorType } from '@proton/components/payments/react-extensions/interface';
  19 import type { CheckSubscriptionData, PaymentsVersion } from '@proton/shared/lib/api/payments';
  20 import type { SubscriptionCheckResponse } from '@proton/shared/lib/interfaces';
  21
  22 import type {
  23     ADDON_NAMES,
  24     Autopay,
  25     CURRENCIES,
  26     FREE_SUBSCRIPTION,
  27     INVOICE_STATE,
  28     INVOICE_TYPE,
  29     MethodStorage,
  30     PAYMENT_METHOD_TYPES,
  31     PAYMENT_TOKEN_STATUS,
  32     PLANS,
  33 } from './constants';
  34
  35 export interface CreateCardDetailsBackend {
  36     Number: string;
  37     ExpMonth: string;
  38     ExpYear: string;
  39     CVC: string;
  40     ZIP: string;
  41     Country: string;
  42 }
  43
  44 export interface CardPayment {
  45     Type: PAYMENT_METHOD_TYPES.CARD;
  46     Details: CreateCardDetailsBackend;
  47 }
  48
  49 export interface TokenPayment {
  50     Type: PAYMENT_METHOD_TYPES.TOKEN;
  51     Details: {
  52         Token: string;
  53     };
  54 }
  55
  56 export type WrappedPaymentsVersion = {
  57     paymentsVersion: PaymentsVersion;
  58 };
  59
  60 export type WrappedProcessorType = {
  61     paymentProcessorType: PaymentProcessorType;
  62 };
  63
  64 export type ExtendedTokenPayment = Partial<TokenPayment> & WrappedProcessorType & WrappedPaymentsVersion;
  65
  66 export interface PaypalPayment {
  67     Type: PAYMENT_METHOD_TYPES.PAYPAL | PAYMENT_METHOD_TYPES.PAYPAL_CREDIT;
  68 }
  69
  70 export interface WrappedPaypalPayment {
  71     Payment: PaypalPayment;
  72 }
  73
  74 export interface ExistingPayment {
  75     PaymentMethodID: string;
  76 }
  77
  78 export interface WrappedCardPayment {
  79     Payment: CardPayment;
  80 }
  81
  82 export interface TokenPaymentMethod {
  83     Payment: TokenPayment;
  84 }
  85
  86 export type Currency = (typeof CURRENCIES)[number];
  87
  88 export interface AmountAndCurrency {
  89     Amount: number;
  90     Currency: Currency;
  91 }
  92
  93 export interface PaymentTokenResult {
  94     Token: string;
  95     Status: PAYMENT_TOKEN_STATUS;
  96     ApprovalURL?: string;
  97     ReturnHost?: string;
  98 }
  99
 100 export type PlainPaymentMethodType = `${PAYMENT_METHOD_TYPES}`;
 101
 102 export type ChargeablePaymentParameters = Partial<V5PaymentToken> &
 103     AmountAndCurrency & {
 104         type:
 105             | PAYMENT_METHOD_TYPES.PAYPAL
 106             | PAYMENT_METHOD_TYPES.PAYPAL_CREDIT
 107             | PAYMENT_METHOD_TYPES.CARD
 108             | PAYMENT_METHOD_TYPES.CHARGEBEE_CARD
 109             | PAYMENT_METHOD_TYPES.CHARGEBEE_PAYPAL
 110             | PAYMENT_METHOD_TYPES.BITCOIN
 111             | PAYMENT_METHOD_TYPES.CHARGEBEE_BITCOIN
 112             | PAYMENT_METHOD_TYPES.CHARGEBEE_SEPA_DIRECT_DEBIT;
 113         chargeable: true;
 114     };
 115
 116 export type ChargeablePaymentToken = V5PaymentToken &
 117     AmountAndCurrency & {
 118         type:
 119             | PAYMENT_METHOD_TYPES.PAYPAL
 120             | PAYMENT_METHOD_TYPES.PAYPAL_CREDIT
 121             | PAYMENT_METHOD_TYPES.CARD
 122             | PAYMENT_METHOD_TYPES.CHARGEBEE_CARD
 123             | PAYMENT_METHOD_TYPES.CHARGEBEE_PAYPAL
 124             | PAYMENT_METHOD_TYPES.CHARGEBEE_SEPA_DIRECT_DEBIT;
 125         chargeable: true;
 126     };
 127
 128 export type NonChargeablePaymentToken = Omit<ChargeablePaymentToken, 'chargeable'> & {
 129     chargeable: false;
 130     status: PAYMENT_TOKEN_STATUS;
 131     returnHost: string;
 132     approvalURL: string;
 133 };
 134
 135 export interface PaymentMethodStatus {
 136     Card: boolean;
 137     Paypal: boolean;
 138     Apple: boolean;
 139     Cash: boolean;
 140     Bitcoin: boolean;
 141 }
 142
 143 export interface PaymentMethodStatusExtended {
 144     CountryCode: string;
 145     State?: string | null;
 146     VendorStates: PaymentMethodStatus;
 147 }
 148
 149 export interface PayPalDetails {
 150     BillingAgreementID: string;
 151     PayerID: string;
 152     Payer: string;
 153 }
 154
 155 export interface SavedCardDetails {
 156     /**
 157      * Even though you can't add the name to the card, it's still returned from the API for old users who already
 158      * have the card name.
 159      */
 160     Name?: string | null;
 161     ExpMonth: string;
 162     ExpYear: string;
 163     ZIP: string;
 164     Country: string;
 165     Last4: string;
 166     Brand: string;
 167 }
 168
 169 export type PaymentMethodCardDetails = {
 170     Order: number;
 171     ID: string;
 172     Type: PAYMENT_METHOD_TYPES.CARD | PAYMENT_METHOD_TYPES.CHARGEBEE_CARD;
 173     Details: SavedCardDetails;
 174     Autopay: Autopay;
 175     External?: MethodStorage;
 176 };
 177
 178 export type PaymentMethodCardDetailsInternal = {
 179     Type: PAYMENT_METHOD_TYPES.CARD;
 180     External?: MethodStorage.INTERNAL;
 181 } & PaymentMethodCardDetails;
 182
 183 export type PaymentMethodCardDetailsExternal = {
 184     Type: PAYMENT_METHOD_TYPES.CHARGEBEE_CARD;
 185     External: MethodStorage.EXTERNAL;
 186 } & PaymentMethodCardDetails;
 187
 188 export type PaymentMethodPaypal = {
 189     Order: number;
 190     ID: string;
 191     Type: PAYMENT_METHOD_TYPES.PAYPAL | PAYMENT_METHOD_TYPES.CHARGEBEE_PAYPAL;
 192     Details: PayPalDetails;
 193     External?: MethodStorage;
 194 };
 195
 196 export type PaymentMethodPaypalInternal = {
 197     Type: PAYMENT_METHOD_TYPES.PAYPAL;
 198     External?: MethodStorage.INTERNAL;
 199 } & PaymentMethodPaypal;
 200
 201 export type PaymentMethodPaypalExternal = {
 202     Type: PAYMENT_METHOD_TYPES.CHARGEBEE_PAYPAL;
 203     External: MethodStorage.EXTERNAL;
 204 } & PaymentMethodPaypal;
 205
 206 export type SepaDetails = {
 207     AccountName: string;
 208     Country: string;
 209     Last4: string;
 210 };
 211
 212 export type PaymentMethodSepa = {
 213     ID: string;
 214     Type: PAYMENT_METHOD_TYPES.CHARGEBEE_SEPA_DIRECT_DEBIT;
 215     Order: number;
 216     Autopay: Autopay;
 217     External?: MethodStorage;
 218     Details: SepaDetails;
 219 };
 220
 221 export type SavedPaymentMethod = PaymentMethodPaypal | PaymentMethodCardDetails | PaymentMethodSepa;
 222 export type SavedPaymentMethodInternal = PaymentMethodPaypalInternal | PaymentMethodCardDetailsInternal;
 223 export type SavedPaymentMethodExternal = PaymentMethodPaypalExternal | PaymentMethodCardDetailsExternal;
 224
 225 export interface LatestSubscription {
 226     LastSubscriptionEnd: number;
 227 }
 228
 229 export type ExistingPaymentMethod = string;
 230
 231 export type PaymentMethodType = PlainPaymentMethodType | ExistingPaymentMethod;
 232
 233 export interface AvailablePaymentMethod {
 234     readonly type: PlainPaymentMethodType;
 235     readonly paymentMethodId?: string; // defined only for existing payment methods
 236     readonly isExpired?: boolean; // defined only for existing credit cards
 237     readonly value: PaymentMethodType;
 238     readonly isSaved: boolean;
 239 }
 240
 241 export type PaymentMethodFlows =
 242     | 'invoice'
 243     | 'signup'
 244     | 'signup-pass'
 245     | 'signup-pass-upgrade'
 246     | 'signup-v2'
 247     | 'signup-v2-upgrade'
 248     | 'signup-vpn'
 249     | 'credit'
 250     | 'subscription'
 251     | 'add-card'
 252     | 'add-paypal';
 253
 254 export type V5Payments = {
 255     v: 5;
 256 };
 257
 258 export type V5PaymentToken = {
 259     PaymentToken: string;
 260 } & V5Payments;
 261
 262 export type ChargeableV5PaymentToken = ChargeablePaymentToken & {
 263     type:
 264         | PAYMENT_METHOD_TYPES.CHARGEBEE_CARD
 265         | PAYMENT_METHOD_TYPES.CHARGEBEE_PAYPAL
 266         | PAYMENT_METHOD_TYPES.CHARGEBEE_SEPA_DIRECT_DEBIT;
 267 };
 268
 269 export type NonChargeableV5PaymentToken = Omit<ChargeableV5PaymentToken, 'chargeable'> & {
 270     chargeable: false;
 271 };
 272
 273 export type AuthorizedV5PaymentToken = {
 274     authorized: true;
 275 };
 276
 277 export type NonAuthorizedV5PaymentToken = {
 278     authorized: false;
 279     approvalUrl: string;
 280 };
 281
 282 export type ChargeableV5PaymentParameters = ChargeablePaymentParameters & {
 283     type:
 284         | PAYMENT_METHOD_TYPES.CHARGEBEE_CARD
 285         | PAYMENT_METHOD_TYPES.CHARGEBEE_PAYPAL
 286         | PAYMENT_METHOD_TYPES.CHARGEBEE_BITCOIN
 287         | PAYMENT_METHOD_TYPES.CHARGEBEE_SEPA_DIRECT_DEBIT;
 288 };
 289
 290 export type ChargebeeFetchedPaymentToken = (ChargeableV5PaymentToken | NonChargeableV5PaymentToken) &
 291     (AuthorizedV5PaymentToken | NonAuthorizedV5PaymentToken);
 292
 293 export type CheckWithAutomaticOptions = {
 294     forcedVersion: PaymentsVersion;
 295     reason: string;
 296     silence?: boolean;
 297 };
 298
 299 export type MultiCheckSubscriptionData = CheckSubscriptionData & (CheckWithAutomaticOptions | {});
 300
 301 export type RequestOptions = {
 302     signal?: AbortSignal;
 303     silence?: boolean;
 304 };
 305
 306 export type MultiCheckOptions = {
 307     cached?: boolean;
 308 } & RequestOptions;
 309
 310 export type GetPlansData = {
 311     currency?: Currency;
 312 };
 313
 314 export interface PaymentsApi {
 315     checkWithAutomaticVersion: (
 316         data: CheckSubscriptionData,
 317         requestOptions?: RequestOptions,
 318         options?: CheckWithAutomaticOptions
 319     ) => Promise<SubscriptionCheckResponse>;
 320
 321     multiCheck: (
 322         data: MultiCheckSubscriptionData[],
 323         options?: MultiCheckOptions
 324     ) => Promise<SubscriptionCheckResponse[]>;
 325
 326     cacheMultiCheck: (
 327         data: CheckSubscriptionData,
 328         options: CheckWithAutomaticOptions | undefined,
 329         result: SubscriptionCheckResponse
 330     ) => void;
 331
 332     statusExtendedAutomatic: () => Promise<PaymentMethodStatusExtended>;
 333 }
 334
 335 export type ChargebeeKillSwitchData = {
 336     reason: string;
 337     data?: any;
 338     error?: any;
 339 };
 340 export type ChargebeeKillSwitch = (data?: ChargebeeKillSwitchData) => boolean;
 341 export type ForceEnableChargebee = () => void;
 342
 343 export type RemoveEventListener = () => void;
 344
 345 export type InitializeCreditCardOptions = {
 346     isNarrow: boolean;
 347 };
 348
 349 export type ChargebeeIframeHandles = {
 350     submitCreditCard: (
 351         payload: ChargebeeSubmitEventPayload
 352     ) => Promise<MessageBusResponseSuccess<ChargebeeSubmitEventResponse>>;
 353     initializeCreditCard: (props: InitializeCreditCardOptions) => Promise<any>;
 354     initializeSavedCreditCard: () => Promise<any>;
 355     validateSavedCreditCard: (
 356         payload: ChargebeeVerifySavedCardEventPayload
 357     ) => Promise<MessageBusResponseSuccess<ChargebeeSavedCardAuthorizationSuccess>>;
 358     initializePaypal: () => Promise<any>;
 359     setPaypalPaymentIntent: (payload: SetPaypalPaymentIntentPayload, abortSignal: AbortSignal) => Promise<any>;
 360     getHeight: () => Promise<GetHeightResponse>;
 361     getBin: () => Promise<MessageBusResponse<BinData | null>>;
 362     validateCardForm: () => Promise<MessageBusResponse<FormValidationErrors>>;
 363     changeRenderMode: (renderMode: CardFormRenderMode) => Promise<any>;
 364     updateFields: () => Promise<any>;
 365     initializeDirectDebit: () => Promise<any>;
 366     submitDirectDebit: (payload: ChargebeeSubmitDirectDebitEventPayload) => Promise<MessageBusResponseSuccess<unknown>>;
 367 };
 368
 369 export type ChargebeeIframeEvents = {
 370     onPaypalAuthorized: (callback: (payload: PaypalAuthorizedPayload) => any) => RemoveEventListener;
 371     onPaypalFailure: (callback: (error: any) => any) => RemoveEventListener;
 372     onPaypalClicked: (callback: () => any) => RemoveEventListener;
 373     onPaypalCancelled: (callback: () => any) => RemoveEventListener;
 374     onThreeDsChallenge: (callback: (payload: ThreeDsChallengePayload) => any) => RemoveEventListener;
 375     onThreeDsSuccess: (callback: (payload: PaymentIntent) => any) => RemoveEventListener;
 376     onThreeDsFailure: (callback: (error: any) => any) => RemoveEventListener;
 377     onCardVeririfcation3dsChallenge: (callback: (payload: ThreeDsChallengePayload) => any) => RemoveEventListener;
 378     onCardVeririfcationSuccess: (
 379         callback: (payload: ChargebeeSavedCardAuthorizationSuccess) => any
 380     ) => RemoveEventListener;
 381     onCardVeririfcationFailure: (callback: (error: any) => any) => RemoveEventListener;
 382     onUnhandledError: (
 383         callback: (error: any, rawError: any, messagePayload: any, checkpoints: any[]) => any
 384     ) => RemoveEventListener;
 385 };
 386
 387 export type CryptocurrencyType = 'bitcoin';
 388
 389 export interface CryptoPayment {
 390     Type: 'cryptocurrency';
 391     Details: {
 392         Coin: CryptocurrencyType;
 393     };
 394 }
 395
 396 export interface WrappedCryptoPayment {
 397     Payment: CryptoPayment;
 398 }
 399
 400 export interface Invoice {
 401     ID: string;
 402     Type: INVOICE_TYPE;
 403     State: INVOICE_STATE;
 404     Currency: Currency;
 405     AmountDue: number;
 406     AmountCharged: number;
 407     CreateTime: number;
 408     ModifyTime: number;
 409     AttemptTime: number;
 410     Attempts: number;
 411     IsExternal: boolean;
 412 }
 413
 414 export interface InvoiceResponse {
 415     Code: number;
 416     Invoices: Invoice[];
 417     Total: number;
 418 }
 419
 420 type Quantity = number;
 421
 422 export type PlanIDs = Partial<{
 423     [planName in PLANS | ADDON_NAMES]: Quantity;
 424 }>;
 425
 426 export type MaxKeys =
 427     | 'MaxDomains'
 428     | 'MaxAddresses'
 429     | 'MaxSpace'
 430     | 'MaxMembers'
 431     | 'MaxVPN'
 432     | 'MaxTier'
 433     | 'MaxIPs' // synthetic key, it does't exist in the API
 434     | 'MaxAI'; // synthetic key, it does't exist in the API
 435
 436 export type FreeSubscription = typeof FREE_SUBSCRIPTION;