Quick Start

This guide is designed for developers to help you integrate Papi into your website or application. Follow these steps to set up a payment system that works seamlessly for your customers.

Prerequisites

1. Your application is online and ready to accept payments.

2. You have created an entry for your application in Papi (and the related organization). You can create an application entry by visiting the Papi application creation page.

3. You have the API key of the application, given by Papi.

4. Choose a URL that you want Papi to redirect to after a payment success.

5. Choose a URL that you want Papi to redirect to after a payment failure.

6. Choose a URL to provide to Papi as an endpoint, so that Papi can inform your system whether the payment succeeded or failed.

Workflow Overview

Before diving into the steps, here’s how everything will fit together:

1. A customer places an order on your website.
2. You create a secure payment link using Papi.
3. The customer is redirected to the payment page to complete their payment.
4. Papi sends the payment result to your system using a notification endpoint (a special URL on your server that processes updates).
5. Your system updates the order status based on whether the payment succeeded or failed.
6. The customer is shown the result on your website (success or failure).

Step 1: Generate a payment link

To let customers pay, you need to create a secure link that will direct them to a payment page. This link includes the payment amount, customer details, and where to notify your system about the payment result.

What You Need to Do

From your checkout page, send a POST request to https://api.papi.mg/clients/payment-form to request a payment link from Papi.

Data to Send to Papi

Include the following header where <your-application-api-key> is the API key attributed to your application by Papi:

{
  "Content-Type": "application/json",
  "AuthentificationKey": "Ibonia <your-application-api-key>"
}

Include a body like this (for MGA payments):

{
  "amount": 500,
  "change": {
    "currency": "MGA",
    "rate": 1
  },
  "failureUrl": "https://yourdomain.com/failure",
  "successUrl": "https://yourdomain.com/success",
  "callbackUrl": "https://yourdomain.com/payment-callback",
  "clientEmail": "customer@example.com",
  "paymentDescription": "Payment for Order #12345"
}

Example

Here is an example code on how to generate a payment link in PHP:

<?php
$apiUrl = "https://api.papi.mg/clients/payment-form";
$apiKey = "Ibonia <your-application-api-key>";

$data = [
    "amount" => 500,
    "change" => [
        "currency" => "MGA",
        "rate" => 1
    ],
    "failureUrl" => "https://yourdomain.com/failure",
    "successUrl" => "https://yourdomain.com/success",
    "callbackUrl" => "https://yourdomain.com/payment-callback",
    "clientEmail" => "customer@example.com",
    "paymentDescription" => "Payment for Order #12345"
];

$options = [
    "http" => [
        "header" => "Content-Type: application/json\r\nAuthentificationKey: $apiKey\r\n",
        "method" => "POST",
        "content" => json_encode($data),
    ],
];

$context = stream_context_create($options);
$response = file_get_contents($apiUrl, false, $context);

if ($response !== false) {
    $responseData = json_decode($response, true);
    $paymentLink = $responseData["data"]["url"];
    echo "Payment Link: $paymentLink\n";
} else {
    echo "Failed to generate payment link.\n";
}
?>

Step 2: Redirect the customer to the payment page

Once the payment link is generated, your customer needs to complete the payment by using that link.

What You Need to Do

1. Extract the URL from the response from Step 1.
2. Redirect the customer to that URL.

Data Returned by Papi

{
  "data": {
    "url": "https://api.papi.mg/paymentform/prepayment/ZGRmMDE4YTI5NThkM2EzN2RhMzJkZGJjOTI4MTI3Mzc5NzY5N2FjOGRhZjU3NGE4MGYxYjFmYWRhZWZmNDczZDozMTJhMTBmOTBmYTI1ZTAwYzIzMWEyNGE5NmUxZjQ2YTVmNGMxMmU4ODU2YTU3YzQ1ZjBkZDA0OTQ3OTZiNDcy/N5O541Y5Yztvd_-jc39z2lYdyb1w-CwxgWlkxoUeYBk/Er80J3WXIzi0ComLc48TguRe0-UOx0JTp98h1b7TwGo6VQUHZrsah1Wwp8RO6pGtGQlGhPB1JV5GTAzrn9kWBshv3brb7WRntw_ern6lQj4SvzQndZcjOLQKiYtzjxM25SIYg4Oc3fs3UDskfLtcjAUF5GFCkFo8GZi2NOR_FYE/CuE-1SuHIw6G9AT99HlI5A/IxzrYx2gLtTMKup4F3ycZQ/rh3cSfkPh-fmqxunHlcCbk3hBoox5v9dhx9KQdh4Alo/CbHS9nDGztVsUEAkKs0w5g"
  }
}

