Home › Knowledge base › Templates and Subscriptions
Explore Knowledge Base

Templates and Subscriptions

29. 01. 2025

Templates

Responsibility: 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

1. Transfer template

DB table name: template_transfer

1.1. Create transfer template

There two options how 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

permissons: TEMPLATES_OWNER
POST
/templates/transfer/operation/{operationId}
Request:
{
 "name": "Test transfer template",
 "amount": 10,
 "description": "Transfer template",
 "reusable": true
}
Response:
{
 "status": "ok",
 "message": "processed successfully",
 "id": "301a84b1-fddb-47cf-82c5-1a1c4a181efe",
 "name": "Test transfer template",
 "senderCoin": {
 "serial": "143347556578",
 "name": "Test USD coin",
 "amount": 9990,
 "availableAmount": 9990,
 "futureAmount": 0,
 "heldAmount": 0,
 "creditLimit": 0,
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client",
 "main": true
 },
 "recipientCoin": {
 "serial": "309322206090",
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client"
 },
 "amount": 10,
 "description": "Transfer template",
 "paymentToolDetails": {
 "type": "COIN",
 "srcValue": "143347556578",
 "srcId": "e5cf99d2-f87b-4ff9-8bd1-dae7b7f3bf43",
 "destValue": "309322206090",
 "destId": "a95fd94f-d41d-4884-abe7-3e81af5355d0",
 "currency": "USD",
 "symbol": "$",
 "recipientFullName": "Merchant Default"
 }
}

1.1.2 Transfer Template basic way

All payment data should be pasted.
reusable – parameter shows if the template can be used in more then 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

permissons: TEMPLATES_OWNER
POST
/templates/transfer
Request:
{
 "name": "Test transfer template",
 "amount": 10,
 "description": "Transfer template",
 "reusable": true,
 "paymentTool": {
 "type": "COIN",
 "srcValue": "143347556578",
 "destValue": "309322206090"
 }
}
Response:
{
 "status": "ok",
 "message": "processed successfully",
 "id": "301a84b1-fddb-47cf-82c5-1a1c4a181efe",
 "name": "Test transfer template",
 "senderCoin": {
 "serial": "143347556578",
 "name": "Test USD coin",
 "amount": 9990,
 "availableAmount": 9990,
 "futureAmount": 0,
 "heldAmount": 0,
 "creditLimit": 0,
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client",
 "main": true
 },
 "recipientCoin": {
 "serial": "309322206090",
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client"
 },
 "amount": 10,
 "description": "Transfer template",
 "paymentToolDetails": {
 "type": "COIN",
 "srcValue": "143347556578",
 "srcId": "e5cf99d2-f87b-4ff9-8bd1-dae7b7f3bf43",
 "destValue": "309322206090",
 "destId": "a95fd94f-d41d-4884-abe7-3e81af5355d0",
 "currency": "USD",
 "symbol": "$",
 "recipientFullName": "Merchant Default"
 }
}

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

permissons: TEMPLATES_OWNER
GET
/templates/transfer
Response:
{
 "status": "ok",
 "message": "processed successfully",
 "transferTemplates": [
 {
 "id": "301a84b1-fddb-47cf-82c5-1a1c4a181efe",
 "type": "TransferTemplate",
 "name": "Test transfer template",
 "amount": 10.0000,
 "description": "Transfer template",
 "reusable": true,
 "regular": true,
 "senderCoin": {
 "serial": "143347556578",
 "name": "Test USD coin",
 "amount": 9990.0000,
 "availableAmount": 9990.0000,
 "futureAmount": 0.0000,
 "heldAmount": 0.0000,
 "creditLimit": 0.0000,
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client",
 "main": true
 },
 "recipientCoin": {
 "serial": "309322206090",
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client"
 },
 "paymentToolDetails": {
 "type": "COIN",
 "srcValue": "143347556578",
 "srcId": "e5cf99d2-f87b-4ff9-8bd1-dae7b7f3bf43",
 "destValue": "309322206090",
 "destId": "a95fd94f-d41d-4884-abe7-3e81af5355d0",
 "currency": "USD",
 "symbol": "$",
 "recipientFullName": "Merchant Default"
 }
 }
 ]
}

1.2.2 Get all templates with filter and pagination

