Initiating Transactions

When initiating transactions, sending a currency is required. A URL with a hosted payment gateway is provided where customers can pay in any currency and payment method of their choice.

Headers

• Authorization: Bearer YOUR_SECRET_KEY
• Content-Type: application/json

Body Parameters

Response Parameters

Success and Failure URLs

When a transaction is completed, the user is redirected to the specified success_url or failure_url. The same data structure is sent back to these URLs, also known as the callback. The callback includes the following parameters:

• status: The status of the transaction.
• checkout_id: The checkout ID.
• transaction_id: The transaction ID.
• transaction_reference: The transaction reference.

The status parameter can have the following values:

• success: The transaction was successful.
• failed: The transaction failed.
• pending: The transaction is pending.
• reversed: The transaction was reversed.
• refunded: The transaction was refunded.
• cancelled: The transaction was cancelled.

These statuses can be used to verify the transaction and take appropriate actions based on the result.

Sample Request to Initiate a Transaction

1. Transaction Request

cURL

curl -X POST https://api.zuripay.app/v1/transactions \
-H "Authorization: Bearer zp_test_26PHem9AhJZvU623DfE1x4sd" \
-H "Content-Type: application/json" \
-d '{
"amount": 1000,
"email": "[email protected]",
"currency": "USD",
"transaction_reference": "ZURIPAY1234567890",
"success_url": "https://yourwebsite.com/success",
"failure_url": "https://yourwebsite.com/failure"
}'

Python

import requests

url = https://api.zuripay.app/v1/transactions

headers = {
    "Authorization": "Bearer zp_test_26PHem9AhJZvU623DfE1x4sd",
    "Content-Type": "application/json"
}

data = {
    "currency": "USD",
    "amount": 1000,
    "email": "[email protected]",
    "transaction_reference": "ZURIPAY1234567890",
    "success_url": "https://yourwebsite.com/success",
    "failure_url": "https://yourwebsite.com/failure"
}

response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
    print("Transaction initiated:", response.json())
else:
    print("Error:", response.status_code, response.text)

2. Transaction Request for Mobile Money

cURL

curl -X POST https://api.zuripay.app/v1/transactions \
-H "Authorization: Bearer zp_test_26PHem9AhJZvU623DfE1x4sd" \
-H "Content-Type: application/json" \
-d '{
"amount": 1000,
"email": "[email protected]",
"mobile_money_number": "0712345678",
"currency": "USD",
"transaction_reference": "ZURIPAY1234567890",
"success_url": "https://yourwebsite.com/success",
"failure_url": "https://yourwebsite.com/failure",
"payment_method_type": "mobile_money",
"payment_method_code": "mpesa" // Set to the specific mobile money operator
}'

Python

import requests

url = https://api.zuripay.app/v1/transactions

headers = {
    "Authorization": "Bearer zp_test_26PHem9AhJZvU623DfE1x4sd",
    "Content-Type": "application/json"
}

data = {
    "currency": "USD",
    "amount": 1000,
    "email": "[email protected]",
    "mobile_money_number": "0712345678",
    "transaction_reference": "ZURIPAY1234567890",
    "success_url": "https://yourwebsite.com/success",
    "failure_url": "https://yourwebsite.com/failure",
    "payment_method_type": "mobile_money",
    "payment_method_code": "mpesa" // Set to the specific mobile money operator
}

response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
    print("Transaction initiated:", response.json())
else:
    print("Error:", response.status_code, response.text)

3. Transaction Request for Ecocash in Test Environment

cURL

curl -X POST https://api.zuripay.app/v1/transactions \
          -H "Authorization: Bearer zp_test_26PHem9AhJZvU623DfE1x4sd" \
          -H "Content-Type: application/json" \
          -d '{
          "amount": 1000,
          "email": "[email protected]",
          "mobile_money_number": "0712345678",
          "currency": "USD",
          "transaction_reference": "ZURIPAY1234567890",
          "payment_method_type": "mobile_money",
          "payment_method_code": "ecocash",
          "requested_response": "success" // Set to "success" or "failed" to simulate the desired response
          }'

