Apexxfintech SDK API

JavaScript SDK Integration 1.0.0 The Apexx Payment Integration SDK is a comprehensive solution designed to streamline payment processing for merchants by integrating multiple payment methods into a single, unified platform. With support for providers like PayPal, Volt, and others, the SDK enables merchants to offer their customers a diverse range of payment options while ensuring seamless management of the payment flow tailored to each method. What is this Library for? The Apexx-PayPal SDK is designed to simplify the integration of PayPal's Embedded Checkout into web applications. This SDK abstracts the complexities of payment logic, enabling merchants to easily handle payment approval and event-driven callbacks. The SDK allows customization of funding sources such as PayPal and Volt, providing flexibility for developers and businesses alike. This document outlines the SDK’s core design, focusing on its key methods, error-handling strategy, and security considerations. By using this SDK, developers can streamline the integration of Apexx's payment services within their applications. What are the features? Paypal Express Checkout Pay Later Credit Use Cases Online Payments & Checkout Integrate PayPal Express Checkout for faster transactions. Accept Pay Later and Paypal Credits Option to auto-capture or capture later. Option to complete the order as per your flow. SDK Process Flow Apexx Completes the Order (CompleteOrder = true) Merchant Completes the Order (CompleteOrder = false) How to setup? The Apexx js library can be downloaded from here: Environment Endpoint Description Sandbox https://sandboxsdk.apexx.global/ApexxSDK.min.js This environment provides you with full access to all the features available. Transactions will have no financial impact. Production https://sdk.apexx.global/ApexxSDK.min.js This environment will be the Live environment with access based on your configuration. Transactions will have financial impact. Where to get credentials If you already have a relationship with a service provider, we will help create the neccessary IDs and share them with your payment provider of choice. If you do not yet have an account with a payment service provider, please reach out to your Apexx account manager who will be happy to help facitlate the onboarding process. To process payments via Apexx SDK you will need an organisation id and an X-APIKEY which you can get from your Apexx account manager. How to consume the library? If you are consuming the library directy from our CDN (Recommended), then add the following JS snippet to your relevant checkout page. <script src="https://paypalsandboxsdkdemo.apexx.global/ApexxSDK.min.js"></script> const paymentInstance = new Apexx("PayPal", (error) => { console.error("Error initializing payment SDK:", error); }); How to incorporate with any existing libraries Merchants can integrate the SDK alongside their existing payment processing systems. The SDK is compatible with JavaScript and backend payment flows. Please note that any unique IDs that are used would need to be specific to the JS library. How to make a call Encrypting Payment parameters Before initializing the SDK you would need to encrypt the data required for processing the payment. To encrypt the data you can call the Apexx server encryption API which will provide you with the required details to initiate the javascript SDK. For more details on server encryption API, visit API Reference The details of the fields required to be encrypted are mentioned in the schema definitions below. Initializing the embedded element Initialize the Apexx wrapper by loading the script from Apexx, using the activation instance keyword (e.g. "PayPal") and an error callback function to handle wrapper error for that payment instance. Eg: const paypalInstance = new Apexx("PayPal",(error)=>{alert(console.log("error"); ))}); The APEXX SDK is initialized using a configuration object that contains key parameters required for payment processing. The initialization process sets up the SDK environment and ensures all provided configurations are validated. Key Parameters & Data Type : These are needed to be provided as a single object. encryptedkey (string) – Required Encrypted Key received in the Get encryption API call. encryptedpayload (string) – Required Encrypted payload received in the Get encryption API call. completeOrder (boolean) - Optional Field defines whether transaction should be completed by the SDK or you want to complete it separately after the approval of the order. organisation_id (string) - Required The ID of an organisation. Example const apexx = new Apexx({ encryptedkey: 'eyJraWQiOiJnM2FKMlJyUVNFYmM5WTVxUFowaDR0bVpr....', // Required encryptedpayload: 'eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0....', // Required completeOrder: 'true', organisation_id:'716ae509B5091A44baBaadeAc4b384e6b31d' sources to enable eventHandlers: { // Optional event handlers onApprove: (data, actions) => { console.log('Payment Approved', data); }, onError: (error) => { console.error('Payment Error:', error); }, onCancel: (error) => { console.error('Payment Error:', error); },} }); Completing the order You can pass the completeOrder field as true to complete the order from the Apexx SDK after the approval is received from Paypal. If you wish to complete the order from your side via a server to server call then pass the completeOrder field as false. However if you chose to complete the order yourself then you will have to call the Apexx Complete Order API which will process the transaction and respond you back with the transaction data. See Complete Order API for retrieving order details Please Note: If you are not doing an auto-capture then capture request will be required separately which you can find at below location. See Capture API Reference Error handling Error Categories Use onError callback to handle errors dynamically. Log errors to capture debugging information. Error TypeDescriptionINPUT_VALIDATIONIssues with provided parameters.SECURITYSecurity-related errors.GENERICGeneral errors not categorized elsewhere.SCRIPTIssues loading the SDK. Error Messages CodeDescriptionMISSING_CONTAINERIContainer not created , Instantiate container first..INVALID_FORMATInvalid {type} format.MALICIOUS_INPUTDetected potentially malicious and sanitized.GENERIC_ERRORError occurred during {type} operation. SCRIPT_ERRORFailed to load {type} script instance. Error Statuses StatusDescriptionINVALID_MODE400 (BadRequest)MISSING_PAYMENT_CONTAINER500 (Internal Server Error)INVALID_FORMAT400 (BadRequest)MALICIOUS_INPUT403 (Forbidden)GENERIC_ERROR500 (Internal Server Error)SCRIPT_ERROR500 (Internal Server Error) <script src="https://paypalsandboxsdkdemo.apexx.global/ApexxSDK.min.js" integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxjwG6ODnY7XJ5SPPc4v5Z4tM"" crossorigin="anonymous"></script> Security considerations To ensure a secure integration of the Apexx SDK, merchants should follow these security best practices: Always load the SDK and make API calls over HTTPS to prevent interception of sensitive payment data. Validate and Sanitize Inputs Ensure that all user inputs, including payment details, are properly validated and sanitized to prevent injection attacks. Use Apexx’s server encryption API to encrypt sensitive payment data before transmitting it to the SDK. Use HTTPS when calling the api to encrypt the payload Implement Content Security Policy (CSP) Configure a strict CSP header to prevent unauthorized script execution. Never expose API keys or encryption credentials on the client-side. Store them securely on your backend. Restrict cross-origin access to ensure that only authorized domains can interact with your payment implementation. Always use the latest version of the SDK to benefit from security patches and improvements. Handle Errors Securely Avoid exposing detailed error messages to users, which could leak sensitive implementation details.