3. Integrate Papi to your webshop

Integrate Papi into your application, including handling payment flows, callbacks, and environment-specific URLs.

---

Environments

Use the correct environment URLs based on your application's stage:

• Sandbox (Preproduction): For testing purposes.
  • URL: https://paymentapi23i.ibonia.com/
• Production: For live transactions.
  • URL: https://api.papi.mg/

Payment Flow Overview

The payment process consists of the following steps:

1. Create a payment link: Send an API request to generate a payment link for the customer.
2. Redirect the customer: Use the returned payment URL to redirect the customer to the secure payment page.
3. Process the payment: The customer completes the payment on the secure page.
4. Receive a callback: After the payment, the system notifies your server with the payment result (success or failure).
5. Handle the result: Update your application based on the payment status from the callback.

---

Step-by-Step guide to implementing payment integration

This guide will walk you through integrating the payment API step by step, from creating endpoints for redirection to handling callbacks and making payment link requests.

Step 1: Create pages for redirection

You need to set up two pages on your website for redirecting customers after payment:

• Success URL: This is the page the customer will be redirected to after a successful payment. It can be an existing page (e.g., a product listing page) or a newly created one. Once the page is set up, take note of its URL, as it will be required when making the request to generate a payment link.

• Failure URL: This is the page the customer will be redirected to after an unsuccessful payment. It is typically an error page, but it can also be an existing page (e.g., a product listing page) with a custom message to inform the customer of the payment failure, rather than the default behavior. Once the page is set up, take note of its URL, as it will be required when making the request to generate a payment link.

Step 2: Create the callback API

The Callback API is an endpoint you create to handle notifications from Papi about the status of a payment. This API will be called automatically by Papi once a transaction is completed, whether it is successful or unsuccessful.

What you need to do:

1. Create an API endpoint:

   • The endpoint should accept POST requests.
   • For example, the endpoint URL might be https://yourdomain.com/payment-callback.

2. Purpose of the callback API:

   • Papi will send the payment details to this endpoint in the body of a POST request after the transaction is completed.
   • These details will include information about the transaction status, amount, payment method, and more.
   • Your application can then use this information to update records, notify users, or trigger other processes.

---

Example callback body sent by Papi:

When Papi calls your API, the body of the POST request will look like this:

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

---

Explanation of callback fields:

Field	Type	Description
description	string	A description of the payment (e.g., the order number or purpose of the payment).
amount	number	The amount of money processed in the payment.
transactionId	string	A unique identifier for the transaction, which you can use to track or update the payment.
status	integer	The status of the transaction: 1 for success, 0 for failure.
paymentMethod	integer	The payment method used: 1 for card, 2 for mobile money, etc.
sender	string	The email or identifier of the payer who initiated the payment.

---

Step 3: Prepare the body and header for payment link request

To generate a payment link, you need to send a POST request with the appropriate body and headers. This step is crucial as it ties together the previously created Success, Failure, and Callback URLs.

Endpoint

/clients/login

Headers

You need to include the following headers in your request:

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

Body parameters

• Success URL: This should be the URL of the Success page you created earlier (e.g., /success). This is where the customer will be redirected after a successful payment.
• Failure URL: This should be the URL of the Failure page you created earlier (e.g., /failure). This is where the customer will be redirected if the payment fails.
• Callback URL: This should be the URL of the Callback API you implemented earlier. This API will receive real-time payment status updates from Papi.

---

Example body for MGA:

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

---

Example body for EUR:

{
  "amount": 500,
  "change": {
    "currency": "EUR",
    "rate": 4800
  },
  "failureUrl": "https://yourdomain.com/failure", // URL of the failure page
  "successUrl": "https://yourdomain.com/success", // URL of the success page
  "callbackUrl": "https://yourdomain.com/payment-callback", // URL of the callback API
  "clientEmail": "customer@example.com",
  "paymentDescription": "Payment for Order #12345"
}

---

Explanation of currency and rates

• Supported currencies:

  • Papi supports both MGA (Malagasy Ariary) and EUR (Euro) for payments. You can choose the currency to be used by specifying it in the change.currency field of the payload.

• Rate field:

  • The rate field specifies the conversion rate for the selected currency.
  • The merchant and his developer (you) are responsible for providing the conversion rate to be used for the payment.
    • For example, if you want to charge the customer in EUR, and your exchange rate is 4800 MGA for 1 EUR, then rate should be set to 4800.
    • For MGA, the rate is typically set to 1 since no conversion is needed.

• Example usage:

  • If the payment amount is 500 EUR, and the conversion rate is 4800 MGA, the total in MGA would be 500 * 4800 = 2,400,000 MGA. The payment will be processed accordingly using the specified rate.

By allowing the merchant to define the rate, Papi provides flexibility for handling currency conversions while ensuring that the payment process aligns with businesses requirements.

---

Explanation of payload fields

Field	Type	Description
amount	number	The payment amount in the specified currency.
change.currency	string	The currency to convert the amount into (e.g., EUR, MGA).
change.rate	number	The conversion rate to apply for the currency exchange.
failureUrl	string	The URL of the Failure page you created earlier, where customers are redirected on payment failure.
successUrl	string	The URL of the Success page you created earlier, where customers are redirected on payment success.
callbackUrl	string	The URL of the Callback API you implemented earlier to receive payment status updates.
clientEmail	string	Email address of the client initiating the payment (must be valid).
paymentDescription	string	A short description of what the payment is for (e.g., product or service).

---

Why are these URLs important?

• Success URL: The customer is redirected here after a successful payment. This confirms their payment and ensures they are informed.
• Failure URL: The customer is redirected here if the payment fails. It provides a way to notify them and allow retry options.
• Callback URL: This API endpoint receives updates about the payment status, allowing your system to stay synchronized with the transaction status.

By correctly referencing the URLs from the earlier steps, you ensure that the redirection and callback mechanisms work seamlessly with your payment flow.

---

Step 4: Send the Post request to retrieve the payment Link

What you need to do:

1. URL: Send a POST request to /clients/payment-form.
2. Headers: Include the Content-Type and AuthentificationKey headers.
3. Body: Use the appropriate payload (e.g., MGA or EUR) based on your use case.

Example response:

{
  "data": {
    "token": "unique-transaction-token",
    "amount": "transaction-amount-id",
    "url": "https://payment-page-url.com"
  }
}

Response fields:

Field	Type	Description
token	string	A unique token generated for the transaction, used for identifying the payment session.
amount	string	A reference amount or identifier used in the transaction.
url	string	The URL where the customer will be redirected to complete the payment.

---

By following these steps, you can ensure your integration is seamless and your customers enjoy a smooth payment experience. Remember to test everything in a Sandbox environment before going live.

Step 5: Redirect the user to the payment URL

Once you have received the payment link in the response from Papi, the final step is to redirect the user to this URL so they can complete the payment.

What you need to do:

1. Extract the url field from the response you received in Step 4. This URL is the secure payment page generated by Papi for the transaction.
2. Redirect the user to this URL using your application's redirection mechanism (e.g., HTTP redirect in a web application, opening a browser tab in a mobile application).

---

Example response from Papi:

{
  "data": {
    "token": "unique-transaction-token",
    "amount": "transaction-amount-id",
    "url": "https://payment-page-url.com"
  }
}

• Field explanation:
  • url: This is the payment page where the customer will complete the transaction. You must redirect the user to this link.

By following the five steps outlined in this guide, you have successfully implemented a payment flow using Papi. This includes setting up redirection pages, creating a callback API to handle payment notifications, preparing and sending the request to generate a payment link, and redirecting the user to the payment page.