permissons: TEMPLATES_OWNER
POST
/templates/transfer/view
Request:
{
 "filter": {
 },
 "pageNumber": 0,
 "pageSize": 20,
 "sort": {
 }
}
Response:
{
 "status": "ok",
 "message": "processed successfully",
 "pageNumber": 0,
 "pageSize": 20,
 "totalRecords": 1,
 "totalPages": 1,
 "records": [
 {
 "id": "301a84b1-fddb-47cf-82c5-1a1c4a181efe",
 "type": "TransferTemplate",
 "name": "Test transfer template",
 "amount": 10.0000,
 "description": "Transfer template",
 "reusable": true,
 "regular": true,
 "senderCoin": {
 "serial": "143347556578",
 "name": "Test USD coin",
 "amount": 9990.0000,
 "availableAmount": 9990.0000,
 "futureAmount": 0.0000,
 "heldAmount": 0.0000,
 "creditLimit": 0.0000,
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client",
 "main": true
 },
 "recipientCoin": {
 "serial": "309322206090",
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client"
 },
 "paymentToolDetails": {
 "type": "COIN",
 "srcValue": "143347556578",
 "srcId": "e5cf99d2-f87b-4ff9-8bd1-dae7b7f3bf43",
 "destValue": "309322206090",
 "destId": "a95fd94f-d41d-4884-abe7-3e81af5355d0",
 "currency": "USD",
 "symbol": "$",
 "recipientFullName": "Merchant Default"
 }
 }
 ]
}

1.3. Update transfer templates

permissons: TEMPLATES_OWNER
PATCH
/templates/transfer/{templateId}
Request:
{
 "amount": 5.25,
 "description": "Transfer template",
 "name": "Test transfer template EDITED"
}
Response:
{
 "status": "ok",
 "message": "processed successfully",
 "id": "301a84b1-fddb-47cf-82c5-1a1c4a181efe",
 "name": "Test transfer template EDITED",
 "senderCoin": {
 "serial": "143347556578",
 "name": "Test USD coin",
 "amount": 9990.0000,
 "availableAmount": 9990.0000,
 "futureAmount": 0.0000,
 "heldAmount": 0.0000,
 "creditLimit": 0.0000,
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client",
 "main": true
 },
 "recipientCoin": {
 "serial": "309322206090",
 "issuer": {
 "id": "31cf9aab-38ea-480c-9c13-2ca85e3ee807",
 "sn": "USD",
 "currency": "USD"
 },
 "active": true,
 "type": "client"
 },
 "amount": 5.2500,
 "description": "Transfer template",
 "paymentToolDetails": {
 "type": "COIN",
 "srcValue": "143347556578",
 "srcId": "e5cf99d2-f87b-4ff9-8bd1-dae7b7f3bf43",
 "destValue": "309322206090",
 "destId": "a95fd94f-d41d-4884-abe7-3e81af5355d0",
 "currency": "USD",
 "symbol": "$",
 "recipientFullName": "Merchant Default"
 }
}

1.4. Delete transfer templates

1.5. Manual payment execution

1.5.1 Calculate payment fee by transfer template

1.5.2 Execute payment fee by transfer template

2. Invoice template

DB table name: template_invoice

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

Recurring Type (field type)

  • DAILY – daily subscription execution

  • WEEKLY – weekly subscription execution

  • MONTHLY – monthly subscription execution

  • ANNUALLY – annually subscription execution

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 task

POST /tasks

{
 "type": "SUBSCRIPTION",
 "name": "Subscription task 1",
 "description": "Subscription task 1",
 "templateId": "01987edc-0139-7277-a052-458c661f7ee1"
}

2. Create subscription schedule

POST /schedules

{
 "taskId": "01987edc-61a1-7588-8d92-3590f2997b2e",
 "name": "Subscription task schedule 1",
 "description": "Subscription task schedule 1 - should be executed every day",
 "frequency": "DAILY",
 "expirationType": "END_DATE",
 "startDate": "2025-01-01T00:00:00+0300",
 "endDate": "2026-01-01T00:00:00+0300",
 "timeZone": "UTC",
 "dayOfWeek": 5,
 "dayOfMonth": 15,
 "hourOfDay": 18,
 "minuteOfHour": 0
}

3. Activate subscription schedule

PATCH /schedules/{scheduleId}

{
 "status": "ACTIVE"
}

4. Get subscription task

API operation GET /tasks with query parameter taskType=SUBSCRIPTION

5. Update subscription task

PATCH /tasks/{taskId}

{
 "type": "SUBSCRIPTION",
 "name": "Subscription task 2",
 "description": "Subscription task 2",
 "templateId": "01987f3f-721a-7ef7-80f0-c5f820d5b16f"
}

5. Delete subscription task

API operation DELETE /tasks/{taskId}

6. Get subscription schedules

API operation GET /schedules with query parameter taskType=SUBSCRIPTION

7. Stop subscription schedule

PATCH /schedules/{scheduleId}

{
 "status": "INACTIVE"
}

8. Delete subscription schedule

API operation DELETE /schedules/{scheduleId}

Periods

Responsibility: to store next execution date for related Subscription.

DB table name: subscription_period, subscription_period_definition

Related entities: Templates & Subscriptions | Subscriptions

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

  • CANCELLED – when Subscription in status CANCELLED

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 lastProcessDate according to the Subscription type

Calculation of the next Date for processing

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”);
}
}