API Reference

Introduction

The MyUser API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the MyUser API in test mode, which does not affect your live data. The API key you use to authenticate the request determines whether the request is live mode or test mode.

API libraries Official libraries for the MyUser API are available in several languages.

Setup

Library Installation

Download php library from here Download

npm i myuserpay --save

To setup you need to do just 4 things:

• Sign up to get API Keys from here

• Finish all steps in dashboard

• Install Library of your preferred language

• Copy Paste 2 blocks of codes from this documentation.

Official libraries for the MyUser API are available in several languages. You can install our libraries via codes or from links below:

JavaScript (Node.js): https://github.com/myuserHQ/myuserpay-node/archive/master.zip

PHP: https://github.com/myuserHQ/myuserpay-php/archive/main.zip

Authentication

Example request:

$ curl https://api.myuser.com/pay/v1/balance \
  -u your_private_key:
    # The colon prevents curl from asking for a password.

<?php 
use \MyUser\MyUserPay;
include 'MyUserPay/init.php'; //path/to/MyUserPay library
MyUserPay::setPrivateKey('your_private_key');

const myuserpay = require('./myuserpay')('your_private_key');

The MyUser API uses API keys to authenticate requests. You can view and manage your API keys in the MyUser Dashboard.

Test mode secret keys have the prefix sk_test_, public keys have the prefix pk_test_, and live mode secret keys have the prefix sk_live_, public keys have the prefix pk_live_.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

Errors

Example error response:

{
"status":false,
"error":{
    "message":"Description of error"
    }
}

Handling errors:

<?php 
//any library function, process will contain json
$process = MyUserPay::get_balance(); //any library function
if($process['status']){
    //success
}else{
    //error
    echo $process['error']['message'];
}

//any library function, process will contain json
const res =  myuserpay.get_balance().then(function (response) {
   if(response.status){
     //success
   }else{
     //error
     console.log(response.error.message);
   }
});

The MyUser API always returns json object, and inside of it, there always will be status variable. If status is not true, there will be an error object: "error":{"message":"Description of error"}. You can use this object to show the error.

Payment Button

Adding button:

<form   action="your-server-side-code" method="post"  >
 <script 
    src="https://api.myuser.com/js/checkout.js" 
    class="myuserPay-button" 
    data-public_key="your_public_key"
    data-amount="10000"
    data-description="description of item"
    data-name="Item name" 
    data-image="Item or your picture,logo"
    data-submit-ajax="1">
 </script>
</form>

There are two integration ways. One is a button, and another is inline integration. This section will explain button integration. Copy html code, and put it into the page that you want to charge your customer. This will insert button inside of the form.

How it works

<form   action="your-server-side-code" method="post"  >
 <div 
    class="myuserPay-button" 
    data-public_key="your_public_key"
    data-amount="10000"
    data-description="description of item"
    data-name="Item name" 
    data-image="Item or your picture,logo"
    data-submit-ajax="1">
 </div>
</form>

<script type="text/javascript" src="https://api.myuser.com/js/checkout.js" ></script>

Using Button Attributes, you can customize what users see as a button text, amount, item image, description when they pay. You can also set email which will be used to inform them about payment, change the behavior of button such as making it subscription payment, or submitting payment using ajax instead of loading new page.

Button Attributes

Attribute	Description
data-submit-ajax	If you set this to 1, form will be submitted via ajax, otherwise will be submitted without ajax.
class	This should be myuserPay-button.
data-public_key	Insert your public key here to authorize.
data-amount	It shows how many cents you will charge user. (100 = $1.00). Calculate your currency and convert it into cents.
data-amount_string	Setting this attribute will allow you to show custom string to the user when they pay. You can use this function to show users how much in which currency they will be charged. In Payment page it will work like this: Pay {data-amount_string}. E.g., Pay 50 EURO, but user will pay data-amount cents. Make sure they are equal.
data-email	This allows you to set email address for customers and should be valid email. MyUser will use this attribute to prevent you from chargebacks
data-name	This should be the name of your business that customers will recognize. They will see it after they click to pay.
data-description	Please write description of product, or if not possible, just general description of user's payment.
data-image	Set it to url of image of the product or your business's logo.
data-verify	This param should be used when you only want to verify the card instead of charging it. For now, this only accepts "verify_card" string, and then it will verify the card.
data-no-button	This will hide the button completely, and will allow you to create your own button.

