Version 1.0
Remote API - version 1.0
The Remote API allows you to connect multiple myCred installations running on separate websites by sending action requests between them. You could use this to query a users balance on a different site or make remote transactions by for example building a payment gateway that myCred manages.
Note that the Remote API requires WordPress permalinks to be enabled.
All examples given in this documentation will be using the built-in functions that WordPress offers for convenience. You can use your own functions if you prefer.
Structure
The myCred Remote API is managed by the myCred_Remote class located in the includes directory of your myCred installation. This class comes with a large set of action and filter hooks which allows you to add / customize it’s functionality.
Remote API Setup
The remote API can be enabled / changed in your admin area by visiting the myCred > Settings page. If you do not see the “Remote API” tab, click on “Management” and make sure the checkbox is selected for “Enable the Remote API”. Click “Save Changes” and you now should have the “Remote API” tab available with a red icon (off). Enter your secret key or click “Generate Key” and set the URL address where API calls are to be accepted from. Calls made to any other URL will be ignored. Click “Save Changes” and your icon should now be green (on).
Supported Methods
The current version of the remote API supports GET, POST and JSON methods for communication between sites.
Supported Actions
GET
Retrieve a users current balance.
CREDIT
Add points to a users current balance.
DEBIT
Deduct points from a users balance.
PAY
Transfer points from one user to another.
Identifying Users
The remote api uses email addresses to identify users. This means that the user registered on site A must have registered with the same email address on site B in order for us to be able to get their balance from the other site.
Security Token
To prevent users to execute mischievous requests on your sites, each request must contain a security token. This security token is a md5 hash of the request combined with the secret key that you have to setup in order to use the API.
This means that all sites that are to be connected must be setup to use the same secret key! If you change the key on one website, you must change it on all other sites as well.
Action: GET
The GET action allows you to query a specific users balance.
You can use this to display a users balance from another site or to sync two or more sites to always have the same point balance. In order to query a users balance, you must provide the users email address as a minimum. If you are using myCred 1.4 or higher, you can also use the type attribute to request a specific point type balance.
For the GET action, you must hash the host, action and your secret key.
You can consult the myCred_Remote class documentation for error codes.
Example
$secret_key = 'mysecretkey';
$remote_url = 'http://siteb.com/api/';
$action = 'GET';
$account = 'john.doe@email.com';
$point_type = 'my_custom_type';
$host = get_bloginfo( 'url' );
$token = md5( $host . $action . $secret_key );
$request = array(
'method' => 'POST',
'body' => array(
'action' => $action,
'account' => $account,
'type' => $point_type,
'token' => $token,
'host' => $host
)
);
Response
0.00
The amount formatted according to your sites myCred setup.
Action: CREDIT
The CREDIT action allows you to add points to a users account. It works the same way as the mycred_add function meaning you are required to provide a reference, the amount of points and a log entry at minimum in order for points to be awarded. Reference ID, point type (requires myCred 1.4 or higher) and data is optional.
For the CREDIT action, you must hash host, action, amount and your secret key.
You can consult the myCred_Remote class documentation for error codes.
Example
$secret_key = 'mysecretkey';
$remote_url = 'http://siteb.com/api/';
$action = 'CREDIT';
$account = 'john.doe@email.com';
$amount = 10;
$ref = 'reference';
$ref_id = 0;
$entry = 'Points for viewing video';
$data = 'optional extra';
$point_type = 'my_custom_type';
$host = get_bloginfo( 'url' );
$token = md5( $host . $action . $amount . $secret_key );
$request = array(
'method' => 'POST',
'body' => array(
'action' => $action,
'account' => $account,
'amount' => $amount,
'ref' => $ref,
'ref_id' => $ref_id,
'type' => $point_type,
'entry' => $entry,
'data' => $data,
'token' => $token,
'host' => $host
)
);
$response = wp_remote_post( $remote_url, $request );
Response
Note that all response codes are submitted in capital letters and are not translatable.
DUPLICATEYour attempt has been executed before and is considered to be duplicate. You should utilize the data variable to make each entry unique.COMPLETEDThe transaction was successfully completed.FAILEDFailed to transfer the funds. Note that the myCred_add filter is used here twice. Once when the amount is deducted from the sender and once when the amount is credited to the recipients account.
Action: DEBIT
The DEBIT action allows you to deduct points to a users account. It works the same way as the myCred_subtract function meaning you are required to provide a reference, the amount of points and a log entry at minimum in order for points to be awarded. Reference ID, point type (requires myCred 1.4 or higher) and data is optional.
For the DEBIT action, you must hash host, action, amount and your secret key.
You can consult the myCred_Remote class documentation for error codes.
Example
$secret_key = 'mysecretkey';
$remote_url = 'http://siteb.com/api/';
$action = 'DEBIT';
$account = 'john.doe@email.com';
$amount = -10;
$ref = 'reference';
$point_type = 'my_custom_type';
$ref_id = 0;
$entry = 'Payment for movie tickets';
$data = 'optional extra';
$host = get_bloginfo( 'url' );
$token = md5( $host . $action . $amount . $secret_key );
$request = array(
'method' => 'POST',
'body' => array(
'action' => $action,
'account' => $account,
'amount' => $amount,
'ref' => $ref,
'ref_id' => $ref_id,
'type' => $point_type,
'entry' => $entry,
'data' => $data,
'token' => $token,
'host' => $host
)
);
$response = wp_remote_post( $remote_url, $request );
Response
Note that all response codes are submitted in capital letters and are not translatable.
DUPLICATE
Your attempt has been executed before and is considered to be duplicate. You should utilize the data variable to make each entry unique.DECLINED
The requested amount exceeds the amount a user has on their account. Note that the myCred_transfer_acc_limit filter is used here.COMPLETED
The transaction was successfully completed.FAILED
Failed to transfer the funds. Note that the myCred_add filter is used here twice. Once when the amount is deducted from the sender and once when the amount is credited to the recipients account.
Action: PAY
The PAY action allows you to transfer money from one account to another. First the user defined under the account variable is deducted the given amount and then added to the recipients account. You define the recipient under the to variable.
For the PAY action, you must hash host, action, amount, account, to and your secret key.
Example
$secret_key = 'mysecretkey';
$remote_url = 'http://siteb.com/api/';
$action = 'PAY';
$from = 'john.doe@email.com';
$amount = 10.50;
$to = 'sara@email.com';
$ref = 'reference';
$ref_id = 0;
$entry = 'Payment for order #1234';
$data = 'optional extra';
$point_type = 'my_custom_type';
$host = get_bloginfo( 'url' );
$token = md5( $host . $action . $amount . $from . $to . $secret_key );
$request = array(
'method' => 'POST',
'body' => array(
'action' => $action,
'account' => $from,
'amount' => $amount,
'to' => $to,
'ref' => $ref,
'ref_id' => $ref_id,
'type' => $point_type,
'entry' => $entry,
'data' => $data,
'token' => $token,
'host' => $host
)
);
$response = wp_remote_post( $remote_url, $request );
Response
Note that all response codes are submitted in capital letters and are not translatable.
DUPLICATE
Your attempt has been executed before and is considered to be duplicate. You should utilize the data variable to make each entry unique.DECLINED
The sender does not have enough points to fulfill this transaction. Note that the myCred_transfer_acc_limit filter is used here.COMPLETED
The transaction was successfully completed.FAILED
Failed to transfer the funds. Note that the myCred_add filter is used here twice. Once when the amount is deducted from the sender and once when the amount is credited to the recipients account.