Python

import requests

          url = https://api.zuripay.app/v1/transactions

          headers = {
              "Authorization": "Bearer zp_test_26PHem9AhJZvU623DfE1x4sd",
              "Content-Type": "application/json"
          }

          data = {
              "currency": "USD",
              "amount": 1000,
              "email": "[email protected]",
              "mobile_money_number": "0712345678",
              "transaction_reference": "ZURIPAY1234567890",
              "payment_method_type": "mobile_money",
              "payment_method_code": "ecocash",
              "requested_response": "success" // Set to "success" or "failed" to simulate the desired response
          }

          response = requests.post(url, headers=headers, json=data)
          if response.status_code == 200:
              print("Transaction initiated:", response.json())
          else:
              print("Error:", response.status_code, response.text)

4. Transaction Request for Innbucks

cURL

curl -X POST https://api.zuripay.app/v1/transactions \
          -H "Authorization: Bearer zp_test_26PHem9AhJZvU623DfE1x4sd" \
          -H "Content-Type: application/json" \
          -d '{
          "amount": 1000,
          "email": "[email protected]",
          "mobile_money_number": "0712345678",
          "currency": "USD",
          "transaction_reference": "ZURIPAY1234567890",
          "payment_method_type": "mobile_money",
          "payment_method_code": "innbucks",
          "requested_response": "success" // Set to "success" or "failed" to simulate the desired response if in test environment
          }'

Python

import requests

          url = https://api.zuripay.app/v1/transactions

          headers = {
              "Authorization": "Bearer zp_test_26PHem9AhJZvU623DfE1x4sd",
              "Content-Type": "application/json"
          }

          data = {
              "currency": "USD",
              "amount": 1000,
              "email": "[email protected]",
              "mobile_money_number": "0712345678",
              "transaction_reference": "ZURIPAY1234567890",
              "payment_method_type": "mobile_money",
              "payment_method_code": "innbucks",
              "requested_response": "success" // Set to "success" or "failed" to simulate the desired response if in test environment
          }

          response = requests.post(url, headers=headers, json=data)
          if response.status_code == 200:
              print("Transaction initiated:", response.json())
          else:
              print("Error:", response.status_code, response.text)

Sample Responses

Successful Transaction (200)

{
    "result": "success",
    "transaction_id": "zp_1234567890",
    "transaction_reference": "ZURIPAY1234567890",
    "message": "Transaction initiated successfully.",
    "hosted_url": https://zuripay.app/pay/ZURIPAY1234567890
}

Successful Transaction with Mobile Money (200)

{
    "result": "success",
    "transaction_id": "zp_1234567890",
    "transaction_reference": "ZURIPAY1234567890",
    "message": "Transaction initiated successfully.",
    "checkout_id": "zp_chk_1234567890"
}

Successful Transaction with Ecocash in Test Environment (200)

{
    "result": "success",
    "status": "success",
    "transaction_id": "zp_1234567890",
    "transaction_reference": "ZURIPAY1234567890",
    "message": "✅ Payment was successfully completed using Ecocash <b>(0771234567)</b> for <b>USD 5.00</b>.<br />Amount sent: <b>USD 5.00</b><br />Charges: <b>USD 0.00</b><br />Total: <b>USD 5.00</b><br />Payment reference: <b>ZURIPAY1234567890</b><br />Checkout ID: <b>zp_chk_1234567890</b>",
    "text_message": "✅ Payment was successfully completed using Ecocash *(0771234567)* for *USD 5.00*. Amount sent: *USD 5.00*. Charges: *USD 0.00*. Total: *USD 5.00*. Payment reference: ZURIPAY1234567890*. Checkout ID: *zp_chk_1234567890*"
}

Successful Transaction with Innbucks (200)