Setup Subscriptions

<form   action="your-server-side-code" method="post"  >
 <script 
    src="https://api.myuser.com/js/checkout.js" 
    class="myuserPay-button"
    data-public_key="your_public_key"
    data-amount="10000"
    data-description="description of item"
    data-name="Item name" 
    data-image="Item or your picture,logo"
        data-subscription="true"
        data-subs_trial_days="14"
        subs_package_name="Company X PRO PLAN"
        data-subs_plan="monthly"
        data-button-text="Subscribe"
    data-submit-ajax="1">
 </script>
</form>

Attributes below should be used to create subscription (e.g. user pay each month/year) charges, but also in the back you should send them in charge method.

Attribute	Description
data-subscription	It takes true/false . If you set it to true, you will activate subscription mode, which means the user will pay monthly or yearly, not a one-time payment.
data-subs_trial_days	In subscription mode, you can use this attribute to set trial days for users, so they will not pay until that time. E.g., if you set this to 7, they will be charged after 7 days.
data-subs_plan	It takes monthly/yearly. Right after the first trial, it will begin to charge customers monthly/yearly.
subs_package_name	What is the package - item - name that customer will subscribe for.

Customization & Callbacks

<form   action="your-server-side-code" method="post">
 <button data-amount="100"
    class="myuserPay-button" 
    data-button-text="Button 1"></button>
</form>
<form   action="your-server-side-code" method="post">
 <button data-amount="200"
    class="myuserPay-button" 
    data-button-text="Button 2"></button>
</form>
<script src="https://api.myuser.com/js/checkout.js" 
    data-public_key="your_public_key"
    data-description="description of item"
    data-name="Company Name" 
    data-image="Your logo url"
    data-submit-ajax="1" >
 </script><script>MyUserPay.render_buttons();</script>

You can build your own button designs, create multiple payment button in one page or let users enter the amount to pay using callbacks in javascript - MyUserPay Object.

Our javascript library (script tag you called) always gives you MyUserPay Javascript object that you can use to control payment flow, callbacks.

Multiple Buttons

If you need more than one button just add button code multiple times, and then use MyUserPay.render_buttons(); function at the end.

Callbacks

<script type="text/javascript">
MyUserPay.onModalClose(function(form_id,myuserPay_response,user_did){
  if(user_did){
    console.log('user clicked close button and payment windows closed');
  }else{
    console.log('payment window closed because user finished payment successfully');
  }
});


MyUserPay.onPaymentSucceed(function(form_id,MyUserToken){
  //if you add here return false, 
  //our API will not submit the form
    //so you can store MyUserToken, and sent it to backend later
});
</script>

To build custom functionality, you can use callbacks as MyUserPay.on{EventName}. form_number argument will be included in each function which represent, in which form event happened. Here is the list of callbacks you can use:

Function	Arguments	Description
MyUserPay.onButtonReady	form_number	This function will be called when button that is connected to form_number is rendered.
MyUserPay.onModalClose	form_num, user_did, server_data	This function will be called when modal (Our Payment Screen) is closed. If user_did is true, then the user closed the Modal; otherwise, it closed automatically because the user made a successful purchase.
MyUserPay.onPaymentSucceed	form_num, MyUserToken	This function will be called when modal is closed, and we prepare the form data to submit to your server. If you add return false; inside of it, the form will not be submitted. You can take MyUserToken and send it to your backend to collect the payment - if you didn't add return false; we will send it to your backend automatically.
MyUserPay.onAjaxSuccess	form_num, your_server_data	This Ajax Request will happen only when you set data-submit-ajax=1 and will be called when request to your server is successful.
MyUserPay.onAjaxFailed	form_num	This Ajax Request will happen only when you set data-submit-ajax=1 and will be called when request fails due to your server errors.

Custom Buttons

Example of custom amounts and buttons:

