Subscriptions
For this tutorial we will see how to create a subscription to charge periodically a service to a customer.
Say you have a service where you offer a one month trial and then you charge a monthly fee of $ 99.99 pesos indefinitely (or until your customer cancels the service).
You have to do the following:
Create a plan
Create customer
Save card
Subscribe customer
Create a plan
A plan is a template for a subscription that contains the cost, charge frequency, trial period, etc.
To create a plan we have two options:
Option 1.- Creation from the API
curl -u sk_e568c42a6c384b7ab02cd47d2e407cab \
-H "Content-type: application/json" \
-X POST -d '{
"amount":99.99,
"status_after_retry":"cancelled",
"retry_times":2,
"name":"Servicio de TV",
"repeat_unit":"month",
"trial_days":30,
"repeat_every":1
}' https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/plans
<?
$openpay = Openpay :: getInstance ( 'mzdtln0bmtms6o3kck8f' , 'sk_e568c42a6c384b7ab02cd47d2e407cab' );
$planDataRequest = array (
'amount' => 150.00 ,
'status_after_retry' => 'cancelled' ,
'retry_times' => 2 ,
'name' => 'Plan Curso Verano' ,
'repeat_unit' => 'month' ,
'trial_days' => '30' ,
'repeat_every' => '1' ,
'currency' => 'MXN' );
$plan = $openpay -> plans -> add ( $planDataRequest );
?>
OpenpayAPI api = new OpenpayAPI ( "https://sandbox-api.openpay.mx" , "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Plan request = new Plan ();
request . name ( "Plan Curso Verano" );
request . amount ( new BigDecimal ( "150.00" ));
request . repeatEvery ( 1 , PlanRepeatUnit . MONTH );
request . retryTimes ( 2 );
request . statusAfterRetry ( PlanStatusAfterRetry . CANCELLED );
request . trialDays ( 30 );
request = api . plans (). create ( request );
OpenpayAPI api = new OpenpayAPI ( "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Plan request = new Plan ();
request . Name = "Plan Curso Verano" ;
request . Amount = new Decimal ( 150.00 );
request . RepeatEvery = 1 ;
request . RepeatUnit = "month" ;
request . RetryTimes = 2 ;
request . StatusAfterRetry = "cancelled" ;
request . TrialDays = 30 ;
request = api . PlanService . Create ( request );
var planRequest = {
'amount' : 150.00 ,
'status_after_retry' : 'cancelled' ,
'retry_times' : 2 ,
'name' : 'Plan Curso Verano' ,
'repeat_unit' : 'month' ,
'trial_days' : '30' ,
'repeat_every' : '1'
};
openpay . plans . create ( planRequest , function ( error , plan ){
// ...
});
@openpay = OpenpayApi . new ( "mzdtln0bmtms6o3kck8f" , "sk_e568c42a6c384b7ab02cd47d2e407cab" )
@plans = @openpay . create ( :plans )
request_hash = {
"name" => "Plan Curso Verano" ,
"amount" => 150 . 00 ,
"repeat_every" => "1" ,
"repeat_unit" => "month" ,
"retry_times" => 2 ,
"status_after_retry" => "cancelled" ,
"trial_days" => "30"
}
response_hash = @plans . create ( request_hash . to_hash )
You can have as many plans as you want. For example you can have a Gold, Platinum and Bronze plan for different levels of service.
If the request is successful we will have a response that contains the id
of the plan
Response:
{
"name" : "Servicio de TV" ,
"status" : "active" ,
"amount" : 99.99 ,
"currency" : "MXN" ,
"id" : "psjubnktzpofhakixfkp" ,
"creation_date" : "2014-02-14T13:47:55-06:00" ,
"repeat_every" : 1 ,
"repeat_unit" : "month" ,
"retry_times" : 2 ,
"status_after_retry" : "cancelled" ,
"trial_days" : 30
}
For more information about the plan parameters go to "Add Plan"
Option 2.- Creation from the dashboard
You can also create plans from the dashboard in Planes -> Agregar:
Create a customer
Now we’ll create the customer we want to subscribe:
curl -u sk_e568c42a6c384b7ab02cd47d2e407cab \
-H "Content-type: application/json" \
-X POST -d '{
"name":"Mi cliente uno",
"email":"micliente@gmail.com"
}' https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers
<?
$openpay = Openpay :: getInstance ( 'mzdtln0bmtms6o3kck8f' , 'sk_e568c42a6c384b7ab02cd47d2e407cab' );
$customerData = array (
'name' => 'Mi cliente uno' ,
'email' => 'micliente@gmail.com'
)
);
$customer = $openpay -> customers -> add ( $customerData );
?>
OpenpayAPI api = new OpenpayAPI ( "https://sandbox-api.openpay.mx" , "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Customer request = new Customer ();
request . name ( "Mi cliente uno" );
request . email ( "micliente@gmail.com" );
request = api . customers (). create ( request );
OpenpayAPI api = new OpenpayAPI ( "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Customer request = new Customer ();
request . Name = "Mi cliente uno" ;
request . Email = "micliente@gmail.com" ;
request = api . CustomerService . Create ( request );
var customerRequest = {
'name' : 'Mi cliente uno' ,
'email' : 'micliente@gmail.com'
};
openpay . customers . create ( customerRequest , function ( error , customer ) {
// ...
});
@openpay = OpenpayApi . new ( "mzdtln0bmtms6o3kck8f" , "sk_e568c42a6c384b7ab02cd47d2e407cab" )
@customers = @openpay . create ( :customers )
request_hash = {
"name" => "Mi cliente uno" ,
"email" => "micliente@gmail.com"
}
response_hash = @customers . create ( request_hash . to_hash )
Response:
{
"id" : "axapgwwolofnckfui2wx" ,
"name" : "Mi cliente uno" ,
"last_name" : null ,
"email" : "micliente@gmail.com" ,
"phone_number" : null ,
"status" : "active" ,
"balance" : 0 ,
"clabe" : "646180109400138692" ,
"address" : null ,
"creation_date" : "2014-02-14T12:30:09-06:00"
}
Save card
The next thing is to save the customer card to use for the subscription. We are going to fill the customer id
(axapgwwolofnckfui2wx) created earlier.
curl -u sk_e568c42a6c384b7ab02cd47d2e407cab \
-H "Content-type: application/json" \
-X POST -d '{
"card_number":"4111111111111111",
"holder_name":"Mi cliente uno",
"expiration_year":"20",
"expiration_month":"12",
"cvv2":"110"
}' https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/axapgwwolofnckfui2wx/cards
<?
$openpay = Openpay :: getInstance ( 'mzdtln0bmtms6o3kck8f' , 'sk_e568c42a6c384b7ab02cd47d2e407cab' );
$cardDataRequest = array (
'holder_name' => 'Mi cliente uno' ,
'card_number' => '4111111111111111' ,
'cvv2' => '123' ,
'expiration_month' => '12' ,
'expiration_year' => '15' );
$customer = $openpay -> customers -> get ( 'axapgwwolofnckfui2wx' );
$card = $customer -> cards -> add ( $cardDataRequest );
?>
OpenpayAPI api = new OpenpayAPI ( "https://sandbox-api.openpay.mx" , "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Card request = new Card ();
request . holderName ( "Mi cliente uno" );
request . cardNumber ( "4111111111111111" );
request . cvv2 ( "110" );
request . expirationMonth ( 12 );
request . expirationYear ( 20 );
request = api . cards (). create ( "axapgwwolofnckfui2wx" , request );
OpenpayAPI api = new OpenpayAPI ( "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Card request = new Card ();
request . HolderName = "Mi cliente uno" ;
request . CardNumber = "4111111111111111" ;
request . Cvv2 = "110" ;
request . ExpirationMonth = "12" ;
request . ExpirationYear = "20" ;
request = api . CardService . Create ( "axapgwwolofnckfui2wx" , request );
var cardRequest = {
'card_number' : '4111111111111111' ,
'holder_name' : 'JMi cliente uno' ,
'expiration_year' : '20' ,
'expiration_month' : '12' ,
'cvv2' : '110'
};
openpay . customers . cards . create ( 'axapgwwolofnckfui2wx' , cardRequest , function ( error , card ) {
// ...
});
@openpay = OpenpayApi . new ( "mzdtln0bmtms6o3kck8f" , "sk_e568c42a6c384b7ab02cd47d2e407cab" )
@cards = @openpay . create ( :cards )
request_hash = {
"holder_name" => "Mi cliente uno" ,
"card_number" => "4111111111111111" ,
"cvv2" => "110" ,
"expiration_month" => "12" ,
"expiration_year" => "20"
}
response_hash = @cards . create ( request_hash . to_hash , "axapgwwolofnckfui2wx" )
Response:
{
"type" : "debit" ,
"brand" : "visa" ,
"address" : null ,
"id" : "kokzmiiwephcdmq1h2qr" ,
"card_number" : "1111" ,
"holder_name" : "Mi cliente uno" ,
"expiration_year" : "20" ,
"expiration_month" : "12" ,
"allows_charges" : true ,
"allows_payouts" : true ,
"creation_date" : "2014-02-14T13:42:25-06:00" ,
"bank_name" : "Banamex" ,
"customer_id" : "axapgwwolofnckfui2wx" ,
"bank_code" : "002"
}
Subscribe Customer
Finally we create the subscription with the plan id
(psjubnktzpofhakixfkp) , the customer id
(axapgwwolofnckfui2wx) and the card id
(kokzmiiwephcdmq1h2qr) , thus the request would look like:
curl -u sk_e568c42a6c384b7ab02cd47d2e407cab \
-H "Content-type: application/json" \
-X POST -d '{
"card_id":"kokzmiiwephcdmq1h2qr",
"plan_id":"psjubnktzpofhakixfkp"
}' https://sandbox-api.openpay.mx/v1/mzdtln0bmtms6o3kck8f/customers/axapgwwolofnckfui2wx/subscriptions
<?
$openpay = Openpay :: getInstance ( 'mzdtln0bmtms6o3kck8f' , 'sk_e568c42a6c384b7ab02cd47d2e407cab' );
$subscriptionDataRequest = array (
"trial_end_date" => "2014-01-01" ,
'plan_id' => 'psjubnktzpofhakixfkp' ,
'card_id' => 'kokzmiiwephcdmq1h2qr' );
$customer = $openpay -> customers -> get ( 'axapgwwolofnckfui2wx' );
$subscription = $customer -> subscriptions -> add ( $subscriptionDataRequest );
?>
final Calendar trialEndDate = Calendar . getInstance ();
trialEndDate . set ( 2014 , 1 , 1 , 0 , 0 , 0 );
OpenpayAPI api = new OpenpayAPI ( "https://sandbox-api.openpay.mx" , "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Subscription request = new Subscription ();
request . planId ( "psjubnktzpofhakixfkp" );
request . trialEndDate ( trialEndDate . getTime ());
request . sourceId ( "kokzmiiwephcdmq1h2qr" );
request = api . subscriptions (). create ( "axapgwwolofnckfui2wx" , request );
OpenpayAPI api = new OpenpayAPI ( "sk_e568c42a6c384b7ab02cd47d2e407cab" , "mzdtln0bmtms6o3kck8f" );
Subscription request = new Subscription ();
request . PlanId = "psjubnktzpofhakixfkp" ;
request . TrialEndDate = new Datetime ( 2014 , 1 , 1 );;
request . CardId = "kokzmiiwephcdmq1h2qr" ;
request = api . SubscriptionService . Create ( "axapgwwolofnckfui2wx" , request );
var subscriptionRequest = {
'plan_id' : 'psjubnktzpofhakixfkp' ,
'source_id' : 'kokzmiiwephcdmq1h2qr' ,
'trial_end_date' : '2014-01-01' ,
};
openpay . customers . subscriptions . create ( "axapgwwolofnckfui2wx" , subscriptionRequest , function ( error , subscription ){
// ...
});
@openpay = OpenpayApi . new ( "mzdtln0bmtms6o3kck8f" , "sk_e568c42a6c384b7ab02cd47d2e407cab" )
@subscriptions = @openpay . create ( :subscriptions )
request_hash = {
"plan_id" => "psjubnktzpofhakixfkp" ,
"trial_end_date" => "2014-01-01" ,
"source_id" => "kokzmiiwephcdmq1h2qr"
}
response_hash = @subscriptions . create ( request_hash . to_hash , "axapgwwolofnckfui2wx" )
Response:
{
"status" : "trial" ,
"card" :{
"type" : "debit" ,
"brand" : "visa" ,
"address" : null ,
"id" : "kokzmiiwephcdmq1h2qr" ,
"card_number" : "1111" ,
"holder_name" : "Mi cliente uno" ,
"expiration_year" : "20" ,
"expiration_month" : "12" ,
"allows_charges" : true ,
"allows_payouts" : true ,
"creation_date" : "2014-02-14T13:42:25-06:00" ,
"bank_name" : "Banamex" ,
"customer_id" : "axapgwwolofnckfui2wx" ,
"bank_code" : "002"
},
"id" : "sfquvei5ya0lwdrd5blo" ,
"cancel_at_period_end" : false ,
"charge_date" : "2014-03-15" ,
"creation_date" : "2014-02-14T13:48:59-06:00" ,
"current_period_number" : 0 ,
"period_end_date" : "2014-03-14" ,
"trial_end_date" : "2014-03-14" ,
"plan_id" : "psjubnktzpofhakixfkp" ,
"customer_id" : "axapgwwolofnckfui2wx"
}
Ready, we have created the subscription, which will be automatically charged each month for $ 99.99 after trial period.
Notes:
You can simulate different results using the test cards
Implement Notifications to know the status of payments in real time