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 and enhanced logging capabilities.

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' },
});

Enhanced Features:

Automatic Logging: All API requests and responses are logged with structured DatadogLogger
Token Security: Tokens are automatically masked in logs for security
Error Tracking: Detailed error information is captured and logged
Performance Monitoring: Request duration and response times are tracked

Logging and Monitoring

Enhanced API Logging

All API endpoints now include comprehensive logging with the following features:

Request Logging

Every API request is automatically logged with:

Request Details: URL, method, headers, and body
Security: Tokens are automatically masked for security
Context: Merchant ID, country code, and other contextual information
Payment Stages: Tracking of different payment processing stages

Response Logging

API responses are logged with:

Response Status: HTTP status codes and response data
Performance: Response time and payload size
Error Details: Comprehensive error information when requests fail

Payment Stage Tracking

API calls are categorized by payment processing stages:

// Payment stages tracked in API logging
const paymentStages = {
	initialization: 'initialization',
	payment_method_selection: 'payment_method_selection',
	form_validation: 'form_validation',
	payment_token_creation: 'payment_token_creation',
	customer_linking: 'customer_linking',
	payment_token_creation_failed: 'payment_token_creation_failed',
};

Example Log Structure

{
	"message": "API Request Details",
	"level": "api_request",
	"url": "/api/createPaymentMethodToken/card",
	"method": "POST",
	"headers": {
		"Authorization": "Bearer eyJhbG************ssw5c",
		"Content-Type": "application/json"
	},
	"body": "{\"accountHolderName\":\"John Doe\",\"countryCode\":\"AU\"}",
	"paymentStage": "payment_token_creation",
	"merchantId": "merchant-123",
	"countryCode": "AU",
	"pageType": "HPP 2.0",
	"timestamp": "2024-01-15T10:30:00.000Z"
}

Monitoring and Debugging

The enhanced logging system provides:

Real-time Monitoring: Track API performance and errors in real-time
Security Auditing: Monitor authentication and authorization patterns
Payment Flow Tracking: Follow the complete payment journey
Error Investigation: Detailed error context for troubleshooting
Performance Analysis: Identify bottlenecks and optimization opportunities

Environment-Specific Behavior

Production Environment:

Sensitive data is automatically filtered from logs
Request/response bodies are sanitized
Debug information is disabled
Enhanced security measures are active

Development/Staging Environment:

Full request/response logging available
Debug information included
Sensitive data can be logged with explicit methods
Enhanced debugging capabilities

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

Enhanced Error Logging

All errors are now logged with comprehensive context:

DatadogLogger.error(
	'API Request Error',
	error,
	{
		url: '/api/endpoint',
		method: 'POST',
		statusCode: 500,
		errorType: 'API_ERROR',
		paymentStage: 'payment_token_creation',
		merchantId: 'merchant-123',
	},
	token,
	context
);

This provides detailed information for debugging and monitoring API issues across different environments and payment stages.

API Reference

On this page