@astropay/astropay-sdk NPM

Table of Contents
Getting Started - Prerequisites - Installation
Usage - Platform Init - Event Listeners - Method Call
Supported languages
Updrading - V4 - Latest - V3 - V2
Support
License

Getting Started

Prerequisites

Node.js v14 or higher.

Installation

Using your favorite package manager, install @astropay/astropay-sdk package.

NPM:

npm install --save @astropay/astropay-sdk

YARN:

yarn add @astropay/astropay-sdk

Usage

Platform Init

SDK config parameters

To correctly configure the SDK, the init method needs to receive the APP_ID and the configuration object with the properties described below:

Property	Type	Default value	Description
environment	`'sandbox'` \| `'production'` \| `undefined`	`'production'`	Enviroment to use.
language	Supported languages \| undefined	`'en'`	The language set on the init object has priority over the language of the URL property on the `ASTROPAY_RESPONSE`
logger	Instance of Logger \| `undefined`	`undefined`	Use to console log actions inside the SDK

If the language property isn't set on the init, the SDK will try to use the language query parameter on the URL of the ASTROPAY_RESPONSE. If both are not set, the SDK will use the default language: english

Code snippet:

import AstropaySDK, { ClientConfiguration, ConsoleLogger, DepositStatus } from  '@astropay/astropay-sdk';

// SDK Config
const config: ClientConfiguration = {
	environment: 'production',
	language: 'en',
	logger: new ConsoleLogger(),
};

// SDK Init
AstroPaySDK.init(APP_ID, config);

Event Listeners

Set up event listeners that receives a callback funcion as a parameter.

// SDK Event Listeners
const eventListening = AstroPaySDK.getEventListener('deposit');
eventListening.on('close', (data) => {
	console.log('data on close event', data);
	}
);

Method Call

Method Parameters

When calling one of the product methods (Deposit | Cashout | Onboarding) to effectively open the SDK, the espected parameters are the ASTROPAY_RESPONSE and the configUI properties to manipulate the UI according to your needs:

Property	Type	Default value	Description
ASTROPAY_RESPONSE	Object	not applicable: mandatory to send on the call	The init object provided by AstroPay services on your call. Check the examples on the Usage section.

Property	Type	Default value	Description
backdrop	`'static'` \| `'active'`	`'static'`	If you want the *AstroPay SDK* to be closed when the user clicks on the Backdrop (Outside the content) use `active` If `static`, the backdrop element will not close the SDK modal when the user clicks outside content.
zIndex	string	`'auto'`	The z-index property specifies the stack order of the popup.Greater stack order is always in front of an element with a lower stack order.

Notice that the ASTROPAY_RESPONSE should be configured with real values for the product calls (Deposit | Cashout | Onboarding). Be careful not to send an incorrect value on these properties

Deposit

// Non mandatory object
const configUI = {backdrop:'active', zIndex:'auto'}

// Mandatory object
const ASTROPAY_RESPONSE = {  
	"merchant_deposit_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
	"deposit_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"status":  "PENDING",  
	"url":  "https://onetouch-sandbox.astropay.com/deposit/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"type":  "default"  
};

// Show the DEPOSIT client
AstropaySDK.deposit(ASTROPAY_RESPONSE);

Cashout

const ASTROPAY_RESPONSE = {  
	"merchant_cashout_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
	"cashout_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"status":  "PENDING",  
	"url":  "https://onetouch-sandbox.astropay.com/cashout/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe"
};

// Show the CASHOUT client
AstropaySDK.cashout(ASTROPAY_RESPONSE);

Onboarding

const ASTROPAY_RESPONSE = {  
	"platform_merchant_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  
	"merchant_name": "Merchant"
	"onboarding_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"status":  "PENDING",  
	"url":  "https://onetouch-sandbox.astropay.com/onboarding/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",
};

// Show the ONBOARDING client
AstropaySDK.onboarding(ASTROPAY_RESPONSE);

Payment

This method receives the AstroPay Response and returns a Promise that will be resolve to an object with the payment data to be display in your site as you please.

//Method Response 
AstropaySDK.payment(AstropayResponse): Promise<PaymentData>

Method response interface

interface PaymentData {
  amount: number;
  currency: string;
  status: string;
  payment_type: string;
  data: {
		txt_qr: string;
		image: string;
	} & Record<string, any>
}

