Introduction

Welcome to the Zippie Pay API Documentation

These docs will help you to quickly get up and running with the Zippie Pay API. The documentation includes information you need to know about the API as well as detailed examples to quickly get you going

Supported Currencies

Zippie Pay API supports the following currencies at the moment.

• Kenyan shillings (KSH)

Getting Started

You can start collecting payments from customers who use Zippie Wallet or M-Pesa.

Once your customer taps "Pay" in your webpage or app, a Zippie payment dialogue pops up and guides the customer through the payment process.

You can set up the service in four steps:

1. Installing the package
2. Create Forms
3. Configure Inputs
4. Call API

Installation

You can include the Zippie Pay API through the cdn or the npm:

Include the CDN tag to your markup, preferably at the footer

<script src="https://unpkg.com/@zippie/pay-button@1.0.2/dist/zippie-pay.js"></script>

npm install @zippie/pay-button

Creating your forms

<input type="email" id="zippie_email">
<input type="number" id="zippie_amount">
<button onclick="onBuyClicked()">Submit</button>

<template>
  <div class='container'>
    <form @submit.prevent='submitForm'>
        <input type='email' v-model='zippie_email'>
        <input type='number' v-model='zippie_amount'>
        <button type='submit' value='submit'>Submit</button>	
    </form>
  </div>
<template>

<script>
export default {
  data() {
    return { 
      zippie_email,
      zippie_amount
    }
  },
}
</script>

import React from 'react'

function App() {

  return (
    <div>
      <form>
        <input
          type="email"
        />
        <input
          type="number"
        />
        <input type="submit" value="Submit" />
      </form>
    </div>
  )
}

export default App

Configuring your forms

Create a function for the <button> element and then create a variable with the following inputs:

<script>
function onBuyClicked() {
  const paymentData = {
    merchantId: 'test.merchant',
    orderId: 'YOUR_ORDER_ID', // tips: you can use customer's email if you don't have access to an unique orderId
    amount: document.getElementById('zippie_amount').value,
    currency: 'KSH' ,
    email: document.getElementById('zippie_email').value
  }
}
</script>

<script>
import { PaymentRequest } from ‘@zippie/pay-button’

export default {
  data() {
    return { 
      zippie_email,
      zippie_amount
    }
  },
  methods: {
    submitForm() {
      const paymentData {
        merchantId: 'test.merchant',
        orderId: 'YOUR_ORDER_ID',
        amount: 1,
        currency: 'KSH',
      }
    }
  }
}
</script>

import React, { useState } from 'react'


function App() {
  const [email, setEmail] = useState("")
  const [amount, setAmount] = useState("")

  const handleSumbit = async (evt) => {
    evt.preventDefault()
    const paymentData = {
      merchantId: 'test.merchant',
      orderId: 'YOUR_ORDER_ID',
      amount: amount,
      currency: 'KSH',
      email: email,
    }
    console.log(paymentData)
  }

  return (
    <div>
      <form onSubmit={handleSumbit}>
        <input
          type="email"
          value={email}
          onChange={e => setEmail(e.target.value)}
        />
        <input
          type="number"
          value={amount}
          onChange={e => setAmount(e.target.value)}
        />
        <input type="submit" value="Submit" />
      </form>
    </div>
  )
}

export default App

Parameters

merchantId [string]

Zippie will provide you a unique Merchant ID which you insert here. If you don't have a Merchant ID yet, contact your Zippie support person.

orderId [string]

An Order ID is a unique number which you'll need to identify and track your orders. If you don't have an Order ID, you can use the customer's email address.

amount [string]

Input the amount you wish charge your customer. (supports up to 6 decimal e.g. 0.123456)

email [string]

The email parameter is where the payment receipt would be sent. Usually your customer's email address.

Calling the API

function onBuyClicked() {
  const paymentData = {
    merchantId: 'test.merchant',
    orderId: 'YOUR_ORDER_ID',
    amount: document.getElementById('zippie_amount').value,
    currency: 'KSH' ,
    email: document.getElementById('zippie_email').value
  }

  try {
    // Create a variable that accesses the paymentRequest API, 
    // and call in the variable you set
    const request = zippie.paymentRequest(paymentData)  
    request.show().then(function(result) {
      // Payment successful
      console.log('zippie.paymentRequest result', result)
    }).catch(function(error) {
      // Payment failed (e.g. cancel)
      console.error('zippie.paymentRequest error', error)
    })
  } catch (error) {
    console.error(error.message)
  }
}