<input class="bluef inputtext" type="text" max="99999999" 
name="" placeholder="Enter Amount" onkeyup="
var amount_val = $(this).val();
var max_amount = 99999999;
if(!$.isNumeric(amount_val) && $.trim(amount_val)!='' ){
amount_val=old_typed_money;
$(this).val(old_typed_money);
}
if(parseInt(amount_val)>max_amount){
$(this).val(old_typed_money);
amount_val=old_typed_money;
}
if($.trim(amount_val)==''){
amount_val=0;
}
old_typed_money=amount_val;
MyUser_amountInCents=amount_val*100;
$('.myuserPay-button').attr('data-amount',MyUser_amountInCents);
$('.CustommyuserForm').attr('action','your-server-url'+'?value='+MyUser_amountInCents);
                                    ">
<form action="your-server-url?value=0" class="CustommyuserForm" method="post">
<script src="https://api.myuser.com/js/checkout.js" class="myuserPay-button"
data-public_key="your_public_key" data-amount="0"
data-description="Enter Card Details" data-name="Company Name" 
data-submit-ajax="1" data-no-button=true>
                                    </script>

<div  onclick="myuserPay_openPaymentModal(1);event.preventDefault();"  class="btndiv">
<button class="btnpop">Increase Balance</button></div>
                                    </form>

You can build your own payment button from scratch with your own rules.

1) Add data-no-button attribute into the element that have myuserPay-button class.

2) Build your button and as an onclick event add myuserPay_openPaymentModal(form_num). form_num should be the number of form; You can see it by just refreshing the page once and looking at HTML code from browser console.

Additionally, if you want to use JSON data to create fields for payment form submission you can use MyUserPay.addFields(JSON_DATA,form_num,{'input_type':'hidden|text'});.

Inline Integration

There are two integration ways. One is a button, and another is inline integration. This section will explain inline integration.

Usually, inline integrations should be inside of some form, so you can submit it to the server. Purpose of this integration is token that will be generated from payment information, so you can add it to the form and then send it to your server to process payment. You need to have one <div></div> element, and with CSS, it should look like all other input fields. Then let's give it some random id called a. Our iframe will be inside of it.

<style type="text/css">
    #a{margin-bottom: 4px;
    height: 16px;
    padding: 8px;
    border-radius: 2px;
    box-shadow: 0 1px 2px rgba(0,0,0,0.16), 0 1px 2px rgba(0,0,0,0.23);
    border-top: 1px solid #ccc;
        width: 260px;
    }
   </style>

<form>

<div id="a"></div>
<button id="example_submit_button"
onclick="
//we will add code here later.
"
>Submit</button>
</form>

Setup Scripts

Now we need to add script tags, set API key, and insert iframe.

<script src="https://api.myuser.com/js/checkout.js"></script>
<script type="text/javascript">
    var style='body{}'; //insert style tag inside of iframe.
    MyUserPay.setKey('your_public_key');
    var element_num = MyUserPay.createElement('#a',{style:style,amount:100});
    //We will use element_num to create token for that specific element
</script>

Create Token

Now when customer clicks submit button on the form, we need to create the token, and then insert it to the form as an hidden input name MyUserToken.

<button id="example_submit_button"
onclick="

MyUserPay.createElementToken(element_num,function(data){

        if(data.status){
            //success
            //data.token is MyUserToken that you can use to process charges; you need to insert it into this form.
      //then submit the form. Please look at the Charges section to see what to write on the server-side.
        }else{
          //error
            //you can receive error message using data.error.message, then show it to the user.
        }
    });
"
>Submit</button>

Charges

Charging user, considering form method was post:

$ curl https://api.myuser.com/pay/v1/charges \
  -u your_private_key:
    -d token="exampleTokenasiqwysaysnUAas_1"
    -d amount=10000
    # The colon prevents curl from asking for a password.

<?php 
use \MyUser\MyUserPay;
include 'MyUserPay/init.php'; //path/to/MyUserPay library
MyUserPay::setPrivateKey('your_private_key');


$process = MyUserPay::charge(
array(
'amount'=>10000,
//If request was post
'token'=>$_POST['MyUserToken'],
)
);
if($process['status']){
//success
$charge_id = $process['id'];
}else{
//error
echo $process['error']['message'];
}

const myuserpay = require('./myuserpay')('your_private_key');

const res =  myuserpay.charge({
//If request was post, and request.body contains post data
token:request.body.MyUserToken,
amount:10000,
}).then(function (response) {
   if(response.status){
       //success
     console.log(response.id);
   }else{
       //error
     console.log(response.error.message);
   }
});

