Templates and Subscriptions

Templates 

Aim: to store data for semi- or automatic payment execution. 

Template types 

There are types of templates in the system: 

1. Transfer template
2. Invoice template
3. Cart & purchase template

1. Transfer template 

DB table name: template_transfer 

1.1. Create transfer template 

There two options how  to create transfer template: 

by operation id 

basic way 

1.1.1 Transfer Template by operation id 

All required payment data are taken from the operation data 

permissions: TEMPLATES_OWNER 

POST /templates/transfer/operation/{operationId} 

1.1.2 Transfer Template basic way 

All payment data should be pasted. 

reusable – parameter shows if the template can be used in more than one subscription.  Value: true | false 

paymentTool – this section contains the required payment data.  

There are two types (type): COIN | SMART_CARD.  

According tho this types in srcValue and destValue should be pasted different values: 

for type COIN it should be the coin serial numbers 

for type SMART_CARD it should be the smart card numbers 

permissions: TEMPLATES_OWNER 

POST /templates/transfer 

1.2. Retrieve transfer templates 

There are two options to obtain templates: 

get all transfer templates 

get all templates with filter and pagination 

1.2.1 Get all transfer templates 

permissions: TEMPLATES_OWNER

GET /templates/transfer 

1.2.2 Get all templates with filter and pagination 

permissons: TEMPLATES_OWNER 

POST /templates/transfer/view 

1.3. Update transfer templates 

permissions: TEMPLATES_OWNER 

PATCH /templates/transfer/{id} 

1.4. Delete transfer templates 

permissions: TEMPLATES_OWNER 

DELETE /templates/transfer/{Id}

1.5. Manual payment execution 

1.5.1 Calculate payment fee by transfer template 

permissions: TEMPLATES_OWNER 

POST /templates/transfer/{Id}/calculate 

1.5.2 Execute payment fee by transfer template 

permissions: TEMPLATES_OWNER 

POST /templates/transfer/{Id}/execute

2. Invoice template 

DB table name: template_invoice 

3. Cart & purchase template

DB table name: template_cart, template_purchase 

Subscriptions 

Responsibility: to manage the regular executions of payments. 

DB table name: subscription, subscription_definition 

Related entities: 

Period: Templates & Subscriptions | Periods 

Subscription statuses: 

ACTIVE – subscription in progress, intermediate state 

STOPPED – stopped subscription; intermediate state, can switch to ACTIVE 

PROCESSED – finished subscription, terminate state 

CANCELLED – exceptionally finished subscription, terminate state 

Expiration Type (field expirationType): 

The type of ending the subscription 

DATE – by date – regular payment is executed until the required date (field endDate) 

INFINITY – there are no constraints on regular payment executions 

COUNT – by reaching required successfully executed payments (field count) 

e.g.: stop subscription after reaching N number of successfully executed payments 

AMOUNT – by reaching required amount of payments (field amount) 

e.g.: required to pay $60 by $20 payments, it means that subscription will be processed after 3 times of successful executions Recurring Type (field type) 

DAILY – daily subscription execution 

WEEKLY – weekly subscription execution 

MONTHLY – monthly subscription execution 

ANNUALLY – annually subscription execution 

Amount (field amount) – amount of payments to be reached. 

Requires for expirationType = AMOUNT 

Count (field count) – number of successfully executed payments. Default value is 1. 

Requires for expirationType = COUNT 

End Date (field endDate) – end date of subscription.  

Requires for expirationType = DATE 

Recurring Start Date (field recurringStartDate) – start date of subscription 

Frequency (field frequency) – max number of execution attempts among the period (according to recurring type) after fail execution. Default  value is 1. 

Template ID (field templateId) – template ID which contains the information of payment execution 

Subscriptions settings:

subscription:   remove-after-complete:   enable: false   subscription-timer:   enabled: true   schedule-expression: ‘0 * * ? * *’ # cron expression   notification:   enable: false

Subscription APIs: 

1. Create Subscription 

Create Subscription with expiration type COUNT COUNT 

mandatory field: count

POST /subscriptions 

After creating the Subscription status is ACTIVE 

Possible options of creating Subscription requests according to other expiration types: 

AMOUNT 

mandatory field: amount

DATE 

mandatory field: endDate 

INFINITY 

there are no mandatory fields 

2. Retrieve Subscription 

permissions:  

 there are no permissions 

GET /subscriptions 

3. Update Subscription 

3.1. Activate subscription 

Only Subscription in status STOPPED could be activated 

permissions:  there are no permissions

PATCH /subscriptions/{Id}/activate 

After activating the Subscription status becomes ACTIVE 

3.2. Stop subscription 

Only Subscription in status ACTIVE could be stopped 

After stopping the Subscription status becomes STOPPED 

4. Delete Subscription 

Only Subscription in status STOPPED could be deleted 

permissions:

DELETE /subscriptions/{Id} 

After deleting the Subscription status becomes CANCELED 

Periods 

Responsibility: to store the next execution date for related Subscription. 

DB table name: subscription_period, subscription_period_definition 

Period statuses: 

SCHEDULED – when Subscription was created and a new execution date was arranged 

FAILED – period was stoped because of exception case 

STOPPED – when Subscription is stopped 

PROCESSED – when the regular payment attempt was successfully finished 

CANCELED – when Subscription in status CANCELED 

Process period on (field processPeriodOn) – date when related subscription should be executed. 

The value of processPeriodOn compiles  

1. When Subscription is created the processPeriodOn is the recurringStartDate 
2. When Subscription is activated or arranging a next execution time the processPeriodOn computes by Subscription frequency value and last Process Date according to the Subscription type

private static OffsetDateTime calculateNewDateForPayment(Subscription  subscription,   OffsetDateTime  lastProcessDate) {   int counter = subscription.getFrequency();   switch (subscription.getType()) {   case DAILY:   return lastProcessDate.plusDays(counter);   case WEEKLY:   return lastProcessDate.plusWeeks(counter);   case MONTHLY:   return lastProcessDate.plusMonths(counter);   case ANNUALLY:   return lastProcessDate.plusYears(counter);   default:   throw new IllegalArgumentException(“period not implemented”);  }  }