Accept Payments

To accept a payment, create a transaction using our API, our client Javascript library. Every transaction includes a link that can be used to complete payment.

Popup

Socialpay Popup provides a simple and convenient payment flow for web. It can be integrated in five easy steps, making it the easiest way to start accepting payments. See demo of the payment methods on the checkout here.

Collect customer information.

To initialize the transaction, you'll need to pass information such as email, first name, last name amount, order_id, etc. You can also pass any other additional information in the custom_fields object field. Here is the full list of parameters you can pass:

Param	Required?	Description
public_key	Yes	Your public key from social pay.
email	Yes	Email address of customer
first_name	Yes	First name of customer
last_name	Yes	Last name of customer
order_id	Yes	Order id for payment
fee_bearer	Yes	Fee bearer for the payment (client/merchant)
amount_charge	Yes	Amount charged for payment
cryptocurrency_type	Yes	Crypto currency type used for the payment.
redirect_url	No	Redirect url for the payment.
custom_fields	No	objects containing any extra information you want recorded in the transaction.
callback	No	Function that runs when payment is successful. This should ideally be a script that uses the verify endpoint on the Social Pay API to check the status of the transaction.
onClose	No	Javascript function that is called if the customer closes the payment window instead of making a payment.

The customer information can be retrieved from your database if you already have it stored, or from a form like in the example below:

demo of social pay

In this sample, notice how:

1. The Social Pay inline JavaScript is included using a script tag. This is how you import Social Pay into your code.

2. The amount here can be hardcoded if you want to charge a specific amount.

3. The Pay button has been tied to an onClick function called payWithSocialPay. This is the action that causes the Social Pay popup to load.

Initialize transaction

When you have all the details needed to initiate the transaction, the next step is to tie them to the JavaScript function that passes them to Social Pay and displays the checkout popup modal.

  function payWithSocialPay() {
    var handler = SocialPay.invoice({
      public_key: "PUBLIC_KEY_cl8soodjc0003iggmxp5phm2ucl8soodjc0004iggmmucwstpa",
      order_id: "SCPAY-DEMO-" + makeid(10),
      first_name: document.getElementById("first_name").value,
      last_name: document.getElementById("last_name").value,
      email: document.getElementById("email").value,
      fee_bearer: "merchant",
      amount_charge: "1.00",
      cryptocurrency_type: "$GARY",
      custom_fields: [
        {
          website: document.getElementById("website").value,
          twitter: document.getElementById("twitter").value
        }
      ],
      callback: function (response) {
        alert(
          "Payment successful. Transaction Reference: " + response.reference_code
        );
        console.log(response);
      },
      onClose: function () {
        console.log("Window Closed.");
      }
    });
  
    handler.openIframe();
  }
  
  function makeid(length) {
    var result = "";
    var characters =
      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    var charactersLength = characters.length;
    for (var i = 0; i < length; i++) {
      result += characters.charAt(Math.floor(Math.random() * charactersLength));
    }
    return result;
  }    

Important notes

1. The public_key field here takes your social pay public_ key.

2. The cryptocurrency_type should be the coin symbol e.g $GARY, $DRIVE e.t.c.

3. It's ideal to generate a unique order_id from your system for every transaction to avoid duplicate attempts.

4. The callback method is called when payment has been completed successfully on the Social Pay checkout. See the next section to see for how to handle the callback.

5. the onClose method is called if the user closes the modal without completing payment.

Handle the callback method.

The callback method is fired when the transaction is successful. This is where you include any action you want to perform when the transaction is successful.

The recommended next step here is to verify payment to confirm the status.

Helpful Tip

To verify the transaction, you have to set up a route or page on your server that you pass the transaction reference to. Then from your server, you call the Social Pay verify endpoint to confirm the status of the transaction, and the response is returned to your frontend.

There are 2 ways you can call your server from the callback function

1. Make an AJAX request to the endpoint on your server that handles the transaction verification

callback: function(response){

  $.ajax({

    url: 'http://www.yoururl.com/reference='+ response.reference_code,

    method: 'get',

    success: function (response) {

      // the transaction status is in response.data.status

    }

  });

}

2. Redirect to the server URL by setting a window.location to the URL where the verification endpoint is set on your server.

callback: function(response) {

  window.location = "http://www.yoururl.com/?reference=" + response.reference_code;

};

Warning

Never call the Social Pay API directly from your front-end to avoid exposing your secret key on the frontend. All requests to the Social Pay API should be initiated from your server, and your frontend gets the response from your server.

Verify the Transaction

After payment is made, the next step is to verify the transaction. Here's how to verify transactions with Social Pay

Handle Webhook

When a payment is successful, Social Pay sends a webhook event to your webhook URL. You can learn more here.

Redirect

Here, you call the Initialize TransactionAPI from your server to generate a checkout link, then redirect your users to the link so they can pay. After payment is made, the users are returned to your website at the redirect_url

Collect customer information

To initialize the transaction, you'll need to pass information such as email, first name, last name amount, oder_id, etc.

The customer information can be retrieved from your database, session or cookie if you already have it stored, or from a form like in the example below.

<form action="/save-order-and-pay" method="POST"> 
    
    <input type="hidden" name="email" value="<?php echo $email; ?>"> 
    
    
    <input type="hidden" name="first_name" value="<?php echo $first_name; ?>"> 
    <input type="hidden" name="last_name" value="<?php echo $last_name; ?>"> 
    
    <input type="hidden" name="amount_charge" value="<?php echo $amount; ?>"> 
    
    <input type="hidden" name="order_id" value="<?php echo $order_id; ?>"> 
    
    <button type="submit" name="pay_now" id="pay-now" title="Pay now">Pay now</button>

</form>

Initialize transaction

When a customer clicks the payment action button, initialize a transaction by making a POST request to our API. Pass the email, amount and any other parameters to the Initialize TransactionAPI endpoint.

If the API call is successful, we will return a URL which you will redirect to for the customer to input their payment information to complete the transaction and the transaction reference which you would use to verify the payment status.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://socialpay.socialconnector.io/api/v1/transaction/init-inline',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_POSTFIELDS =>'{
    "public_key": "PUBLIC_KEY",
      "order_id" : "REV_508587108281",
      "first_name": "Tes",
    "last_name": "Sal",
        "email": "[e-mail]",
        "phone": "[phone]",
      "fee_bearer": "client",
      "amount_charge": "5.00",
      "custom_fields": [
          {
              "shipping_address": "San jones"
          }
      ],
      "cryptocurrency_type": "$DEV",
      "redirect_url": "https://your_website.com?order=order_id"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Verify Transaction

If the transaction is successful, Social Pay will redirect the user back to a redirect_url you set. . In the example above, the user will be redirected to. https://your_website.com?order=order_id use the order id to retrieve the transaction reference that was sent earlier and use that to call the verify endpoint to confirm the status of the transaction.

It's very important that you call the Verify endpoint to confirm the status of the transactions before delivering value. Just because the redirect_url was visited doesn't prove that transaction was successful.