Quick Start

Get setup to accept payments in less than 5 minutes...

NOTE: Our quick start guide can help you set up our API quickly in a few easy steps. However, we encourage you to read through it in order to utilize its full power!

Get your API keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. API keys from client applications must also include your public key so we know it's for you. For client-side initialized transactions, only public keys are allowed for security purposes.

You can generate and retrieve your API key from your Dashboard at any time.

Install the SwitchApp inline library

The easiest way to interact with our API is to use our official javascript inline library:

You may also use SwitchApp via a javascript tag if you do not wish to install packages

npm

# Install via NPM
npm install --save @switchappgo/switchapp-inline

# Install via yarn
yarn add @switchappgo/switchapp-inline


# Require the package in the project file
import SwitchAppCheckout from "@switchappgo/switchapp-inline";;

script tag

How it helps: Using our library enables you to get up and running quickly with minimal coding.

Initialize the library with your public key

Pass your public key as the publicApiKey property to the initialization function.

      const switchappClient = new SwitchAppCheckout({
        publicApiKey: "pk_live_9E6x4TxxnXZVzC6HQUryAUeeu"
      });

Setup your payment

Assemble all the details of your payment. This includes the country, currency, the amount you would like to receive, and the customer's details.

      ...

      function onClose(args) {
        alert("Modal closed with args: " + args);
        console.log("Modal closed with args: ", args);
      }

      function onSuccess(args) {
        alert("payment successful with args: " + args);
        console.log("payment successful with args: ", args);
      }
      
      const paymentDetails = {
            country: "NG",
            currency: "NGN",
            amount: 150,
            customer: {
              full_name: "Your Full Name",
              email: "[email protected]",
            },

            // (OPTIONAL) Customize the checkout page
            title: "My First Transaction Using SwitchApp InlineJS",
            logo_url:
              "https://your-awesome-website/your-awesome-logo.svg",
            description: "This is a test payment",
            
            // (OPTIONAL) Extra helpful data to the payment
            metadata: {
              cartId: 12,
              flightId: "x-404-251",
            },

            // (OPTIONAL) Specify actions to run upon closing the checkout page or completing payment
            onClose,
            onSuccess,
          }

Make your first request

To make your first request, pass the assembled payment information to the showCheckoutModal function in the SwitchApp client returned after initialization with your public key. This will initialize a new payment transaction and pop up a hosted page modal for the customer to complete payment.

Once payment is completed or canceled, the checkout modal closes and invokes any functions passed to it ie onSuccess and onClose passing parameters to them that describe the payment info.

    switchappClient.showCheckoutModal(paymentDetails)
    .then((p) => {
        console.log(`Successfully initialized a new payment`);
    });

IMPORTANT: Your secret key should always remain hidden from the public. This includes ensuring it is never committed to source control eg git and that it is never bundled in your client-side code.

If your secret keys are compromised at any time, terminate them and generate new ones. This will render the compromised keys invalid. This can be done via the API or on your dashboard.

The process described above only works while initializing from a client device eg a customer's mobile phone or computer. To initialize via your server, you need to call the server-initialize endpoint while authenticating with your secret key.