npm package: @firstdata/first-data-gateway
Description: TypeScript SDK to be used with First Data's IPG API (version 21.5.0). This SDK has been created and packaged to offer the easiest way to integrate your application into the First Data Gateway. This SDK gives you the ability to run transactions such as sal
Latest version: 1.14.0

# FirstApiSDK

FirstApiSdk - Typescript client for FirstApiSDK

Payment Gateway API Specification.
- API version: 21.5.0
- Package version: 1.14.0

## Installation

```shell
    npm install @firstdata/first-data-gateway --save --save-exact
```

## Reference Documentation

https://docs.firstdata.com/org/gateway/docs/api

## Getting Started

```typescript
import {AxiosPromise} from "axios";
import {
  Amount,
  PrimaryTransaction,
  PrimaryTransactionParams,
  PaymentMethod,
  TransactionType,
  Card,
  TransactionResponse,
  Context, IContext,
  ICredentials,
  IConfiguration,
  IClientFactory,
  IPaymentApi,
} from "@firstdata/first-data-gateway";

const getPaymentClient = (): IPaymentApi => {
  const credentials: ICredentials = {
    apiKey: "API_KEY_HERE",
    apiSecret: "API_SECRET_HERE",
  };

  const config: IConfiguration {
    basePath: "https://cert.api.firstdata.com/gateway",
    credentials,
  };

  const context: IContext = new Context(config);
  const factory: IClientFactory = context.factory;
  return factory.paymentApi();
};

const getApiParams = (): PrimaryTransactionParams => {
  const amount: Amount = {
    total: 27.00,

    // ISO 4217 currency code
    currency: "USD",
  };

  const card: Card = {
    cardholderName: "Example Name",
    cardNumber: "4242424242424242",
    expDate: "022022", // MMCCYY
    cvv: "123",
  };

  const paymentMethod: PaymentMethod = {
    methodType: PaymentMethod.MethodTypeEnum.Card,
    card,
  };

  const payload: PrimaryTransaction = {
    transactionType: TransactionType.SALE,
    amount,
    paymentMethod,
  };

  return {
    payload,
  };
};

const responsePromise: AxiosPromise<TransactionResponse> =
  getPaymentClient().primaryPaymentTransaction(getApiParams());

```


## Repo Organization

- src/openapi/: code auto-generated from api specification
- src/firstdata/: code manually created for simpler API
- src/firstdata/api/: wrapper classes for each api
- src/firstdata/context.ts: takes care of object instantiation while still providing flexibility
- src/firstdata/factory.ts: an instance of this class is exposed on Context instances and provides noarg methods to instantiate each api client
- src/firstdata/models.ts: exposes models both autogenerated and specific to the wrapper api classes


## API Methods/Endpoints

All URIs are relative to *https://cert.api.firstdata.com/gateway*

Interface | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*IAuthenticationApi* | **getAccessToken** | **POST** /v2/authentication/access-tokens | Generate an access token for user authentication.
*IInformationLookupApi* | **cardInfoLookup** | **POST** /v2/card-information | Card information lookUp
*IInformationLookupApi* | **lookUpAccount** | **POST** /v2/account-information | Account information lookUp
*IVerificationApi* | **verifyCard** | **POST** /v2/card-verification | Verify a payment card.
*IVerificationApi* | **verifyAccount** | **POST** /v2/account-verification | Verify a payment account.
*ICurrencyConversionApi* | **getExchangeRate** | **POST** /v2/exchange-rates | Generate dynamic currency conversion transactions
*IFraudDetectApi* | **scoreOnly** | **POST** /v2/fraud/score-only | Score a transaction for fraud.
*IFraudDetectApi* | **clientRegistration** | **POST** /v2/fraud/client-registration | Client Registration for fraud detect.
*IFraudDetectApi* | **paymentRegistration** | **POST** /v2/fraud/payment-registration | Payment Registration for fraud detect.
*IOrderApi* | **orderInquiry** | **GET** /v2/orders/{order-id} | Retrieve the state of an order
*IOrderApi* | **secondaryTransaction** | **POST** /v2/orders/{order-id} | Perform a return or postAuth on an already existing order.
*IPaymentApi* | **finalizeSecureTransaction** | **PATCH** /v2/payments/{transaction-id} | Update a 3DSecure or UnionPay payment and continue processing.
*IPaymentApi* | **secondaryTransaction** | **POST** /v2/payments/{transaction-id} | Perform a void, postAuth or return secondary transaction.
*IPaymentApi* | **primaryTransaction** | **POST** /v2/payments | Generate a primary transaction.
*IPaymentApi* | **transactionInquiry** | **GET** /v2/payments/{transaction-id} | Retrieve the state of a transaction.
*IPaymentSchedulesApi* | **cancelPaymentSchedule** | **DELETE** /v2/payment-schedules/{order-id} | Cancel a gateway payment schedule.
*IPaymentSchedulesApi* | **createPaymentSchedule** | **POST** /v2/payment-schedules | Use this to create a gateway payment schedule.
*IPaymentSchedulesApi* | **inquiryPaymentSchedule** | **GET** /v2/payment-schedules/{order-id} | View a gateway payment schedule.
*IPaymentSchedulesApi* | **updatePaymentSchedule** | **PATCH** /v2/payment-schedules/{order-id} | Update a gateway payment schedule.
*IPaymentTokenApi* | **createPaymentToken** | **POST** /v2/payment-tokens | Create a payment token from a payment card.
*IPaymentTokenApi* | **deletePaymentToken** | **DELETE** /v2/payment-tokens/{token-id} | Delete a payment token.
*IPaymentTokenApi* | **getPaymentTokenDetails** | **GET** /v2/payment-tokens/{token-id} | Get details of an existing token.
*IPaymentTokenApi* | **updatePaymentToken** | **PATCH** /v2/payment-tokens | Update payment token information.
*IPaymentUrlApi* | **createPaymentUrl** | **POST** /v2/payment-url | Create a payment URL.
*IPaymentUrlApi* | **deletePaymentUrl** | **DELETE** /v2/payment-url | Delete a payment URL.
*IPaymentUrlApi* | **paymentUrlDetail** | **GET** /v2/payment-url | Retrive the state of a payment URL.


