@astropay/payments-lib
Version:
Official AstroPay payments library for web and mobile.
278 lines (213 loc) • 9.34 kB
Markdown
<div align="center">
<a href="http://www.astropay.com">
</a>
</div>
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.
<div align="center">
[](https://www.npmjs.com/package/@astropay/payments-lib)
[](https://www.npmjs.com/package/@astropay/payments-lib)
</div>
## 🚀 Quick Links
- 🧪 [Live Demo](https://demo.astropay.com)
- 📘 [Full Documentation](https://developers.astropay.com/docs/accept-astropay/checkout/overview)
## 📋 Table of Contents
- [🚀 Quick Links](#-quick-links)
- [📋 Table of Contents](#-table-of-contents)
- [📦 Installation](#-installation)
- [Prerequisites](#prerequisites)
- [DOM Requirements](#dom-requirements)
- [NPM](#npm)
- [Yarn](#yarn)
- [🚀 Basic Usage](#-basic-usage)
- [🧩 Components](#-components)
- [AstroPayFullCheckout](#astropayfullcheckout)
- [Props](#props)
- [Example](#example)
- [AstroPayPayment](#astropaypayment)
- [Props](#props-1)
- [Example](#example-1)
- [🎨 Styling \& Theming](#-styling--theming)
- [Available Themes](#available-themes)
- [Custom Styling](#custom-styling)
- [Available Style Properties](#available-style-properties)
- [🌐 Internationalization](#-internationalization)
- [Available Languages](#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:
```html
<div id="payment-container"></div>
```
The library will render the payment interface inside this container element.
### NPM
```bash
npm install @astropay/payments-lib
```
### Yarn
```bash
yarn add @astropay/payments-lib
```
## 🚀 Basic Usage
Initialize the library with your API token and optional configuration:
```typescript
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
```typescript
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
```typescript
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:
```typescript
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:
```typescript
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](https://developers.astropay.com/docs/accept-astropay/checkout/payment-lib-web/styling-theming#custom-styling) |
## 🌐 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:
```typescript
AstroPayCore.init('app-id', {
language: 'es',
});
```