💰Payment Requests

Dunia Terminal allows you to bridge the gap between online and offline payments. You can create a payment request from the server powering your point of sales system, web, or mobile application and complete the payment offline using our Terminal.

The integration flow is a three-step process:

1. Create a payment request

2. Send the payment request to the Terminal

3. Listen to payment notifications

Create a payment request

Prerequisites

This document focuses on sending payment to our Terminal. You can refer to how to Create an invoice to get a better understanding of payment requests

When a user has selected their items and is ready to make payment, you initiate a payment request from your application to our /paymentrequest endpoint:

const https = require('https')

const params = JSON.stringify({ 
  "customer": "CUS_5lgv9bc41uw15pb",
  "description": "Invoice for Damilola",
  "line_items": [
    { "name": "Pancakes and sausage", "amount": "2000", "quantity": 1 },
    { "name": "Chicken Salad", "amount": "3000", "quantity": 1 }
  ]
})

const options = {
  hostname: 'api.dunia.co',
  port: 443,
  path: '/paymentrequest',
  method: 'POST',
  headers: {
    Authorization: 'Bearer SECRET_KEY',
    'Content-Type': 'application/json'
  }
}

const req = https.request(options, res => {
  let data = ''

  res.on('data', (chunk) => {
    data += chunk
  });

  res.on('end', () => {
    console.log(JSON.parse(data))
  })
}).on('error', error => {
  console.error(error)
})

req.write(params)
req.end()

The id and offline_reference are needed in the next step. You should store both parameters as they will be used in the coming sections.

Push to terminal

Dunia Terminal can receive and process a payment request sent from the merchant's server, allowing developers to build delightful in-person experiences.

In order to complete a payment request on the terminal, you need to make a request to the Terminal EventAPI, passing the id and offline_reference of a previously created payment request:

const https = require('https')

const params = JSON.stringify({
  "type": "invoice",
  "action": "process",
  "data": { 
    "id": 7895939, 
    "reference": 4634337895939
  }
})

const options = {
  hostname: 'api.dunia.co',
  port: 443,
  path: '/terminal/:terminal_id/event',
  method: 'POST',
  headers: {
    Authorization: 'Bearer SECRET_KEY',
    'Content-Type': 'application/json'
  }
}

const req = https.request(options, res => {
  let data = ''

  res.on('data', (chunk) => {
    data += chunk
  });

  res.on('end', () => {
    console.log(JSON.parse(data))
  })
}).on('error', error => {
  console.error(error)
})

req.write(params)
req.end()

Verify event delivery

When you push to the terminal, a successful response indicates that the push request has successfully been received by our servers and has been forwarded to the terminal. It doesn't necessarily mean that the request was successfully received by the device.

To confirm that the terminal received the event, you can make a request to the Terminal Event StatusAPI:

const https = require('https')

const options = {
  hostname: 'api.dunia.co',
  port: 443,
  path: '/terminal/:terminal_id/event/:event_id',
  method: 'GET',
  headers: {
    Authorization: 'Bearer SECRET_KEY'
  }
}

https.request(options, res => {
  let data = ''

  res.on('data', (chunk) => {
    data += chunk
  });

  res.on('end', () => {
    console.log(JSON.parse(data))
  })
}).on('error', error => {
  console.error(error)
})

When a terminal receives the payment request, it displays the payment request details for the customer to review and make payment.

Event delivery confirmation

You can only confirm that a device received an event within 48 hours from the request initiation

Listen to notifications

Receiving Notifications

In order to receive notifications, you need to implement a webhook URL and set the webhook URL on your Dunia Dashboard.

When payment is made for an invoice, we send an update to your server using webhooks. On your webhook URL, you should listen to these events:

Event	Description
charge.success	This is sent when the customer successfully makes a payment. It contains the transaction, customer, and card details.
paymentrequest.success	This is also sent to indicate a successful payment for an invoice. It contains the invoice details.
paymentrequest.pending	This is sent when the payment request is successfully created.
invoice.payment_failed	This is sent when the payment for the invoice failed.

Verifying a payment request manually

We'll send a webhook as soon as a transaction is completed. If your system is unavailable we'll keep retrying every hour for the next 72 hours. If you don't receive an event on your webhook URL after 72 hours, you can verify the invoice status either by using the Verify InvoiceAPI or by checking the status directly on the dashboard.