## Code Overview

### Context and Configuration

```typescript
interface ICredentials {
  apiKey: string;
  apiSecret: string;
}

interface IConfiguration {
  basePath: string;
  credentials: ICredentials;
  storeId?: string;
  region?: string;
  axios?: AxiosInstance;
  factory?: IClientFactory;
}

interface IContext extends IConfiguration {
  readonly axios: AxiosInstance;
  readonly basePath: string;
  readonly credentials: ICredentials
  readonly factory: IClientFactory;
}

class Context implements IContext {
  public constructor(config: IConfiguration) { /*...*/ }
}
```

### IClientFactory

```typescript
interface IClientFactory {
  authenticationApi(): IAuthenticationApi;
  cardInfoLookupApi(): IInformationLookupApi;
  cardVerificationApi(): IVerificationApi;
  currencyConversionApi(): ICurrencyConversionApi;
  fraudDetectApi(): IFraudDetectApi;
  orderApi(): IOrderApi;
  paymentApi(): IPaymentApi;
  paymentSchedulesApi(): IPaymentSchedulesApi;
  paymentTokenApi(): IPaymentTokenApi;
  paymentUrlApi(): IPaymentUrlApi;
}
```

### IAuthenticationApi

```typescript
interface IAuthenticationApi {
  getAccessToken(params: GetAccessTokenParams): AxiosPromise<AccessTokenResponse>;
}
```

### IInformationLookupApi

```typescript
type CardInfoLookupParams = {
  region?: string;
  payload: CardInfoLookupRequest;
};

type AcctInfoLookupParams = {
  region?: string;
  payload: AccountInfoLookupRequest>
};

interface IInformationLookupApi {
  cardInfoLookup(params: CardInfoLookupParams): AxiosPromise<CardInfoLookupResponse>;
  acctInfoLookup(params: AcctInfoLookupParams): AxiosPromise<CardInfoLookupResponse>
}
```

### IVerificationApi

```typescript
type VerifyCardParams = {
  region?: string;
  payload: CardVerificationRequest;
};

type VerifyAccountParams = {
  region?: string;
  payload: AccountVerificationRequest;
}

interface IVerificationApi {
  verifyCard(params: VerifyCardParams): AxiosPromise<TransactionResponse>;
  verifyAcct(params: VerifyAcctParams): AxiosPromise<TransactionResponse>
}
```

### ICurrencyConversionApi

```typescript
type ExchangeRateParams = {
  region?: string;
  payload: ExchangeRateRequest;
};

interface ICurrencyConversionApi {
  getExchangeRate(params: ExchangeRateParams): AxiosPromise<ExchangeRateResponse>;
}
```

### IFraudDetectApi

```typescript
type ScoreOnlyParams = {
  region?: string;
  payload: ScoreOnlyRequest;
};

type ClientRegistrationParams = {
  region?: string;
  payload: ClientRegistration;
};

type PaymentRegistrationParams = {
  region?: string;
  payload: PaymentRegistration;
};

interface IFraudDetectApi {
  scoreOnly(params: ScoreOnlyParams): AxiosPromise<ScoreOnlyResponse>;
  fraudClientRegistrationPost(params: ClientRegistrationParams): AxiosPromise<FraudRegistrationResponse>;
  fraudPaymentRegistrationPost(params: PaymentRegistrationParams): AxiosPromise<FraudRegistrationResponse>;
}
```

