diff --git a/en/openapi/components/parameters/signature.yaml b/en/openapi/components/parameters/signature.yaml new file mode 100644 index 00000000..8edac483 --- /dev/null +++ b/en/openapi/components/parameters/signature.yaml @@ -0,0 +1,7 @@ +name: Content-Signature +in: header +description: > + Message signature formed according to the above rules +required: true +schema: + type: string diff --git a/en/openapi/components/schemas/AccountID.yaml b/en/openapi/components/schemas/AccountID.yaml new file mode 100644 index 00000000..2ce9f5cc --- /dev/null +++ b/en/openapi/components/schemas/AccountID.yaml @@ -0,0 +1,3 @@ +description: Account identifier +type: string +example: tZ0jUmlsV0 diff --git a/en/openapi/components/schemas/AccountNumber.yaml b/en/openapi/components/schemas/AccountNumber.yaml new file mode 100644 index 00000000..11e7f62d --- /dev/null +++ b/en/openapi/components/schemas/AccountNumber.yaml @@ -0,0 +1,4 @@ +description: Account number +type: integer +format: int64 +example: 1430000 diff --git a/en/openapi/components/schemas/BankCard.yaml b/en/openapi/components/schemas/BankCard.yaml new file mode 100644 index 00000000..b40970b0 --- /dev/null +++ b/en/openapi/components/schemas/BankCard.yaml @@ -0,0 +1,26 @@ +description: Bank card details +allOf: + - + $ref: "../schemas/DestinationResource.yaml" + - + type: object + required: + - cardNumberMask + - paymentSystem + properties: + cardNumberMask: + description: Masked card number + type: string + pattern: '^\d{6,8}\*+\d{2,4}$' + bin: + description: Card issuing bank BIN + type: string + pattern: '^\d{6,8}$' + lastDigits: + description: Card last digits + type: string + pattern: '^\d{2,4}$' + paymentSystem: + $ref: "../schemas/BankCardPaymentSystem.yaml" + tokenProvider: + $ref: "../schemas/BankCardTokenProvider.yaml" diff --git a/en/openapi/components/schemas/BankCardPaymentSystem.yaml b/en/openapi/components/schemas/BankCardPaymentSystem.yaml new file mode 100644 index 00000000..2f8ebf07 --- /dev/null +++ b/en/openapi/components/schemas/BankCardPaymentSystem.yaml @@ -0,0 +1,2 @@ +description: Payment system +type: string diff --git a/en/openapi/components/schemas/BankCardTokenProvider.yaml b/en/openapi/components/schemas/BankCardTokenProvider.yaml new file mode 100644 index 00000000..cfa8786d --- /dev/null +++ b/en/openapi/components/schemas/BankCardTokenProvider.yaml @@ -0,0 +1,6 @@ +description: Payment token provider +type: string +enum: + - applepay + - googlepay + - samsungpay diff --git a/en/openapi/components/schemas/CryptoCurrency.yaml b/en/openapi/components/schemas/CryptoCurrency.yaml new file mode 100644 index 00000000..f22f8c15 --- /dev/null +++ b/en/openapi/components/schemas/CryptoCurrency.yaml @@ -0,0 +1,9 @@ +description: Cryptocurrency +type: string +enum: + - Bitcoin + - Litecoin + - BitcoinCash + - Ripple + - Ethereum + - Zcash diff --git a/en/openapi/components/schemas/CryptoWallet.yaml b/en/openapi/components/schemas/CryptoWallet.yaml new file mode 100644 index 00000000..3ede8734 --- /dev/null +++ b/en/openapi/components/schemas/CryptoWallet.yaml @@ -0,0 +1,18 @@ +description: Cryptocurrency wallet details +allOf: + - + $ref: "../schemas/DestinationResource.yaml" + - + type: object + required: + - cryptoWalletId + - currency + properties: + cryptoWalletId: + description: Identifier (aka address) of a cryptocurrency wallet + type: string + minLength: 16 + maxLength: 256 + example: zu3TcwGI71Bpaaw2XkLWZXlhMdn4zpVzMQ + currency: + $ref: "../schemas/CryptoCurrency.yaml" diff --git a/en/openapi/components/schemas/CurrencyID.yaml b/en/openapi/components/schemas/CurrencyID.yaml new file mode 100644 index 00000000..9755969e --- /dev/null +++ b/en/openapi/components/schemas/CurrencyID.yaml @@ -0,0 +1,5 @@ +description: > + Currency, character code according to [ISO 4217](http://www.iso.org/iso/home/standards/currency_codes.htm). +type: string +pattern: "^[A-Z]{3}$" +example: RUB diff --git a/en/openapi/components/schemas/Destination.yaml b/en/openapi/components/schemas/Destination.yaml new file mode 100644 index 00000000..365dd0aa --- /dev/null +++ b/en/openapi/components/schemas/Destination.yaml @@ -0,0 +1,28 @@ +description: Destination data +type: object +required: + - name + - currency + - resource +properties: + id: + $ref: "../schemas/DestinationID.yaml" + name: + description: | + A human-readable name for the receiver by which it is easily recognizable + type: string + example: Squarey plastic thingy + party: + $ref: "../schemas/PartyID.yaml" + currency: + $ref: "../schemas/CurrencyID.yaml" + resource: + $ref: "../schemas/DestinationResource.yaml" + metadata: + description: > + An arbitrary, client-specific API and non-transparent set of data associated with given receiver + type: object + example: + color_hint: olive-green + externalID: + $ref: "../schemas/ExternalID.yaml" diff --git a/en/openapi/components/schemas/DestinationAuthorized.yaml b/en/openapi/components/schemas/DestinationAuthorized.yaml new file mode 100644 index 00000000..20cd7a6a --- /dev/null +++ b/en/openapi/components/schemas/DestinationAuthorized.yaml @@ -0,0 +1,13 @@ +description: Changing the status of the destination receiver to authorized +allOf: + - + $ref: "../schemas/Event.yaml" + - + type: object + required: + - destinationID + properties: + destinationID: + $ref: "../schemas/DestinationID.yaml" + externalID: + $ref: "../schemas/ExternalID.yaml" diff --git a/en/openapi/components/schemas/DestinationCreated.yaml b/en/openapi/components/schemas/DestinationCreated.yaml new file mode 100644 index 00000000..ad855c4b --- /dev/null +++ b/en/openapi/components/schemas/DestinationCreated.yaml @@ -0,0 +1,11 @@ +description: Destination creation event +allOf: + - + $ref: "../schemas/Event.yaml" + - + type: object + required: + - destination + properties: + destination: + $ref: "../schemas/Destination.yaml" diff --git a/en/openapi/components/schemas/DestinationID.yaml b/en/openapi/components/schemas/DestinationID.yaml new file mode 100644 index 00000000..9d02aea1 --- /dev/null +++ b/en/openapi/components/schemas/DestinationID.yaml @@ -0,0 +1,3 @@ +description: Destination identifier +type: string +example: "10ASF74D98" diff --git a/en/openapi/components/schemas/DestinationName.yaml b/en/openapi/components/schemas/DestinationName.yaml new file mode 100644 index 00000000..1162c082 --- /dev/null +++ b/en/openapi/components/schemas/DestinationName.yaml @@ -0,0 +1,3 @@ +description: Human-readable name of the destination +type: string +example: "Worldwide PHP Awareness Initiative" diff --git a/en/openapi/components/schemas/DestinationResource.yaml b/en/openapi/components/schemas/DestinationResource.yaml new file mode 100644 index 00000000..3d083984 --- /dev/null +++ b/en/openapi/components/schemas/DestinationResource.yaml @@ -0,0 +1,19 @@ +description: Asset receiver resource used to make withdrawals +type: object +required: + - type +properties: + type: + description: | + Destination resource type + type: string + enum: + - BankCard + - CryptoWallet + - DigitalWallet +discriminator: + propertyName: type + mapping: + "BankCard": "../schemas/BankCard.yaml" + "CryptoWallet": "../schemas/CryptoWallet.yaml" + "DigitalWallet": "../schemas/DigitalWallet.yaml" diff --git a/en/openapi/components/schemas/DestinationUnauthorized.yaml b/en/openapi/components/schemas/DestinationUnauthorized.yaml new file mode 100644 index 00000000..01956cc8 --- /dev/null +++ b/en/openapi/components/schemas/DestinationUnauthorized.yaml @@ -0,0 +1,13 @@ +description: Changing the status of the destination receiver to unauthorized +allOf: + - + $ref: "../schemas/Event.yaml" + - + type: object + required: + - destinationID + properties: + destinationID: + $ref: "../schemas/DestinationID.yaml" + externalID: + $ref: "../schemas/ExternalID.yaml" diff --git a/en/openapi/components/schemas/DigitalWallet.yaml b/en/openapi/components/schemas/DigitalWallet.yaml new file mode 100644 index 00000000..b14eeca4 --- /dev/null +++ b/en/openapi/components/schemas/DigitalWallet.yaml @@ -0,0 +1,20 @@ +description: Cryptocurrency wallet details +allOf: + - + $ref: "../schemas/DestinationResource.yaml" + - + type: object + required: + - digitalWalletId + - digitalWalletProvider + properties: + digitalWalletId: + description: E-wallet identifier + type: string + minLength: 16 + maxLength: 256 + example: zu3TcwGI71Bpaaw2XkLWZXlhMdn4zpVzMQ + digitalWalletProvider: + description: Electronic assets service provider + type: string + example: Paypal diff --git a/en/openapi/components/schemas/Event.yaml b/en/openapi/components/schemas/Event.yaml new file mode 100644 index 00000000..0aa4610f --- /dev/null +++ b/en/openapi/components/schemas/Event.yaml @@ -0,0 +1,35 @@ +description: Event data +type: object +required: + - occuredAt + - topic + - eventType +properties: + eventID: + description: Event identifier + type: string + occuredAt: + description: Date and time the event occurrence + type: string + format: date-time + topic: + description: Subject of notification + type: string + enum: + - WithdrawalTopic + - DestinationTopic + eventType: + type: string + description: Type of event that occurred. + enum: + - WithdrawalStarted + - WithdrawalSucceeded + - WithdrawalFailed + - DestinationCreated +discriminator: + propertyName: eventType + mapping: + "WithdrawalStarted": "../schemas/WithdrawalStarted.yaml" + "WithdrawalSucceeded": "../schemas/WithdrawalSucceeded.yaml" + "WithdrawalFailed": "../schemas/WithdrawalFailed.yaml" + "DestinationCreated": "../schemas/DestinationCreated.yaml" diff --git a/en/openapi/components/schemas/ExternalID.yaml b/en/openapi/components/schemas/ExternalID.yaml new file mode 100644 index 00000000..c898d999 --- /dev/null +++ b/en/openapi/components/schemas/ExternalID.yaml @@ -0,0 +1,6 @@ +description: | + The unique identifier of the content on your side. + + When specified, will be used to ensure idempotent processing of the operation. +type: string +example: "10036274" diff --git a/en/openapi/components/schemas/Fee.yaml b/en/openapi/components/schemas/Fee.yaml new file mode 100644 index 00000000..340ffc3b --- /dev/null +++ b/en/openapi/components/schemas/Fee.yaml @@ -0,0 +1,13 @@ +description: Fee charged for the withdrawal +type: object +required: + - amount + - currency +properties: + amount: + description: The amount of money in minor units, for example, in cents + type: integer + format: int64 + example: 1430000 + currency: + $ref: '../schemas/CurrencyID.yaml' diff --git a/en/openapi/components/schemas/GeneralError.yaml b/en/openapi/components/schemas/GeneralError.yaml new file mode 100644 index 00000000..aa3e7ae7 --- /dev/null +++ b/en/openapi/components/schemas/GeneralError.yaml @@ -0,0 +1,6 @@ +type: object +required: + - message +properties: + message: + type: string diff --git a/en/openapi/components/schemas/IdentityID.yaml b/en/openapi/components/schemas/IdentityID.yaml new file mode 100644 index 00000000..146d825f --- /dev/null +++ b/en/openapi/components/schemas/IdentityID.yaml @@ -0,0 +1,3 @@ +description: Identifier of wallet owner +type: string +example: tZ0jUmlsV0 diff --git a/en/openapi/components/schemas/PartyID.yaml b/en/openapi/components/schemas/PartyID.yaml new file mode 100644 index 00000000..48469e2e --- /dev/null +++ b/en/openapi/components/schemas/PartyID.yaml @@ -0,0 +1,3 @@ +description: Identifier of owner +type: string +example: tZ0jUmlsV0 diff --git a/en/openapi/components/schemas/WalletID.yaml b/en/openapi/components/schemas/WalletID.yaml new file mode 100644 index 00000000..5fea2d5a --- /dev/null +++ b/en/openapi/components/schemas/WalletID.yaml @@ -0,0 +1,3 @@ +description: Identifier of the wallet +type: string +example: "10068321" diff --git a/en/openapi/components/schemas/Withdrawal.yaml b/en/openapi/components/schemas/Withdrawal.yaml new file mode 100644 index 00000000..6079d428 --- /dev/null +++ b/en/openapi/components/schemas/Withdrawal.yaml @@ -0,0 +1,24 @@ +description: Funds withdrawal data +type: object +required: + - wallet + - destination + - body +properties: + id: + $ref: "../schemas/WithdrawalID.yaml" + createdAt: + description: Date and time the withdrawal started + type: string + format: date-time + destination: + $ref: "../schemas/DestinationID.yaml" + body: + $ref: "../schemas/WithdrawalBody.yaml" + metadata: + description: > + A custom client-specific API and a data set that is not transparent to the system, associated with this withdrawal + wallet: + $ref: "../schemas/WalletID.yaml" + externalID: + $ref: "../schemas/ExternalID.yaml" diff --git a/en/openapi/components/schemas/WithdrawalBody.yaml b/en/openapi/components/schemas/WithdrawalBody.yaml new file mode 100644 index 00000000..62288c33 --- /dev/null +++ b/en/openapi/components/schemas/WithdrawalBody.yaml @@ -0,0 +1,15 @@ +description: | + Amount of funds to be withdrawn +type: object +required: + - amount + - currency +properties: + amount: + description: | + The amount of money in minor units, for example, in cents + type: integer + format: int64 + example: 1430000 + currency: + $ref: "../schemas/CurrencyID.yaml" diff --git a/en/openapi/components/schemas/WithdrawalFailed.yaml b/en/openapi/components/schemas/WithdrawalFailed.yaml new file mode 100644 index 00000000..3bd24a0d --- /dev/null +++ b/en/openapi/components/schemas/WithdrawalFailed.yaml @@ -0,0 +1,13 @@ +description: Unsuccessful withdrawal event +allOf: + - + $ref: "../schemas/Event.yaml" + - + type: object + required: + - withdrawalID + properties: + withdrawalID: + $ref: "../schemas/WithdrawalID.yaml" + externalID: + $ref: "../schemas/ExternalID.yaml" diff --git a/en/openapi/components/schemas/WithdrawalID.yaml b/en/openapi/components/schemas/WithdrawalID.yaml new file mode 100644 index 00000000..e0394dc4 --- /dev/null +++ b/en/openapi/components/schemas/WithdrawalID.yaml @@ -0,0 +1,3 @@ +description: Identifier of funds withdrawal +type: string +example: tZ0jUmlsV0 diff --git a/en/openapi/components/schemas/WithdrawalStarted.yaml b/en/openapi/components/schemas/WithdrawalStarted.yaml new file mode 100644 index 00000000..0b9442b4 --- /dev/null +++ b/en/openapi/components/schemas/WithdrawalStarted.yaml @@ -0,0 +1,11 @@ +description: Withdrawal start event +allOf: + - + $ref: "../schemas/Event.yaml" + - + type: object + required: + - withdrawal + properties: + withdrawal: + $ref: "../schemas/Withdrawal.yaml" diff --git a/en/openapi/components/schemas/WithdrawalSucceeded.yaml b/en/openapi/components/schemas/WithdrawalSucceeded.yaml new file mode 100644 index 00000000..6c81e1c1 --- /dev/null +++ b/en/openapi/components/schemas/WithdrawalSucceeded.yaml @@ -0,0 +1,15 @@ +description: Successful withdrawal event +allOf: + - + $ref: "../schemas/Event.yaml" + - + type: object + required: + - withdrawalID + properties: + withdrawalID: + $ref: "../schemas/WithdrawalID.yaml" + externalID: + $ref: "../schemas/ExternalID.yaml" + fee: + $ref: "../schemas/Fee.yaml" diff --git a/en/openapi/openapi.yaml b/en/openapi/openapi.yaml new file mode 100644 index 00000000..c4903d63 --- /dev/null +++ b/en/openapi/openapi.yaml @@ -0,0 +1,51 @@ +openapi: 3.0.0 +info: + version: 0.1.0 + title: Vality Wallets. Webhooks Events API + termsOfService: https://vality.dev/ + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + description: > + + ## Wallet Webhook Events API + The specification defines a protocol for delivering notifications about new wallet events within your organisation. The notifications are deliveried by the system as HTTP requests to the URL of webhooks you created. Handlers for such kind of queries should be implemented on the side of your server code according to the specification. + + Webhook is a subscription to a specific type of event or group of events relating to different objects within your organisation. API methods described in the specification [Vality Webhook Management API](https:/github.com/valitydev/swag-wallets) are used to manage webhooks. + + When within the wallet one of the events occurs (e.g. a wallet status change), the system selects a webhook matching that event type and sends an HTTP request containing a JSON message to the URL specified in the webhook. If several webhooks matching this event type were created, the event is simultaneously delivered to all URLs specified in those webhooks in an undefined order. + ## Delivery strategy + The system guarantees events delivery order within a specific notification subject (wallet, deposit, withdrawal, etc.). The system maintains a message queue for each notification item to keep the sequence and ensure the guaranteed delivery. + + A delivery request is considered to be successful only when a response with status `200` is received. The system will wait for a successful response to the sent a request during 10 seconds. In case of a response with any other status or after expiration of the specified time which was reserved to process the notification, the system will try to re-deliver notifications until a successful response is received, or until a decision is made that it is impossible to deliver information. Delivery attempts will be made at the following time intervals between requests: + - 30 seconds, - 5 minutes, - 15 minutes, - 1 hour. - every hour within 24 hours + If the last attempt of notification delivery fails, all the events that have been accumulated in this wallet queue are discarded. + ## Received messages authorization + The system confirms notifications authenticity by signing messages with a private key that is unique to each webhook, the paired public key of which is contained in the data of that webhook. The signature is transmitted in the HTTP header Content-Signature. Represented in various atributes the header contains the information about the algorithm used to create a signature and content of the signature in the format [URL-safe base-64](https://tools.ietf.org/html/rfc4648). + + ``` Content-Signature: alg=RS256; digest=zFuf7bRH4RHwyktaqHQwmX5rn3LfSb4dKo... ``` + + At the moment the only one signature generation algorithm is possible to use. + ### [RS256](https://tools.ietf.org/html/rfc7518#section-3.3) + The signature is generated according to [RSASSA-PKCS1-v1_5](https://tools.ietf.org/html/rfc3447#section-8.2) algorithm , which itself uses result of message [SHA-256](https://tools.ietf.org/html/rfc6234) calculation. + + The set of header attributes and the list of possible signature generation algorithms can be expanded later. +servers: + - + url: "https://merchant.site" +tags: + - + name: Event Notifications + x-displayName: Notifications + description: Delivery of platform event notifications. +paths: + "/webhook": + $ref: "./paths/webhook-url.yaml" +components: + securitySchemes: + signature: + description: | + Message signature formed according to the above rules. + name: Content-Signature + type: apiKey + in: header diff --git a/en/openapi/paths/webhook-url.yaml b/en/openapi/paths/webhook-url.yaml new file mode 100644 index 00000000..4cf8073b --- /dev/null +++ b/en/openapi/paths/webhook-url.yaml @@ -0,0 +1,18 @@ +post: + tags: + - Event Notifications + summary: Notify of an event + operationId: notifyWebhookEvent + security: + - + signature: [ ] + requestBody: + description: Data from an event that occurred in the platform + required: true + content: + application/json: + schema: + $ref: "../components/schemas/Event.yaml" + responses: + "200": + description: Notification processed