{
    "result": "success",
    "status": "pending",
    "transaction_id": "zp_1234567890",
    "transaction_reference": "ZURIPAY1234567890",
    "message": "Code generated successfully",
    "text_message": "Code generated successfully",
    "qr_code": "123456",
    "code": "123456"
}

Failed Transaction with Ecocash in Test Environment (200)

{
    "result": "error",
    "transaction_id": "zp_1234567890",
    "transaction_reference": "ZURIPAY1234567890",
    "message": "Transaction failed.",
    "checkout_id": "zp_chk_1234567890"
}

Bad Request (400)

{
    "result": "error",
    "message": "Invalid request parameters."
}

Bad Request - Missing Payment Method Code (400)

{
    "result": "error",
    "error": {
        "type": "InvalidRequestParameters",
        "message": "Payment method code is required. Parameter: payment_method_code"
    }
}

Bad Request - Missing Mobile Money Number (400)

{
    "result": "error",
    "error": {
        "type": "InvalidRequestParameters",
        "message": "Mobile money number is required. Parameter: mobile_money_number"
    }
}

Bad Request - Invalid Mobile Money Number Format (400)

{
    "result": "error",
    "error": {
        "type": "InvalidRequestParameters",
        "message": "Mobile money number must start with a zero. Parameter: mobile_money_number"
    }
}

Bad Request - Invalid Mobile Money Number Usage (400)

{
    "result": "error",
    "error": {
        "type": "InvalidRequestParameters",
        "message": "Mobile money number is only allowed for mobile money payment method. Parameter: mobile_money_number"
    }
}

Unauthorized (401)

{
    "result": "error",
    "message": "Unauthorized. Please provide a valid API key."
}

Internal Server Error (500)

{
    "result": "error",
    "message": "Internal server error. Please try again later."
}

Redirecting to Hosted Checkout Page

You can redirect users to a hosted checkout page using a publishable key. The amount can be set initially or input by the customer later. A transaction reference can be added or left out for autogeneration. Additionally, you can specify URLs to redirect users upon successful or failed transactions.

HTML

<form action="https://api.zuripay.app/v1/checkout" method="POST">
  <input type="hidden" name="publishable_key" value="undefined">
  <input type="hidden" name="amount" value="1000"> <!-- Optional, can be set by customer later -->
  <input type="hidden" name="transaction_reference" value="ZURIPAY1234567890"> <!-- Optional -->
  <input type="hidden" name="currency" value="USD"> <!-- Required -->
  <input type="hidden" name="success_url" value="https://yourwebsite.com/success"> <!-- Redirect URL on success -->
  <input type="hidden" name="failure_url" value="https://yourwebsite.com/failure"> <!-- Redirect URL on failure -->
  <button type="submit">Pay Now</button>
</form>

JavaScript

<script>
  function initiateCheckout() {
    const form = document.createElement('form');
    form.action = "https://api.zuripay.app/v1/checkout";
    form.method = "POST";

    const publishableKeyInput = document.createElement('input');
    publishableKeyInput.type = "hidden";
    publishableKeyInput.name = "publishable_key";
    publishableKeyInput.value = "undefined";
    form.appendChild(publishableKeyInput);

    const amountInput = document.createElement('input');
    amountInput.type = "hidden";
    amountInput.name = "amount";
    amountInput.value = "1000"; // Optional, can be set by customer later
    form.appendChild(amountInput);

    const transactionReferenceInput = document.createElement('input');
    transactionReferenceInput.type = "hidden";
    transactionReferenceInput.name = "transaction_reference";
    transactionReferenceInput.value = "ZURIPAY1234567890"; // Optional
    form.appendChild(transactionReferenceInput);

    const currencyInput = document.createElement('input');
    currencyInput.type = "hidden";
    currencyInput.name = "currency";
    currencyInput.value = "USD"; // Required
    form.appendChild(currencyInput);

    const successUrlInput = document.createElement('input');
    successUrlInput.type = "hidden";
    successUrlInput.name = "success_url";
    successUrlInput.value = "https://yourwebsite.com/success"; // Redirect URL on success
    form.appendChild(successUrlInput);

    const failureUrlInput = document.createElement('input');
    failureUrlInput.type = "hidden";
    failureUrlInput.name = "failure_url";
    failureUrlInput.value = "https://yourwebsite.com/failure"; // Redirect URL on failure
    form.appendChild(failureUrlInput);

    document.body.appendChild(form);
    form.submit();
  }
