### Authentication and Integration Steps

Source: https://developers.tabapay.com/reference/getting-started

Information on how to authenticate requests and the initial steps required for integrating with the TabaPay API.

```APIDOC
## Integrating with TabaPay

### Steps to Integrate:

1.  **Get Access**: Email [help@tabapay.com](mailto:help@tabapay.com) to get access to the APIs.
2.  **Authentication**: TabaPay API uses API keys for authentication. Ensure your requests include the necessary API key.
3.  **HTTPS**: All API requests must be made over HTTPS. Plain HTTP calls will fail.
4.  **IP Whitelisting**: Provide TabaPay with the IP addresses you intend to use for API calls to ensure they are whitelisted.
```

--------------------------------

### Configure npm Start Script

Source: https://developers.tabapay.com/reference/integrate-apple-pay-server-setup

Defines a 'start' script in the package.json file to execute the index.js file using Node.js. This allows the application to be started with the command 'npm start'.

```json
"scripts": {
    "start": "node index.js"
  }
```

--------------------------------

### Setup Session - iOS (Swift)

Source: https://developers.tabapay.com/docs/how-to-use-the-3ds-sdk-starter-guide

Initiates the session setup process for TabaPay authentication on iOS using Swift. It takes a JWT string and provides callbacks for successful setup completion (returning a consumerSessionId) and setup failures.

```swift
let jwtString = "INSERT_THE_TABAPAY_INIT_JWT_HERE"

session.setup(jwtString: jwtString, completed: { (consumerSessionId: String) in
    //
    // You may have your Submit button disabled on page load. Once you are setup
    // for CCA, you may then enable it. This will prevent users from submitting
    // their order before CCA is ready.
    //
}) { (validateResponse: CardinalResponse) in
    // Handle failed setup
    // If there was an error with setup, cardinal will call this function with
    // validate response and empty serverJWT
}
```

--------------------------------

### Account Creation Success Response Example

Source: https://developers.tabapay.com/reference/accountcreate

This JSON response indicates a successful account creation. It includes the HTTP status code, an internal error code, a unique account ID, and optionally, card details like the last four digits and expiration date. This response confirms the account setup.

```json
{
  "SC": 200,
  "EC": "0",
  "accountID": "TabaPay_AccountID_22ch",
  "card": {
    "last4": "1234",
    "expirationDate": "202502"
  }
}
```

--------------------------------

### Tabapay Transaction Response Example (JSON)

Source: https://developers.tabapay.com/reference/getting-started

An example JSON response from the Tabapay Create Transaction API. The 'networkRC' field indicates the network's response code, where '00' typically means the transaction was approved or completed successfully. Not all networks may return this specific code.

```json
{
  "SC": 200,
  "EC": "0",
  "transactionID": "TabaPay_TransactionID_",
  "network": "Visa",
  "networkRC": "00",
  "status": "COMPLETED",
  "approvalCode": "000000"
}
```

--------------------------------

### Make Your First API Call - Retrieve Client

Source: https://developers.tabapay.com/docs/make-your-first-api-call

This guide walks you through making your first API call to retrieve client information. It involves setting up your request with a Bearer Token, FQDN, and ClientID.

