@astropay/astropay-sdk

AstroPay SDK for JavaScript

Official AstroPay SDK for easy product integrations

Table of Contents

• 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:

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:

// 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

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

License

Copyright © 2023 AstroPay. All rights reserved.