</script>
<button onclick="initiateCheckout()">Pay Now</button>

Embedded Hosted Checkout Page

This section explains how to embed a hosted checkout page directly within your website. By using this method, you can initiate a checkout process without redirecting the user to a different page. Instead, the checkout page is loaded in an iframe on the same page, providing a seamless user experience.

<script>
  /**
   * This function initiates a hosted checkout process without redirecting the user.
   * It sends a POST request to the API to generate a checkout ID, which is then used
   * to load the checkout page in an iframe on the same page.
   */
  function loadHostedCheckout() {
    const xhr = new XMLHttpRequest();
    xhr.open("POST", "https://api.zuripay.app/v1/checkout", true);
    xhr.setRequestHeader("Content-Type", "application/json");

    xhr.onreadystatechange = function () {
      if (xhr.readyState === 4) {
        if (xhr.status === 200) {
          const response = JSON.parse(xhr.responseText);
          if (response.checkout_url) {
            // Create an iframe to load the checkout page using the generated checkout URL
            const iframe = document.createElement('iframe');
            iframe.src = response.checkout_url;
            iframe.width = "100%";
            iframe.height = "600px";
            document.getElementById('checkout-container').appendChild(iframe);
          } else {
            console.error("Failed to get checkout URL");
          }
        } else if (xhr.status === 400) {
          console.error("Invalid request parameters.");
        } else if (xhr.status === 401) {
          console.error("Unauthorized. Please provide a valid API key.");
        } else if (xhr.status === 500) {
          console.error("Internal server error. Please try again later.");
        }
      }
    };

    // Prepare the data to be sent in the request
    const data = JSON.stringify({
      publishable_key: "undefined",
      amount: 1000, // Optional, can be set by customer later
      transaction_reference: "ZURIPAY1234567890", // Optional
      currency: "USD", // Required
      success_url: "https://yourwebsite.com/success", // Redirect URL on success
      failure_url: "https://yourwebsite.com/failure" // Redirect URL on failure
    });

    // Send the request to the API
    xhr.send(data);
  }
</script>
<div id="checkout-container"></div>
<button onclick="loadHostedCheckout()">Load Hosted Checkout</button>

Response Examples

Successful Transaction (200)

{
  "result": "success",
  "transaction_id": "txn_1234567890",
  "checkout_url": "https://checkout.zuripay.app/checkout_1234567890"
}

Bad Request (400)

{
  "result": "error",
  "message": "Invalid request parameters."
}

Unauthorized (401)

{
  "result": "error",
  "message": "Unauthorized. Please provide a valid API key."
}

Internal Server Error (500)

{
  "result": "error",
  "message": "Internal server error. Please try again later."
}

Available Payment Methods

Explanation of Payment Methods

This section provides details about the different payment methods available in our system. Each payment method has specific requirements and behaviors that you should be aware of when integrating them into your application.

Mobile Money Payments

Mobile money payments allow users to make transactions using their mobile phones. This method is popular in regions where traditional banking services are less accessible. When using mobile money payments, ensure that the mobile money number is correctly formatted and corresponds to the payment method being used.

Note: If the payment method code is "ecocash", the transaction will be real as Ecocash does not provide a test environment. Therefore, Ecocash transactions using test credentials will not trigger a real transaction but will return a dummy response instead.

For the staging environment, it is necessary to set the requested_response parameter. This allows you to specify whether you want a "success" or "failed" response for mobile money transactions, enabling you to test different scenarios effectively.