Create a file that your server-side codes will run (the file URL should be the same with action attribute of form tag).

Charge Function

Here is charge function params:

Parameter	type	Description
token	required	token of the charge that came from payment form submission.
amount	required	it shows how much money you want to charge. It should match with front end code.
verify	optional	Accepts verify_card, and when you do that, it will not charge the card, it will just verify that it is valid card.
subscription	optional	It could be true/false. Default is false which means one time charge. If you set it to true, user will pay each month/year.
subs_plan	required if subscription is true	It accepts monthly/yearly. Right after the first trial, it will begin to charge customers monthly/yearly. It should be the same with frontend's - button's - data-subs_plan attribute.
trial_days	optional	In subscription mode, you can use this attribute to set trial days for users, so they will not pay until that time. E.g., if you set this to 7, they will be charged after 7 days. It should be the same with frontend's - button's - data-subs_trial_days attribute.
triggers	optional but strongly recommended if subscription is true	In subscription mode, you should send trigger array/object. It will send you request, if trial ended, request failed, or successed.
triggers.success_url	optional	the url that we will send request when customer paid subscription fee for next month/year.
triggers.success_custom_data	optional	custom data you want us to send on successful payment
triggers.fail_url	optional	url that we will inform you when customer failed to pay subscription fee for next month/year.
triggers.fail_custom_data	optional	custom data you want us to send on failed payment
triggers.trial_end_url	optional	the url that we will send request when trial ends.
triggers.trial_end_custom_data	optional	custom data for trial end requestes.

Response Explanation

Example response from our server for successful charge:

{
  "status": true,
  "id": "ch_84.5730ceeb6d96ea1d1ab0e455eadf3b47",
  "card_id": "card_",
  "currency": "usd",
  "amount": 10000,
  "profit": 9630,
  "profit_in_bonus": 370,
  "paid": true,
  "email": "[e-mail]",
  "created": "1552213902",
  "live": false,
  "source": {
        "type":"card",
    "brand": "Visa",
    "country": "US",
    "last4": "4242",
    "exp_month": 4,
    "exp_year": 2042,
    "funding": "credit",
    "cvc_check": "pass"
  }
}

Parameter	Description
status	could be true/false . If it is true, there is no error.
id	This shows the ID of the charge, and you can use it to issue refund, or cancel subscription (if it is subscription payment) for this specific charge.
card_id	This is id of the card that is being charged. It will return card_id when you do verify_card request, and you will be able to use that card number when you send payment in the future. Soon we will allow you to store card_id to charge them later.
currency	in which currency charge is being made.
profit_in_bonus	How much bonus points, MyUser helped you to earn.
paid	It could be true/false. It could be false when you do subscription charge, and allow user not to pay upfront.
live	Request mode; false means test mode.
source	source of the charge. This is the object that shows details of the source.
source.type	this shows type of the source. E.g. card, paypal, ach.
source.funding	If source.type was card, then source.funding represents card type: credit/debit.

Refunds

Refund:

$ curl https://api.myuser.com/pay/v1/refunds \
  -u your_private_key:
    -d charge="ch_84.5730ceeb6d96ea1d1ab0e455eadf3b47"

<?php 
use \MyUser\MyUserPay;
include 'MyUserPay/init.php'; //path/to/MyUserPay library
MyUserPay::setPrivateKey('your_private_key');

//charge_id comes from charge functions.
$charge_id = "ch_84.5730ceeb6d96ea1d1ab0e455eadf3b47"; 
//if amount is not defined, it will do full refund.
$process = MyUserPay::refund({charge:$charge_id,amount:1000});
if($process['status']){
//success;
}else{
//error
echo $process['error']['message'];
}

const myuserpay = require('./myuserpay')('your_private_key');

//charge_id comes from charge functions.
charge_id = "ch_84.5730ceeb6d96ea1d1ab0e455eadf3b47"; 
//if amount is not defined, it will do full refund.
const res =  myuserpay.refund({charge:charge_id,amount:1000}).then(function (response) {
   if(response.status){
       //success
   }else{
       //error
     console.log(response.error.message);
   }
});

{
  "status": true
}

Doing refund is easy, you just need charge id that got when using charge function, and how much cents you want to refund.

Subscriptions

