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": "[email protected]",
"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.