Example

Here is an example showing how to redirect the customer using PHP:

<?php
header("Location: https://api.papi.mg/paymentform/prepayment/ZGRmMDE4YTI5NThkM2EzN2RhMzJkZGJjOTI4MTI3Mzc5NzY5N2FjOGRhZjU3NGE4MGYxYjFmYWRhZWZmNDczZDozMTJhMTBmOTBmYTI1ZTAwYzIzMWEyNGE5NmUxZjQ2YTVmNGMxMmU4ODU2YTU3YzQ1ZjBkZDA0OTQ3OTZiNDcy/N5O541Y5Yztvd_-jc39z2lYdyb1w-CwxgWlkxoUeYBk/Er80J3WXIzi0ComLc48TguRe0-UOx0JTp98h1b7TwGo6VQUHZrsah1Wwp8RO6pGtGQlGhPB1JV5GTAzrn9kWBshv3brb7WRntw_ern6lQj4SvzQndZcjOLQKiYtzjxM25SIYg4Oc3fs3UDskfLtcjAUF5GFCkFo8GZi2NOR_FYE/CuE-1SuHIw6G9AT99HlI5A/IxzrYx2gLtTMKup4F3ycZQ/rh3cSfkPh-fmqxunHlcCbk3hBoox5v9dhx9KQdh4Alo/CbHS9nDGztVsUEAkKs0w5g");
exit();
?>

Step 3: Set up a notification endpoint

After the customer completes the payment on Papi's payment page, Papi needs to inform your system whether the payment succeeded or failed. This is done by sending data to a notification endpoint in your application (a special URL on your server that receives payment updates).

What you need to do

1. Create an endpoint that handles the notification from Papi as a POST request. This script will, for example, update your system, such as marking the order as paid or failed.
2. Save this script to reflect the URL you gave to Papi in Step 1 as the value for the callbackUrl attribute. In the example above, that URL is https://yourdomain.com/payment-callback.

Data returned by Papi

Example data sent back by Papi:

{
  "description": "Payment for Order #12345",
  "amount": 500.00,
  "transactionId": "abc123def456",
  "status": 200,
  "errorMessage": "",
  "paymentMethod": 2,
  "sender": "customer@example.com"
}

• status is an HTTP status code. Values are:
  • 200 if the payment is a success.
  • 400 if the payment is a failure.
• errorMessage is empty if the payment is a success. Otherwise, it contains information about the reasons for failure if available (not all providers provide details).
• paymentMethod values are:
  • 2 for MVola,
  • 3 for Airtel Money,
  • 4 for SogeCommerce (card payment),
  • 5 for Orange Money.

Example PHP notification endpoint

<?php
// payment-c

allback.php

// Read the JSON data sent by Papi
$data = json_decode(file_get_contents("php://input"), true);

// Extract important details
$transactionId = $data["transactionId"];
$status = $data["status"]; // 1 = Success, 0 = Failure

if ($status == 1) {
    // Payment was successful
    file_put_contents("log.txt", "Transaction $transactionId: SUCCESS\n", FILE_APPEND);
    // Update your database to mark the order as paid
    // ...
} else {
    // Payment failed
    file_put_contents("log.txt", "Transaction $transactionId: FAILED\n", FILE_APPEND);
    // Handle failure (e.g., notify the customer)
    // ...
}

http_response_code(200); // Let Papi know the update was received
?>

Step 4: Create pages for payment results

Once the payment process is complete, Papi will itself inform the user if the payment was a success or a failure by displaying a message. After that display, Papi will redirect the user to either a success page or a failure page on your website. You gave these URLs to Papi in Step 1.

What you need to do

Option 1: Given that Papi has already informed the user of success or failure, you could use a single URL for both that would simply return the user to the home page, the order details page, or a page of your choice.

Option 2: If the user is to be informed about next steps such as delivery, then you can create two distinct pages:

• Create a page on your website to handle the next steps of a successful payment. Save it to the URL you gave to Papi in Step 1 under the successUrl attribute.
• Create a page on your website to handle the next steps of a payment failure. Save it to the URL you gave to Papi in Step 1 under the failureUrl attribute.