```APIDOC
## POST /api/client/retrieve

### Description
This endpoint is used to retrieve client details after successful authentication. It's a foundational step for interacting with the TabaPay API.

### Method
POST

### Endpoint
`/api/client/retrieve`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bearerToken** (string) - Required - The authentication token for the API request.
- **clientId** (string) - Required - The unique identifier for the client.
- **fqdn** (string) - Required - The fully qualified domain name for the TabaPay API endpoint.

### Request Example
```json
{
  "bearerToken": "*Redacted*",
  "clientId": "YOUR_SANDBOX_CLIENT_ID",
  "fqdn": "https://sandbox.tabapay.com"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **approvedNetworks** (array) - Lists the networks approved for push or pull transactions.
- **pushLimits** (object) - Details on push transaction limits.
- **pullLimits** (object) - Details on pull transaction limits.

#### Response Example
```json
{
  "status": "success",
  "approvedNetworks": ["Visa", "Mastercard"],
  "pushLimits": {
    "daily": 10000,
    "monthly": 100000
  },
  "pullLimits": {
    "daily": 5000,
    "monthly": 50000
  }
}
```
```

--------------------------------

### Create Transaction: Example JSON for Push Payment

Source: https://developers.tabapay.com/reference/getting-started

This JSON object illustrates the request body parameters for a 'push' transaction, used for payouts. It specifies source and destination accounts, a reference ID, transaction type, and the amount.

```json
{
   "accounts": {
         "sourceAccountID": "zxc4123412341234123412",
         "destinationAccountID": "1234123412341234abc412"
    },
    "referenceID": "zxcv456",
    "type": "push",
    "amount": "50.00"
}
```

--------------------------------

### Create Transaction Examples

Source: https://developers.tabapay.com/reference/transactioncreate

Provides examples for creating transactions using different methods. Includes push and pull transactions using account IDs, card information, and RSA keys.

```json
{
  "referenceID": "1",
  "type": "push",
  "accounts": {
    "sourceAccountID": "SettlementAccountID_22",
    "destinationAccountID": "TabaPay_AccountID_22-c"
  },
  "amount": "0.25"
}
```

```json
{
  "referenceID": "1",
  "type": "pull",
  "accounts": {
    "sourceAccountID": "TabaPay_AccountID_22-c",
    "destinationAccountID": "SettlementAccountID_22"
  },
  "amount": "0.25"
}
```

```json
{
  "referenceID": "5",
  "type": "pull",
  "accounts": {
    "sourceAccount": {
      "card": {
        "accountNumber": "4111111111111111",
        "expirationDate": "202708",
        "securityCode": "232"
      },
      "owner": {
        "name": {
          "first": "Test",
          "last": "Name"
        },
        "address": {
          "line": "123 Street",
          "city": "San Francisco",
          "state": "CA",
          "zipcode": "94103",
          "country": "840"
        }
      }
    },
    "destinationAccountID": "TabaPay_AccountID_22-c"
  },
  "amount": "0.25"
}
```

```json
{
  "referenceID": "6",
  "type": "pull",
  "accounts": {
    "sourceAccount": {
      "card": {
        "keyID": "TabaPay_22_CharacterID"
      }
    }
  }
}
```

--------------------------------

### Create Transaction: Example JSON for Pull Payment

Source: https://developers.tabapay.com/reference/getting-started

This JSON object demonstrates the request body parameters for a 'pull' transaction, used for accepting payments. It includes account details, a reference ID, transaction type, and amount.

```json
{
   "accounts": {
         "sourceAccountID": "zxc4123412341234123412",
         "destinationAccountID": "1234123412341234abc412"
    },
    "referenceID": "abc123",
    "type": "pull",
    "amount": "100.00"
}
```

--------------------------------

### iOS: Setup Session with JWT

Source: https://developers.tabapay.com/docs/how-to-use-the-3ds-sdk-starter-guide

Use the SDK to authenticate the JWT and begin collecting device data. This completes the setup process and returns a consumerSessionId.

```APIDOC
## POST /websites/developers_tabapay

### Description
Use the SDK to authenticate the JWT and begin collecting device data. This completes the setup process and returns a consumerSessionId.

### Method
POST

### Endpoint
/websites/developers_tabapay

### Parameters
#### Request Body
- **jwtString** (String) - Required - The JWT obtained from the TabaPay init request.

### Request Example
```swift
let jwtString = "INSERT_THE_TABAPAY_INIT_JWT_HERE"

session.setup(jwtString: jwtString, completed: { (consumerSessionId: String) in
    // Handle successful setup
    print("Consumer Session ID: \(consumerSessionId)")
}) { (validateResponse: CardinalResponse) in
    // Handle failed setup
    print("Setup failed: \(validateResponse.errorDescription)")
}
```

### Response
#### Success Response (200)
- **consumerSessionId** (String) - The unique session ID for the consumer.

#### Response Example
```json
{
  "consumerSessionId": "some_consumer_session_id_12345"
}
```
```

--------------------------------

### PCI Compliance

Source: https://developers.tabapay.com/reference/getting-started

Information regarding PCI compliance requirements and how to achieve it.

```APIDOC
## PCI Compliance

### Description
Provides guidance on achieving and maintaining PCI compliance when using Tabapay services.

### Resource
- **PCI How to Guide**: [https://developers.tabapay.com/reference/making-sure-you-are-pci-compliant](https://developers.tabapay.com/reference/making-sure-you-are-pci-compliant)
```

--------------------------------

### Create Basic index.js File

Source: https://developers.tabapay.com/reference/integrate-apple-pay-server-setup

Creates a new index.js file and adds a simple 'Hello world!' log statement. This serves as the entry point for the Node.js application and is used to test the 'npm start' script.

```javascript
console.log('Hello world!');
```

--------------------------------

### API Request Recommendations

Source: https://developers.tabapay.com/reference/getting-started

Guidelines for request rates per second and token expiration for production environments.

```APIDOC
## API Request Recommendations

### Description
Provides recommendations for request rates per second in production and the expiration time for iFrame Tokens.

### Production Request Rate
- **Recommended**: 1 transaction per second (1 txn/second)
- **Maximum**: 3-5 transactions per second (3-5 txns/second)

### iFrame Tokens
- **Expiration**: iFrame Tokens will expire after 5 minutes.

### RetrieveAccount/Transaction by ReferenceID Usage
- **Purpose**: Should only be used in the case of a HTTP Communications Error (i.e., an AccountID or TransactionID was not returned).
- **Consequence of Misuse**: Using these endpoints when not necessary will result in a Status Code of `421` (Misdirected Request) if the Account or Transaction was created over 24 hours ago.

### Sandbox Rate Limiting
- **Note**: Rate limiting is enforced on the Sandbox Environment as it is a shared environment for development purposes.
```

--------------------------------

### Android: Initialize Cardinal and Setup Session

Source: https://developers.tabapay.com/docs/how-to-use-the-3ds-sdk-starter-guide

Initialize the Cardinal SDK and begin the process of authenticating credentials and collecting device data. Returns a consumerSessionId upon completion.

```APIDOC
## POST /websites/developers_tabapay

### Description
Initialize the Cardinal SDK and begin the process of authenticating credentials (using the JWT from the previous step) and completing the data collection process. Returns a consumerSessionId upon completion.

### Method
POST

### Endpoint
/websites/developers_tabapay

### Parameters
#### Request Body
- **jwtString** (String) - Required - The JWT obtained from the TabaPay init request.

### Request Example
```java
// Assuming 'cardinal' is an instance of Cardinal obtained via Cardinal.getInstance()
String jwtString = "INSERT_THE_TABAPAY_INIT_JWT_HERE";

cardinal.init(this, jwtString, new CardinalInitializationCallback() {
    @Override
    public void onInitialized() {
        // Initialization successful
        Log.d("TabaPay", "Cardinal initialized successfully.");
    }

    @Override
    public void onSetupCompleted(String consumerSessionId) {
        // Setup completed, proceed with checkout
        Log.d("TabaPay", "Setup completed. Consumer Session ID: " + consumerSessionId);
        // Use consumerSessionId for 3D Secure Lookup
    }

    @Override
    public void onError(CardinalResponse cardinalResponse) {
        // Handle initialization or setup errors
        Log.e("TabaPay", "Error during Cardinal initialization/setup: " + cardinalResponse.getErrorMessage());
    }
});
```

### Response
#### Success Response (200)
- **consumerSessionId** (String) - The unique session ID for the consumer.

#### Response Example
```json
{
  "consumerSessionId": "some_consumer_session_id_12345"
}
```
```

--------------------------------

### API Formatting Rules

Source: https://developers.tabapay.com/reference/getting-started

Guidelines for formatting data sent to Tabapay APIs to avoid errors and ensure compatibility.

```APIDOC
## API Formatting Rules

### Description
Details the recommended and restricted character sets for data fields in API requests to prevent errors and ensure compatibility with various systems.

### General Recommendation
- **Character Set**: Use only the Base64 URL-Safe Character Set for all data.
- **Reference**: Refer to [Data](https://developers.tabapay.com/reference/data) for detailed formatting rules.

### Restricted Characters
- `,` Comma
- `"` Double Quotes
- `~` Tilde
- `^` Caret
- `|` Pipe

### Free Form Fields (Name, Address, etc.)

#### Formatting Rules:
- **Prohibited Content**: No SQL statements or code.
- **Prohibited Characters**: `; | ^ ~ , "`
- **Consecutive Characters**: No consecutive periods (`..`).

#### Recommended Character Set (URL Safe Base 64):
- **Includes**: `A-Z`, `a-z`, `0-9`, `-`, `_`, `[space]`

#### Consequences of Deviation:
- **Network Rejection**: Some networks may reject transactions based on characters in fields like `city` (e.g., `T√ourin`).
- **WAF Blocking**: Consecutive characters not in the URL-Safe Base 64 set may be blocked by the Web Application Firewall (WAF) if they appear suspicious.
```

--------------------------------

### Configurations for Value Added Services

Source: https://developers.tabapay.com/reference/getting-started

Details on configuring value-added services such as 3DS, Apple Pay, Google Pay, and TabaPay Shield.

```APIDOC
## Configurations for Value Added Services

### Description
Information on configuring various value-added services essential for your business case before launch. Contacting Tabapay support is required to enable these services.

### Services
- **3DS**: [https://developers.tabapay.com/docs/overview-of-3ds](https://developers.tabapay.com/docs/overview-of-3ds)
- **Apple Pay**: [https://developers.tabapay.com/docs/apple-pay](https://developers.tabapay.com/docs/apple-pay)
- **Google Pay**: [https://developers.tabapay.com/docs/google-pay](https://developers.tabapay.com/docs/google-pay)
- **TabaPay Shield**: [https://developers.tabapay.com/docs/overview-of-tabapay-shield](https://developers.tabapay.com/docs/overview-of-tabapay-shield)

### Configuration Support
- **Contact**: Email [help@tabapay.com](mailto:help@tabapay.com) for assistance with enabling services and ensuring correct configurations on both your side and Tabapay's side.
- **Benefits**: Services like TabaPay Shield help eliminate fraud and enable L2 and L3 interchange benefits.
```

--------------------------------

### iOS SDK Session Setup with JWT

Source: https://developers.tabapay.com/reference/how-to-use-the-3ds-sdk-starter-guide

This Swift code snippet shows how to use the JWT obtained from the initialization step to set up the Cardinal session for authenticating credentials and collecting device data.

```APIDOC
## iOS SDK Session Setup with JWT

### Description
This code snippet demonstrates how to initiate the session setup process in the iOS SDK using the JWT obtained from the TabaPay initialization step. This process authenticates credentials and begins collecting device data.

### Method
Swift function call

### Endpoint
N/A (Client-side SDK function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```swift
let jwtString = "INSERT_THE_TABAPAY_INIT_JWT_HERE"
// Assuming 'session' is an instance of CardinalSession configured previously
session.setup(jwtString, :)
```

### Response
#### Success Response (200)
* **consumerSessionId** (string) - Returned in the `completed` callback. This ID is needed for the 3D Secure Lookup.

#### Response Example
```json
{
  "consumerSessionId": "some-unique-session-id"
}
```
```

--------------------------------

### Browser SDK Integration

Source: https://developers.tabapay.com/reference/browser-sdk-reference

This section provides information on how to get started with the TabaPay Browser SDK, including the sandbox URL and the importance of testing configurations.

```APIDOC
## Browser SDK Integration

### Description
This section guides you on integrating the TabaPay Browser SDK to accept card payments. It includes the necessary sandbox URL and emphasizes testing configurations.

### Getting Started
To begin integrating the Browser SDK, use the provided sandbox URL along with your ClientID. This setup enables calls to various customization keys for the Custom iFrame.

### Sandbox URL
```javascript
https://iframes.sandbox.tabapay.net/TabaPaySDK.js
```

### Testing Configurations
It is recommended for clients to test their desired configurations to understand the behavior of each key and its impact on the payment experience.
```

--------------------------------

### Initialize npm Package

Source: https://developers.tabapay.com/reference/integrate-apple-pay-server-setup

Initializes a new or existing npm package in the current directory. This command generates a package.json file, which stores metadata and dependency information for the project. Users will be prompted to provide details like package name, version, and entry point.

```bash
npm init
```

--------------------------------

### Retrieve Account via cURL

Source: https://developers.tabapay.com/reference/retrieve-account-by-referenceid

Demonstrates how to retrieve account details using a cURL command. This example shows the GET request structure, including the URL and necessary headers.

```shell
curl --request GET \
     --url https://fqdn/:PORT/Version/clients//accounts/ \
     --header 'accept: application/json'
```

--------------------------------

### Install Apache Web Server on Ubuntu

Source: https://developers.tabapay.com/reference/integrate-apple-pay-server-setup

Install the Apache2 package, which is a widely used web server software that enables the delivery of web content over the internet.

```bash
sudo apt install apache2
```

--------------------------------

### Retrieve Transaction using Node.js

Source: https://developers.tabapay.com/reference/retrieve-transaction-by-referenceid

Example of retrieving transaction details using Node.js. This code makes a GET request to the TabaPay API and handles the JSON response.

```javascript
const fetch = require('node-fetch');

const options = {
  method: 'GET',
  headers: {
    'accept': 'application/json'
  }
};

fetch('https://{FQDN}:{PORT}/v1/clients/{ClientID}/transactions/{TransactionID}', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

--------------------------------

### Install Node.js using NVM

Source: https://developers.tabapay.com/reference/integrate-apple-pay-server-setup

Installs Node.js using the Node Version Manager (nvm). This involves downloading and executing the nvm installation script, sourcing the .bashrc file to enable nvm, listing available Node.js versions, and installing a specific version (e.g., v16.17.0).

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
source ~/.bashrc
nvm list-remote
nvm install v16.17.0
nvm list
```

--------------------------------

### Complementary APIs Overview

Source: https://developers.tabapay.com/reference/getting-started

TabaPay offers several complementary APIs to support the unified payment flow, including Card, Bank, Account, 3D Secure, and Sub-client APIs.

```APIDOC
## Complementary APIs

### Card API
- **Description**: Used for Address Verification System (AVS), checking eligibility for push/pull, and retrieving BIN attributes.
- **Reference**: [Card API](https://developers.tabapay.com/reference/cardquery)

### Bank API
- **Description**: Retrieves attributes of a bank, such as Real-Time Payments (RTP) eligibility.
- **Reference**: [Bank API](https://developers.tabapay.com/reference/bankquery)

### Account API
- **Description**: Stores and manages cards with TabaPay. Outputs a TabaPay Token (account ID) that can be used in lieu of a payment instrument.
- **Reference**: [Account API](https://developers.tabapay.com/reference/accountcreate)

### 3D Secure API
- **Description**: Allows for performing 3D Secure authentication.
- **Reference**: [3D Secure API](https://developers.tabapay.com/reference/3dsinit)

### Sub-client API
- **Description**: Enables automatic onboarding of sub-clients, setting their fees, and configuration.
- **Reference**: [Sub-client API](https://developers.tabapay.com/reference/createsubclient)
```

--------------------------------

### Setup Session - Android (Java)

Source: https://developers.tabapay.com/docs/how-to-use-the-3ds-sdk-starter-guide

Initializes the TabaPay session setup on Android using Java. This method requires a server JWT and implements a CardinalInitService to handle the completion of the setup process, providing a consumerSessionId, or reporting validation errors.

```java
cardinal = Cardinal.getInstance();
String serverJwt = "INSERT_THE_TABAPAY_INIT_JWT_HERE";
cardinal.init(serverJwt ,
new CardinalInitService() {
    /**
    * You may have your Submit button disabled on page load. Once you are set up
    * for CCA, you may then enable it. This will prevent users from submitting
    * their order before CCA is ready.
    */
    @Override
    public void onSetupCompleted(String consumerSessionId) {
 
    }
    /**
    * If there was an error with set up, Cardinal will call this function with
    * validate response and empty serverJWT
    * @param validateResponse
    * @param serverJwt will be an empty
    */
    @Override
    public void onValidated(ValidateResponse validateResponse, String serverJwt) {
 
    }
});
```

--------------------------------

### Begin Apple Pay Session

Source: https://developers.tabapay.com/reference/integrate-apple-pay-decrypt-the-apple-pay-payload-frontend-backend-setup

Initiates the Apple Pay SDK session, starting the payment process. This is typically the final step after all event handlers and configurations are set up.

```javascript
session.begin();
```