<script>
import { PaymentRequest } from ‘@zippie/pay-button’

export default {
  data() {
    return { 
      zippie_email,
      zippie_amount
    }
  },
  methods: {
    submitForm() {
      const paymentData {
        merchantId: 'test.merchant',
        orderId: 'YOUR_ORDER_ID',
        amount: 1,
        currency: 'KSH',
      }

      const request = zippie.paymentRequest(paymentData)
      request.
        .show()
        .then(function (result) {
          // Payment succesful
       }) 
      .catch(function (error) {
        // Payment failed (e.g. cancel)
      })
    }
  }
} 
</script>

import React, { useState } from 'react'
import { paymentRequest } from '@zippie/pay-button'


function App() {
  const [email, setEmail] = useState("")
  const [amount, setAmount] = useState("")

  const handleSumbit = async (evt) => {
    evt.preventDefault()
    const paymentData = {
      merchantId: 'test.merchant',
      orderId: 'YOUR_ORDER_ID',
      amount: amount,
      currency: 'KSH',
      email: email,
    }
    const request = paymentRequest(paymentData)
    const result = await request.show()
    console.log(result)
  }

  return (
    <div>
      <form onSubmit={handleSumbit}>
        <input
          type="email"
          value={email}
          onChange={e => setEmail(e.target.value)}
        />
        <input
          type="number"
          value={amount}
          onChange={e => setAmount(e.target.value)}
        />
        <input type="submit" value="Submit" />
      </form>
    </div>
  )
}

export default App

Webhooks

Webhooks are coded like a phone number that Zippie uses to notify you of any activity in your Zippie account, e.g. incoming payments or payout of funds to your bank account. The notification is carried out by calling the configured webhook URL.

Note: Not all Zippie Pay integrations require webhooks.

Getting started

Before we get started setting up your webhook, you must obtain a secret key from Zippie. Contact your Zippie Support person for your secret key.

Setting up your webhook to listen for incoming payments (server side)

Once your server is up and running, your server would be listening for incoming post request. The secret key is used to verify the header signature in order to make sure the request is coming from Zippie servers.

Installation

npm install @zippie/pay-button

Example

const express = require('express')
const bodyParser = require('body-parser')
const app = express()
const { signature } = require('@zippie/pay-button/src/utils.js')

const YOUR_SECRET = 'ef03e1d18120f717deb1f9445d9a86bf46011dc5e82ad5230234db866ee1aa13' // Provided by Zippie

app.use(bodyParser.json())

app.post('/incoming_payment', async function (req, res) {
  const payment = req.body

  try {
    signature.verifyHeader(JSON.stringify(payment), req.headers['zippie-signature'], YOUR_SECRET, 120)
  } catch(error) {
    res.status(400).send('Verification of zippie-signature failed')
    return
  }

  // Handle incoming payment (e.g. send sms, store in db, call another api, etc)
  const amount = payment.amount
  const token = payment.token
  const orderId = payment.recipientOrderId // sha256(orderId) e.g. sha256('YOUR_ORDER_ID') => '0xda70aa8a0a002bcdb0eb84d829198ca7a49d5c970590ccd56e5ae278c152cd7d'
  console.log(`Incoming payment successful for order ${orderId}: ${amount} ${token}`)
  res.status(200).send('OK')
})

const server = app.listen(9300, '0.0.0.0', function () {
  console.log('app listening at http://%s:%s', server.address().address, server.address().port)
})

Payment data example

This payment data serves as an example of C2B or Customer to Business (Zippie Wallet to Merchant Wallet)

const payment = {
 amount:"0.750000",
 recipientOrderId:"0xda70aa8a0a002bcdb0eb84d829198ca7a49d5c970590ccd56e5ae278c152cd7d",
 token:"JAMBOPAY-KSH",
 uniqueID:"0xbe1f34058bcddb61847e51cd512c888f0985c97e5222dd25d33eb29074650d74/log/1",
 type:"c2b",
}

Parameters

amount [float]

Amount would be in decimals

recepientOrderId [string]

Recipient Order ID (sha256 of the original orderId)

token [string]

Token name

uniqueID

txHash (Ethereum Transaction Hash) + Log Index

Support

If you are missing any examples in your preferred programming language, don't hesitate to Contact Us and we will do our best to help.