AstroPay's official frontend library that allows you to easily embed customizable and secure payment components into your website or e-commerce platform. It supports seamless international transactions, theming, localization, and real-time payment processing — all with minimal setup.

🚀 Quick Links

• 🧪 Live Demo
• 📘 Full Documentation

📋 Table of Contents

• 🚀 Quick Links
• 📋 Table of Contents
• 📦 Installation
  • Prerequisites
    • DOM Requirements
  • NPM
  • Yarn
• 🚀 Basic Usage
• 🧩 Components
  • AstroPayFullCheckout
    • Props
    • Example
  • AstroPayPayment
    • Props
    • Example
• 🎨 Styling & Theming
  • Available Themes
  • Custom Styling
    • Available Style Properties
• 🌐 Internationalization
  • Available Languages

📦 Installation

Prerequisites

DOM Requirements

Before using the AstroPay Payment components, ensure your HTML document includes container elements where the components will be rendered. For example, to use the basic payment component, you need to have an element with id="payment-container" in your DOM:

<div id="payment-container"></div>

The library will render the payment interface inside this container element.

NPM

npm install @astropay/payments-lib

Yarn

yarn add @astropay/payments-lib

🚀 Basic Usage

Initialize the library with your API token and optional configuration:

import { AstroPayCore, AstroPayFullCheckout } from '@astropay/payments-lib';

// Initialize the library
AstroPayCore.init('app-id', {
  environment: 'production', // or 'sandbox'
  theme: 'light', // or 'dark'
  language: 'en', // or 'es', 'pt'
  currencyMode: 'iso', // or 'symbol'
  tracking: true // or false to disable tracking
});

// Use the payment component in your application
const paymentComponent = new AstroPayFullCheckout({
  amount: 100,
  currency: 'USD',
  country: 'BR',
  onSuccess: () => console.log('Payment successful'),
  onError: () => console.error('Payment failed')
});

// Render the component into a container element
const paymentElement = document.getElementById('payment-container');
paymentComponent.render(paymentElement);

// Later, when you want to clean up
// paymentComponent.destroy();

🧩 Components

AstroPayFullCheckout

The main component for rendering a payment interface.

Props

| Prop | Type | Required | Description | | --------------- | ---------- | -------- | ------------------------------------------------------------ | | amount | number | Yes | The payment amount | | currency | string | Yes | The currency code (e.g., 'USD') | | country | string | Yes | The country code (e.g., 'BR', 'US') | | showTitle | boolean | No | Whether to show the component title (defaults to true) | | showDescription | boolean | No | Whether to show the payment description (defaults to true) | | cardConfig | object | No | Configuration for card module. | | cardConfig.showPaymentSummary | boolean | No | Whether to display the summary of the payment (defaults to true) | | cardConfig.expirationDateFormat | MM/YYYY or MM/YY | No | Mask format for expiration date (defaults to MM/YY) | | onSuccess | () => void | No | Callback function called when payment is successful | | onError | () => void | No | Callback function called when payment fails |

Example

import { AstroPayFullCheckout } from '@astropay/payments-lib';

const fullCheckoutComponent = new AstroPayFullCheckout({
  amount: 100,
  currency: 'USD',
  country: 'US',
  // Optional props
  showTitle: true,
  showDescription: true,
  cardConfig: {
    showPaymentSummary: true,
    expirationDateFormat: 'MM/YY',
  },
  onSuccess: () => {
    console.log('Payment was successful');
    // Handle successful payment, e.g., redirect to success page
  },
  onError: () => {
    console.error('Payment failed');
    // Handle payment failure
  }
});

// Render the component into a container element
const container = document.getElementById('payment-container');
fullCheckoutComponent.render(container);

// Later, when you want to clean up (e.g., on page navigation)
// fullCheckoutComponent.destroy();

AstroPayPayment

A streamlined payment component focused on AstroPay's native payment method.

Props

| Prop | Type | Required | Description | | --------- | ---------- | -------- | --------------------------------------------------- | | amount | number | Yes | The payment amount | | currency | string | Yes | The currency code (e.g., 'USD') | | country | string | Yes | The country code (e.g., 'BR', 'US') | | onSuccess | () => void | No | Callback function called when payment is successful | | onError | () => void | No | Callback function called when payment fails |

Example

import { AstroPayPayment } from '@astropay/payments-lib';

const paymentComponent = new AstroPayPayment({
  amount: 100,
  currency: 'USD',
  country: 'BR',
  onSuccess: () => {
    console.log('Payment was successful');
    // Handle successful payment, e.g., redirect to success page
  },
  onError: () => {
    console.error('Payment failed');
    // Handle payment failure
  }
});

// Render the component into a container element
const container = document.getElementById('payment-container');
paymentComponent.render(container);

// Later, when you want to clean up (e.g., on page navigation)
// paymentComponent.destroy();

🎨 Styling & Theming

The library supports customizable theming through the initialization configuration.

Available Themes

The library comes with two built-in themes:

• light (default)
• dark

You can specify the theme during initialization:

AstroPayCore.init('app-id', {
  theme: 'dark',
  environment: 'production', // or 'sandbox'
  language: 'en',
  currencyMode: 'iso', // or 'symbol'
});

Custom Styling

You can customize the styling by providing a styles object in the initialization configuration:

AstroPayCore.init('app-id', {
  styles: {
    backgroundColor: '#FFFFFF',
    fontFamily: 'Arial, sans-serif',
    textColor: '#000000',
    primaryColor: '#FF5500',
    textPrimaryColor: '#333333',
    secondaryColor: '#00AAFF',
    textSecondaryColor: '#666666',
    width: 500,
    paddingWrapper: 20,
    borderRadiusWrapper: 8,
  },
});

Available Style Properties

| Property | Type | Description | | ------------------- | ------------- | ---------------------------------- | | backgroundColor | string | Background color | | fontFamily | string | Font family | | textColor | string | Text color | | primaryColor | string | Primary brand color | | textPrimaryColor | string | Primary text color | | secondaryColor | string | Secondary brand color | | textSecondaryColor | string | Secondary text color | | width | string/number | Component width in pixels | | paddingWrapper | string/number | Padding for component wrapper | | borderRadiusWrapper | string/number | Border radius for component wrapper| | ...otherProps | — | For additional styling options, see the full style API docs |

🌐 Internationalization

The library supports multiple languages through the i18next internationalization framework.

Available Languages

• English (en) - Default
• Spanish (es)
• Portuguese (pt)

You can specify the language during initialization:

AstroPayCore.init('app-id', {
  language: 'es',
});