FrontEnd example code:

<form   action="your-server-side-code" method="post"  >
 <script 
    src="https://api.myuser.com/js/checkout.js" 
    class="myuserPay-button"
    data-public_key="your_public_key"
    data-amount="10000"
    data-description="description of item"
    data-name="Item name" 
    data-image="Item or your picture,logo"
        data-subscription="true"
        data-subs_trial_days="14"
        subs_package_name="Company X PRO PLAN"
        data-subs_plan="monthly"
        data-button-text="Subscribe"
    data-submit-ajax="1">
 </script>
</form>

Backend example code:

$ curl https://api.myuser.com/pay/v1/charges \
  -u your_private_key:
    -d token="exampleTokenasiqwysaysnUAas_1"
    -d amount=10000
    -d subscription=true
    -d subs_plan=monthly
    -d triggers[success_url]='http://example.com/webhooks?success=true'
    -d triggers[success_custom_data][user_id]='custom_id'
    -d triggers[fail_url]='http://example.com/webhooks?fails=true'
    -d triggers[fail_custom_data][user_id]='custom_id'
    -d triggers[trial_end_url]='http://example.com/webhooks?trialend=true',
    -d triggers[trial_end_custom_data][user_id]='custom_id'

<?php
use \MyUser\MyUserPay;
include 'MyUserPay/init.php'; //path/to/MyUserPay library
MyUserPay::setPrivateKey('your_private_key');

$process = MyUserPay::charge(
array(
'amount'=>10000,
//If request was post
'token'=>$_POST['MyUserToken'],
'subscription'=>true,
'subs_plan'=>'monthly',
'triggers'=>array(
    'success_url'=>'http://example.com/webhooks?success=true',
    'success_custom_data'=>array('user_id'=>'custom_id'),
    'fail_url'=>'http://example.com/webhooks?fails=true',
    'fail_custom_data'=>array('user_id'=>'custom_id'),
    'trial_end_url'=>'http://example.com/webhooks?trialend=true',
    'trial_end_custom_data'=>array('user_id'=>'custom_id'),
),
  ));
if($process['status']){
//success
$charge_id = $process['id'];
}else{
//error
echo $process['error']['message'];
}

const myuserpay = require('./myuserpay')('your_private_key');

const res =  myuserpay.charge({
//If request was post, and request.body contains post data
token:request.body.MyUserToken,
amount:10000,
'subscription':true,
'subs_plan':'monthly',
'triggers':{
    'success_url':'http://example.com/webhooks?success=true',
    'success_custom_data':{'user_id'=>'custom_id'},
    'fail_url':'http://example.com/webhooks?fails=true',
    'fail_custom_data':{'user_id'=>'custom_id'},
    'trial_end_url':'http://example.com/webhooks?trialend=true',
    'trial_end_custom_data':{'user_id'=>'custom_id'},
},

}).then(function (response) {
   if(response.status){
       //success
     console.log(response.id);
   }else{
       //error
     console.log(response.error.message);
   }
});

Setting up subscription is easy, it is just putting extra attributes/argument into payment button, and charge function.

1) Setting up Subscription button - click to get codes

2) Adding extra params in charge function - click to learn more

3) Do verification for triggers to make sure request came from MyUser servers. - click to learn more

Request Verifications

Request Verification:

$ curl /webhooks/?action=verify \
  -u your_private_key:
    -d request_id="{request_id}"

<?php 
use \MyUser\MyUserPay;
include 'MyUserPay/init.php'; //path/to/MyUserPay library
MyUserPay::setPrivateKey('your_private_key');

$json = file_get_contents('php://input');
$request = json_decode($json, true);

$verify_for='subscription';
$process = MyUserPay::verify_webhook($request['request_id'],$verify_for);

if($process['status']){
//we sent the request
}else{
//some else sent the request
}

const myuserpay = require('./myuserpay')('your_private_key');

var verify_for='subscription';
const res =  myuserpay.verify_webhook({request.body.request_id,verify_for}).then(function (response) {
   if(response.status){
      //we sent the request
        }else{
        //some else sent the request
        }
});

Example response will be status false or true:

{
  "status": true
}

When we send you webhook (E.g., when subscription fails), you need to make sure that request came from us, if it didn't, you should block it. You can use our library to verify the request easily.