@astropay/astropay-sdk

v4.2.0

Published

a year ago

Official AstroPay client for easy frontend integration to One Touch

Downloads

660

0High
0Medium
0Low

astropay

astropay deposit cashout onboarding

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:

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:

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

Support

We provide detailed documentation on the AstroPay OneTouch API Guide. Please check it for more information that might be necessary for developers.

If you need more technical support, please contact support

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents