FirstApiSDK

FirstApiSdk - Typescript client for FirstApiSDK

Payment Gateway API Specification.

• API version: 21.5.0
• Package version: 1.14.0

Installation

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

Reference Documentation

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

Getting Started

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

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

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

IAuthenticationApi

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

IInformationLookupApi

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

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

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

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

IFraudDetectApi

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

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

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

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

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

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>;
}