How to Integrate with imsafu Using PHP

imsafu is a payment processing service that allows you to create and query payments. This document will guide you through accessing the imsafu service.

Prerequisites

Before getting started, make sure you have the following prerequisites:

1. PHP environment installed on your computer.
2. Basic knowledge of PHP development.

Install Dependencies

There are no specific dependencies for accessing the imsafu service. Here, we provide some default libraries that you can replace with any other library that offers similar functionality.

Create Required Variables for imsafu

To connect to the imsafu test server, you can use the following variables. If you want to connect to the production server, you can join the waiting list.

$options = array(
  "url" => "https://devnet.imsafu.com",
  "api" => "https://allowpay-api-devnet.fly.dev/v1",
  "apiSecret" => "your-api-secret",
  "receiver" => "your-wallet-account",
  "merchantBrand" => "imsafu demo",
  "merchantRedirectURL" => "https://merchant.com/redirect"
);

Create a New Payment

First, we need to generate a random 32-character hexadecimal string as the ID for the new order.

function generateOrderID() {
  return '0x' . str_pad(bin2hex(random_bytes(32)), 32, '0', STR_PAD_RIGHT);
}

To create a new payment, we need to implement a createPayment function. This function takes the payment amount as a parameter and returns a parsed object as a PaymentResponse.

function createPayment($amount) {
  global $options;
  $newOrderID = generateOrderID();

  $payload = array(
    "payment" => array(
      "orderID" => $newOrderID,
      "receiver" => $options['receiver'],
      "amount" => strval($amount),
    ),
    "notifyURL" => $options['url'] . "/notify"
  );

  $headers = array(
    "Content-Type: application/json",
    "Authorization: Bearer " . $options['apiSecret']
  );

  $ch = curl_init($options['api'] . "/depositPay");
  curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

  $response = curl_exec($ch);

  if ($response === false) {
    return null;
  }

  $responseData = json_decode($response, true);
  return $responseData;
}

Generate Payment URL

Next, write a method to generate the payment URL.

function buildPaymentURL($itemMemo, $res) {
  global $options;

  $urlSearchParams = http_build_query(array(
    "payID" => $res['payment']['payID'],
    "brand" => $options['merchantBrand'],
    "memo" => $itemMemo,
    "redirect_url" => $options['merchantRedirectURL'],
    "currency" => "USD"
  ));

  $url = $options['url'] . "/payment_qrcode?" . $urlSearchParams;
  return $url;
}

$amount = 100;
$createPaymentResponse = createPayment($amount);
$paymentURL = buildPaymentURL("test item", $createPaymentResponse);

User Payment

Display the generated paymentURL to the user, and when clicked, it will open the payment page on a web browser. For the specific payment process, refer to Using imsafu for Payments.

Retrieve Payment Information

After the user completes the payment, imsafu will send a POST request to the notifyURL provided during the creation of the order, containing the payID. We need to retrieve the payment information using the getPayment interface and verify if the user's payment was successful.

To retrieve the payment information, we first need to implement a getPayment function. This function takes the payment ID (payID) as a parameter and returns a parsed object as a PaymentResponse.

function getPayment($payID) {
  global $options;

  $headers = array(
    "Content-Type: application/json",
    "Authorization: Bearer " . $options['apiSecret']
  );

  $ch = curl_init($options['api'] . "/depositPays/" . $payID);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

  $response = curl_exec($ch);

  if ($response === false) {
    return null;
  }

  $responseData = json_decode($response, true);
  return $responseData;
}

// Get payID from the notify request

$paymentResponse = getPayment($payID);

// Perform further operations

Appendix: Type Definitions Used in the Code

class Payment {
  public $payID;
  public $orderID;
  public $receiver;
  public $amount;
  public $originalAmount;
  public $maxFeeAmount;
  public $deadline;
}

class Chain {
  public $id;
  public $symbol;
  public $name;
}

class Token {
  public $symbol;
  public $address;
}

class ReceiveTx {
  public $chain;
  public $txID;
  public $confirmedAt;
  public $amount;
  public $feeAmount;
  public $token;
}

class Deposit {
  public $chainID;
  public $token;
}

class PaymentResponse {
  public $status;
  public $payment;
  public $owner;
  public $depositAddress;
  public $callID;
  public $receiveTx;
  public $deposits;
}

Please note that the above code examples are for demonstration purposes only, and you should adjust and enhance them for your specific use case and security requirements.