### IOrderApi

```typescript
type OrderParams = {
  region?: string;
  storeId?: string;
  orderId: string;
};

type SecondaryTxOrderParams = OrderParams & {
  payload: SecondaryTransaction;
};

interface IOrderApi {
  orderInquiry(params: OrderParams): AxiosPromise<OrderResponse>;
  orderPostAuth(params: SecondaryTxOrderParams): AxiosPromise<TransactionResponse>;
  orderReturnTransaction(params: SecondaryTxOrderParams): AxiosPromise<TransactionResponse>;
}
```

### IPaymentSchedulesApi

```typescript
type ExistingPaymentScheduleParams = {
  region?: string;
  storeId?: string;
  orderId: string;
};

type CreatePaymentScheduleParams = {
  region?: string;
  payload: PaymentSchedulesRequest;
};

type UpdatePaymentScheduleParams =
  CreatePaymentScheduleParams & ExistingPaymentScheduleParams;

interface IPaymentSchedulesApi {
  cancelPaymentSchedule(params: ExistingPaymentScheduleParams): AxiosPromise<PaymentSchedulesResponse>;
  createPaymentSchedule(params: CreatePaymentScheduleParams): AxiosPromise<PaymentSchedulesResponse>;
  inquiryPaymentSchedule(params: ExistingPaymentScheduleParams): AxiosPromise<RecurringPaymentDetailsResponse>;
  updatePaymentSchedule(params: UpdatePaymentScheduleParams): AxiosPromise<PaymentSchedulesResponse>;
}
```

### IPaymentTokenApi

```typescript
type PaymentTokenParams = {
  region?: string;
  authorization?: string;
};

type CreatePaymentTokenParams =
  PaymentTokenParams & {
    payload: PaymentTokenizationRequest;
  };

type DeletePaymentTokenParams =
  PaymentTokenParams & {
    tokenId: string;
    storeId?: string;
  };

  type GetPaymentTokenDetailsParams =
  PaymentTokenParams & {
    tokenId: string;
    storeId?: string;
  };

  type UpdatePaymentTokenParams =
  PaymentTokenParams & {
    payload: PaymentCardPaymentTokenUpdateRequest
  };

interface IPaymentTokenApi {
  createPaymentToken(params: CreatePaymentTokenParams): AxiosPromise<PaymentTokenizationResponse>;
  deletePaymentToken(params: DeletePaymentTokenParams): AxiosPromise<PaymentTokenizationResponse>;
  getPaymentTokenDetails(params: GetPaymentTokenParams): AxiosPromise<PaymentTokenizationResponse>;
  updatePaymentToken(params: UpdatePaymentTokenParams): AxiosPromise<PaymentTokenUpdateResponse>;
}
```

### IPaymentUrlApi

```typescript
type CreatePaymentUrlParams = {
  region?: string;
  payload: PaymentUrlRequest;
};

type DeletePaymentUrlParams = {
  region?: string;
  storeId?: string;
  transactionId?: string;
  orderId?: string;
  paymentUrlId?: string;
  transactionTime?; string;
};

type PaymentUrlDetailParams = {
  region?: string;
  storeId?: string;
  fromDate: string;
  toDate: string;
  orderId?: string;
  merchantTransactionId?: string;
  status?: string;
};

interface IPaymentUrlApi {
  createPaymentUrl(params: CreatePaymentUrlParams): AxiosPromise<PaymentUrlResponse>;
  deletePaymentUrl(params: DeletePaymentUrlParams): AxiosPromise<PaymentUrlResponse>;
  paymentUrlDetail(params: PaymentUrlDetailParams): AxiosPromise<PaymentUrlDetailResponse>;
}
```

### IPaymentApi

```typescript
type PaymentParams = {
  region?: string;
  storeId?: string;
  transactionId: string;
};

type SecondaryTxPaymentParams =
  PaymentParams & {
    payload: SecondaryTransaction;
  };

type PrimaryTransactionParams = {
  region?: string;
  payload: PrimaryTransaction;
};

type FinalizeTransactionParams = {
  region?: string;
  transactionId: string;
  payload: AuthenticationResponseVerificationRequest;
};

interface IPaymentApi {
  finalizeSecureTransaction(params: FinalizeTransactionParams): AxiosPromise<TransactionResponse>;
  performPaymentPostAuthorisation(params: SecondaryTxPaymentParams): AxiosPromise<TransactionResponse>;
  primaryPaymentTransaction(params: PrimaryTransactionParams): AxiosPromise<TransactionResponse>;
  returnTransaction(params: SecondaryTxPaymentParams): AxiosPromise<TransactionResponse>;
  transactionInquiry(params: PaymentParams): AxiosPromise<TransactionResponse>;
  voidTransaction(params: PaymentParams): AxiosPromise<TransactionResponse>;
}
```