Skip to content

API.md

Latest commit

 

History

History
483 lines (351 loc) · 10.4 KB

API.md

File metadata and controls

483 lines (351 loc) · 10.4 KB

RaiAccept JavaScript SDK - API Documentation

Table of Contents

Installation

npm install @smartbase-js/raiaccept-api-client

Quick Start

import { RaiAcceptService, HttpClient } from '@smartbase-js/raiaccept-api-client';

// Initialize client
const httpClient = new HttpClient();
const service = new RaiAcceptService(httpClient, cert, key);

// Authenticate
const authResult = await service.retrieveAccessTokenWithCredentials(
  'username',
  'password'
);
const accessToken = authResult?.accessToken;

// Step 1: Create order entry
const orderResponse = await service.createOrderEntry(accessToken, orderRequest);
const orderIdentification = orderResponse.object.getOrderIdentification();

// Step 2: Create payment session for the order
const paymentSessionResponse = await service.createPaymentSession(
  accessToken,
  orderRequest,
  orderIdentification
);
const paymentRedirectURL = paymentSessionResponse.object?.paymentRedirectURL;

API Client

RaiAcceptAPIApi

Main API client for interacting with RaiAccept services.

Constructor

const apiClient = new RaiAcceptAPIApi(httpClient, cert, key);

Parameters:

  • httpClient (HttpClient): HTTP client instance for making requests
  • cert (string | Buffer): Client certificate for mTLS
  • key (string | Buffer): Client private key for mTLS

Methods

token(username, password)

Authenticate with username and password.

Parameters:

  • username (string): Username
  • password (string): Password

Returns: Promise<ApiResponse<AuthApiLoginOutput>> - Authentication response with access token, refresh token, and expiration times

Example:

const response = await apiClient.token('username', 'password');
const authResult = response.object;
const accessToken = authResult?.accessToken;
const refreshToken = authResult?.refreshToken;
const accessTokenExpiresIn = authResult?.accessTokenExpiresIn;
const refreshTokenExpiresIn = authResult?.refreshTokenExpiresIn;
tokenLogout(token)

Logout with refresh token. Uses AUTH_URL; cert and key not required.

Parameters:

  • token (string): Refresh token to logout

Returns: Promise<boolean> - True if logout successful (HTTP 200), false otherwise

Example:

const success = await apiClient.tokenLogout(refreshToken);
createOrderEntry(accessToken, createOrderRequest)

Create a new order entry.

Parameters:

  • accessToken (string): Bearer token for authentication
  • createOrderRequest (Object): Order request object

Returns: Promise<Object> - Order creation response

Example:

const orderRequest = {
  invoice: {
    amount: 100.00,
    currency: 'EUR',
    description: 'Payment description',
    merchantOrderReference: 'ORDER-123',
    items: [...]
  },
  urls: {
    successUrl: 'https://example.com/success',
    failUrl: 'https://example.com/fail',
    cancelUrl: 'https://example.com/cancel'
  },
  consumer: { ... },
  paymentMethodPreference: 'CARD',
  linkId: 'unique-link-id'
};

// Step 1: Create order entry
const orderResponse = await apiClient.createOrderEntry(accessToken, orderRequest);
const orderIdentification = orderResponse.object.getOrderIdentification();

// Step 2: Create payment session for the order (see createPaymentSession method below)
createPaymentSession(accessToken, paymentSessionRequest, externalOrderId)

Create payment session for an existing order. Note: This must be called after createOrderEntry to complete the payment flow.

Parameters:

  • accessToken (string): Bearer token
  • paymentSessionRequest (Object): Payment session configuration
  • externalOrderId (string): External order identifier

Returns: Promise<Object> - Payment session response with checkout URL

Example:

// After creating an order entry (see createOrderEntry example above)
const paymentSessionResponse = await apiClient.createPaymentSession(
  accessToken,
  orderRequest, // Use the same request object from createOrderEntry
  orderIdentification // The order ID from createOrderEntry response
);

const paymentRedirectURL = paymentSessionResponse.object?.paymentRedirectURL;
const sessionId = paymentSessionResponse.object?.sessionId;

console.log('Redirect customer to:', paymentRedirectURL);
getOrderDetails(accessToken, orderId)

Retrieve details for a specific order.

Parameters:

  • accessToken (string): Bearer token
  • orderId (string): Order identifier

Returns: Promise<Object> - Order details

Example:

const response = await apiClient.getOrderDetails(accessToken, 'order-123');
const status = response.object.getStatus();
getOrderTransactions(accessToken, orderId)

Get all transactions for an order.

Parameters:

  • accessToken (string): Bearer token
  • orderId (string): Order identifier

Returns: Promise<Object> - List of transactions

Example:

const response = await apiClient.getOrderTransactions(accessToken, 'order-123');
const transactions = response.object.transactions;
getTransactionDetails(accessToken, orderId, transactionId)

