API Reference

This page provides a detailed reference for all API endpoints available in the Hosted Components project. These endpoints support various payment-related operations, from token generation to payment method management.

Authentication

Most API endpoints require authentication using JWT tokens. Include the token in your request headers:

Authorization: Bearer <your_jwt_token>

Endpoints

Create JWT Token

Creates an authentication token with appropriate scopes for payment operations.

Endpoint: /api/createJWTToken

Method: POST

Request Body: None required (credentials handled by server)

Response:

{
	"access_token": "string"
}

Create Payment Method Token for Card

Creates a payment method token for a credit/debit card.

Endpoint: /api/createPaymentMethodToken/card

Method: POST

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "accountHolderName": "string",
  "accountNumber": "string",
  "countryCode": "string",
  "expiryDate": "MM/YY",
  "termAndConditionAgreed": boolean
}

Response:

{
  "data": {
    // Vault data including payment method token
  },
  "status": number
}

Create Payment Method

Associates a payment method token with a customer.

Endpoint: /api/createPaymentMethod

Method: POST

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "customerId": "string",
  "paymentMethodToken": "string",
  "primary": boolean
}

Response:

{
  "data": {
    // Payment method details
  },
  "status": number
}

Get Accepted Payment Methods

Retrieves payment methods accepted by a merchant.

Endpoint: /api/getAcceptedPaymentMethods

Method: GET

Headers:

Authorization: Bearer <jwt_token>

Query Parameters:

• merchantId (optional) - The merchant ID to fetch payment methods for. If not provided, the API will automatically extract it from the JWT token if it contains a merchant_id claim.

Response:

{
  "acceptedPaymentMethods": ["VISA", "MASTERCARD", ...]
}

Notes:

• The merchant ID can be provided either through the query parameter or it will be automatically extracted from the JWT token
• Token must have create_payment_method or hosted_payment scope

Get Fee Pricing

Retrieves fee pricing information for a merchant.

Endpoint: /api/getFeePricing

Method: GET

Headers:

Authorization: Bearer <jwt_token>

Query Parameters:

• merchantId (optional) - The merchant ID to fetch fee pricing for. If not provided, the API will automatically extract it from the JWT token if it contains a merchant_id claim.

Response:

{
  "data": {
    // Fee pricing details
  },
  "status": number
}

Get Merchant Details

Retrieves basic details about a merchant.

Endpoint: /api/getMerchantDetails

Method: GET

Headers:

Authorization: Bearer <jwt_token>

Query Parameters:

• merchantId (optional) - The merchant ID to fetch details for. If not provided, the API will automatically extract it from the JWT token if it contains a merchant_id claim.

Response:

{
  "data": {
    "merchantId": "string",
    "merchantName": "string",
    "legalName": "string",
    "status": "string"
  },
  "status": number
}

Mock Endpoint

A test endpoint that returns mock payment method data.

Endpoint: /api/mockendpoint

Method: GET

Response:

{
  "message": "string",
  "data": [
    {
      "id": number,
      "type": "string",
      "name": "string",
      "displayName": "string",
      "isActive": boolean
    }
  ]
}

Search

A utility endpoint for documentation search functionality.

Endpoint: /api/search

Method: GET

Utility Functions

apiRequest

The project provides a utility function for making API requests with proper error handling.

interface ApiRequestConfig {
	url: string;
	method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
	token?: string;
	body?: Record<string, unknown>;
}

interface ApiResponse<T> {
	data: T | null;
	status: number;
}

async function apiRequest<T>(config: ApiRequestConfig): Promise<ApiResponse<T>>;

Example Usage:

const { data, status } = await apiRequest({
	url: 'https://api.example.com/data',
	method: 'POST',
	token: 'your-jwt-token',
	body: { key: 'value' },
});

Error Handling

API responses follow a consistent error format:

{
	"message": "Error description",
	"errorType": "ERROR_CODE",
	"error": {} // Optional additional error details
}

Common error types include:

• INVALID_TOKEN - Authentication issues
• INVALID_SCOPE - Token lacks required permissions
• MISSING_MERCHANT_ID - Required merchant ID not provided
• API_ERROR - Errors from downstream APIs
• INTERNAL_SERVER_ERROR - Unexpected server errors