The returned object fields:

amount: Amount of the payment
currency: Currency of the payment
status: Status of the payment
payment_type: A string define by the method selected for this payment
data: Object containing the data of the payment with a key - value format

Notice that this method is only compatible with type: "gateway" deposits

Important
Based on the payment_type field the data object could include specific fields:

Payment Type	Data	Value	Description
PIX	Object	txt_qr: string,image: string	The qr code for the pix payment as a string. Base64 string containing the qr code image to embbed

// Mandatory object
const ASTROPAY_RESPONSE = {  
	"merchant_deposit_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
	"deposit_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"status":  "PENDING",  
	"url":  "https://onetouch-sandbox.astropay.com/deposit/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"type":  "gateway"
};

// Get the payment data response
AstropaySDK.payment(ASTROPAY_RESPONSE).
    .then(result => {
      //This is the payment data response object
      console.log(result)
    })

Example Response:

{
  amount: 5,
  currency: "BRL", 
  status: "PENDING",
  payment_type: "PIX",
  data: {
    txt_qr: "examplePixCode"
    image: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAYAAAAY4QDjAAAABmJLR0QA/wD/AP+gvaeTAAADfElEQVRoge2aXW/TQBBFf2BOwAhoh0CaQt0EfQAdAEYAIUARgCFWJED7FhYgFiwKFCAEsEKA"
  }
}

Sign in

This method allows you to render the "Sign in with Astropay" button on your site.

On the site you want to display the option setup an element with the "ap-login" id.

//On your site
 <div id="ap-login"></div>

// Mandatory Parameters
client_id: string
redirect_uri: string

// Show the Sign in with AstroPay button
AstropaySDK.signin(client_id, redirect_uri);

Supported languages

Language	code
English	en
Español	es
Indonesia	id
日本人	ja
한국의	ko
Português	pt
ไทย	th
Türk	tr
Tiếng Việt	vi
簡中	zh

Updrading

V4 - Latest

The last version of the SDK offers a better UI control, event listeners, new configuration parameters and new product integrations usage.

To fully understand this version, check the documentation on the Usage section.

Breaking changes

To correctly configure the event of automatic SDK modal closing and redirection, check the new Event Listeners section on this documentation.

V3

Breaking changes

Notice that for old versions only the _external_id was necessary to initiate the SDK UI. Now the method receives an object with the AstroPay init response provided by your own services.

Legacy method call:

const ASTROPAY_EXTERNAL_DEPOSIT_ID =  'External Deposit ID';
AstropaySDK.showDeposit(ASTROPAY_EXTERNAL_DEPOSIT_ID);

V3 updated method call:

const ASTROPAY_RESPONSE = {  
	"merchant_deposit_id":  "0c435984-0b55-4f16-a15e-36070fbcee19",  		
	"deposit_external_id": "QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"status":  "PENDING",  
	"url":  "https://onetouch-sandbox.astropay.com/deposit/QYPvyLz9fM57EGHtR1DV3TcZOlBng7Uw1m1KWUpe",  
	"type":  "default"  
};

// Show the DEPOSIT client
AstropaySDK.deposit(ASTROPAY_RESPONSE);

V2

Usage example

//Your APP ID SDK Credential
const APP_ID = ""; 

const ASTROPAY_CONFIG = {
  environment: "production",
  onDepositStatusChange: (depositResult) => getDepositStatus(depositResult), //Subscribes to every transaction status update.
  onClose: (depositResult) => iframeClosed(depositResult),
};

//Initiates the SDK with the configuration set above
AstropaySDK.init(APP_ID, ASTROPAY_CONFIG); 

//Sets the Deposit External ID generated for the deposit
const ASTROPAY_EXTERNAL_DEPOSIT_ID = "oehpJvCma8jaoaM7qmK3m3MX1LsmUWk8iulDl3Wx"; 

//Here you can do something according to the transaction current status.
const getDepositStatus = (depositResult) => { console.log(depositResult);};

const iframeClosed = (depositResult) => {
  //Here you can also do a action if the user closes the iFrame, also checking the transaction status.
  console.log(
    "action: iFrame was closed",
    "Deposit Status:",
    depositResult
  ); 
};