diff options
Diffstat (limited to 'core/api-merchant.rst')
| -rw-r--r-- | core/api-merchant.rst | 238 |
1 files changed, 237 insertions, 1 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst index ebd5647d..c1bbf058 100644 --- a/core/api-merchant.rst +++ b/core/api-merchant.rst @@ -3127,7 +3127,7 @@ Adding webhooks The creation of the webhook is successsful. :http:statuscode:`404 Not found`: - The merchant instance is unknowm or it not in our data. + The merchant instance is unknown or it not in our data. .. ts:def:: WebhookAddDetails @@ -3288,6 +3288,242 @@ Removing webhook +---------------------------------------- +Token Families: Subscriptions, Discounts +---------------------------------------- + +This API provides functionalities for the issuance, management, and revocation +of token families. Tokens facilitate the implementation of subscriptions and +discounts, engaging solely the merchant and the user. Each token family +encapsulates details pertaining to its respective tokens, guiding the merchant's +backend on the appropriate processing and handling. + + +Creating token families +----------------------- + +.. http:post:: [/instances/$INSTANCES]/private/tokenfamilies + + This is used to create a token family. + + **Request:** + + The request must be a `TokenFamilyCreateRequest`. + + **Response:** + + :http:statuscode:`204 No content`: + The token family was created successfully. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the instance. + + .. ts:def:: TokenFamilyCreateRequest + + interface TokenFamilyCreateRequest { + + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + + // Human-readable name for the token family. + name: string; + + // Human-readable description for the token family. + description: string; + + // Optional map from IETF BCP 47 language tags to localized descriptions. + description_i18n?: { [lang_tag: string]: string }; + + // Start time of the token family's validity period. + // If not specified, merchant backend will use the current time. + valid_after?: Timestamp; + + // End time of the token family's validity period. + valid_before: Timestamp; + + // Validity duration of an issued token. + duration: RelativeTime; + + // Kind of the token family. + kind: TokenFamilyKind; + + } + + .. ts:def:: TokenFamilyKind + + enum TokenFamilyKind { + Discount = "discount", + Subscription = "subscription", + } + + +Updating token families +----------------------- + +.. http:patch:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG + + This is used to update a token family. + + **Request:** + + The request must be a `TokenFamilyUpdateRequest`. + + **Response:** + + :http:statuscode:`200 OK`: + The token family was successsful updated. Returns a `TokenFamilyDetails`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + .. ts:def:: TokenFamilyUpdateRequest + + interface TokenFamilyUpdateRequest { + + // Human-readable name for the token family. + name: string; + + // Human-readable description for the token family. + description: string; + + // Optional map from IETF BCP 47 language tags to localized descriptions. + description_i18n: { [lang_tag: string]: string }; + + // Start time of the token family's validity period. + valid_after: Timestamp; + + // End time of the token family's validity period. + valid_before: Timestamp; + + // Validity duration of an issued token. + duration: RelativeTime; + + } + + + +Inspecting token families +------------------------- + +.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies + + This is used to list all configured token families for an instance. + + **Response:** + + :http:statuscode:`200 OK`: + The merchant backend has successfully returned all token families. + Returns a `TokenFamiliesList`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the instance. + + .. ts:def:: TokenFamiliesList + + // TODO: Add pagination + + interface TokenFamiliesList { + + // All configured token families of this instance. + token_families: TokenFamilySummary[]; + + } + + .. ts:def:: TokenFamilySummary + + interface TokenFamilySummary { + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + + // Human-readable name for the token family. + name: string; + + // Start time of the token family's validity period. + valid_after: Timestamp; + + // End time of the token family's validity period. + valid_before: Timestamp; + + // Kind of the token family. + kind: TokenFamilyKind; + } + + +.. http:get:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG + + This is used to get detailed information about a specific token family. + + **Response:** + + :http:statuscode:`200 OK`: + The merchant backend has successfully returned the detailed information + about a specific token family. Returns a `TokenFamilyDetails`. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + + The `TokenFamilyDetails` object describes a configured token family. + + .. ts:def:: TokenFamilyDetails + + interface TokenFamilyDetails { + + // Identifier for the token family consisting of unreserved characters + // according to RFC 3986. + slug: string; + + // Human-readable name for the token family. + name: string; + + // Human-readable description for the token family. + description: string; + + // Optional map from IETF BCP 47 language tags to localized descriptions. + description_i18n?: { [lang_tag: string]: string }; + + // Start time of the token family's validity period. + valid_after: Timestamp; + + // End time of the token family's validity period. + valid_before: Timestamp; + + // Validity duration of an issued token. + duration: RelativeTime; + + // Kind of the token family. + kind: TokenFamilyKind; + + // How many tokens have been issued for this family. + issued: Integer; + + // How many tokens have been redeemed for this family. + redeemed: Integer; + + } + + + +Deleting token families +----------------------- + +.. http:delete:: [/instances/$INSTANCES]/private/tokenfamilies/$TOKEN_FAMILY_SLUG + + This is used to delete a token family. Issued tokens of this family will not + be spendable anymore. + + **Response:** + + :http:statuscode:`204 No content`: + The backend has successfully deleted the token family. + + :http:statuscode:`404 Not found`: + The merchant backend is unaware of the token family or instance. + + + ------------------ The Contract Terms ------------------ |