Get details for a specific transaction.

Parameters:

  • accessToken (string): Bearer token
  • orderId (string): Order identifier
  • transactionId (string): Transaction identifier

Returns: Promise<Object> - Transaction details

refund(accessToken, orderId, transactionId, refundRequest)

Process a refund for a transaction.

Parameters:

  • accessToken (string): Bearer token
  • orderId (string): Order identifier
  • transactionId (string): Transaction identifier
  • refundRequest (Object): Refund details

Returns: Promise<Object> - Refund response

Example:

const refundRequest = {
  amount: 50.00,
  currency: 'EUR'
};

const response = await apiClient.refund(
  accessToken,
  'order-123',
  'txn-456',
  refundRequest
);

Service Methods

RaiAcceptService

Status Helpers

getPaidStatuses()

Returns array of statuses indicating successful payment: ['PAID', 'SUCCESS']

getFailedStatuses()

Returns array of statuses indicating failed payment: ['FAILED']

getCancelledStatuses()

Returns array of statuses indicating cancelled payment: ['CANCELED', 'ABANDONED']

getRejectedStatuses()

Returns array of all rejected statuses: ['FAILED', 'CANCELED', 'ABANDONED']

Utility Functions

transliterate(string)

Transliterate non-Latin characters to Latin equivalents.

Example:

const result = RaiAcceptService.transliterate('Γεια σου');
// Result: "Geia sou"
transliterateAndLimitLength(string, limit = 127)

Transliterate and limit string length.

Example:

const result = RaiAcceptService.transliterateAndLimitLength('Very long text...', 50);
cleanPhoneNumber(phoneNumber)

Clean and format phone number.

Example:

const cleaned = RaiAcceptService.cleanPhoneNumber('+1 (234) 567-8900');
// Result: "+12345678900"
getCountryIso3(countryCode)

Convert 2-letter country code to 3-letter ISO code.

Example:

const iso3 = RaiAcceptService.getCountryIso3('US');
// Result: "USA"

Models

All models support fromObject(data) static method for deserialization.

Address

{
  addressStreet1: string,
  addressStreet2: string,
  addressStreet3: string,
  city: string,
  country: string,
  firstName: string,
  lastName: string,
  postalCode: string,
  state: string
}

Consumer

{
  email: string,
  firstName: string,
  ipAddress: string,
  lastName: string,
  mobilePhone: string,
  phone: string,
  workPhone: string
}

Invoice

{
  amount: number,
  currency: string,
  description: string,
  items: InvoiceItem[],
  merchantOrderReference: string // must be unique for merchant
}

InvoiceItem

{
  description: string,
  numberOfItems: number,
  price: number
}

Urls

{
  successUrl: string,
  failUrl: string,
  cancelUrl: string,
  notificationUrl: string|null
}

Transaction

{
  transactionId: string,
  transactionAmount: number,
  transactionCurrency: string,
  isProduction: boolean,
  transactionType: string, // 'PURCHASE' or 'REFUND'
  paymentMethod: string,
  status: string,
  statusCode: string,
  statusMessage: string,
  createdOn: string,
  updatedOn: string
}

Utilities

ObjectSerializer

Utility class for serialization and deserialization.

Methods

  • sanitizeForSerialization(data) - Prepare data for API transmission
  • toPathValue(value) - URL-encode value for path parameters
  • toString(value) - Convert value to string
  • deserialize(data, modelClass) - Deserialize JSON to model instance

Error Handling

ApiException

Thrown when API requests fail.

Properties:

  • message (string): Error message
  • statusCode (number): HTTP status code
  • headers (Object): Response headers
  • body (string): Response body
  • responseObject (Object): Parsed response object

Example:

try {
  // Step 1: Create order entry
  const orderResponse = await apiClient.createOrderEntry(accessToken, orderRequest);
  const orderIdentification = orderResponse.object.getOrderIdentification();
  
  // Step 2: Create payment session
  const paymentSessionResponse = await apiClient.createPaymentSession(
    accessToken,
    orderRequest,
    orderIdentification
  );
} catch (error) {
  if (error instanceof ApiException) {
    console.error('API Error:', error.statusCode, error.message);
    console.error('Response:', error.body);
  }
}

InvalidArgumentException

Thrown when required parameters are missing or invalid.

Example:

try {
  const response = await apiClient.getOrderDetails(null, 'order-123');
} catch (error) {
  if (error instanceof InvalidArgumentException) {
    console.error('Invalid argument:', error.message);
  }
}

Constants

Accepted Languages

RaiAcceptAPIApi.ACCEPTED_LANGUAGES
// ['en', 'de', 'fr', 'cs', 'sk', 'sr', 'al', 'ro', 'pl', 'hr']

Complete Example

See examples/basic-usage.js for a complete working example.