From 80163bc029fc6026d03d1840aa50f1b293e537bf Mon Sep 17 00:00:00 2001 From: Marwen Abid Date: Mon, 31 Jul 2023 15:59:58 -0700 Subject: [PATCH] Add descriptions, add examples, add missing endpoints (#202) * Add descriptions, add examples, add missing endpoints * Replace `Wallet-Registration` with `Registration` --- .../stellar-disbursement-platform/main.yml | 650 ++++++++++++++---- 1 file changed, 513 insertions(+), 137 deletions(-) diff --git a/openapi/stellar-disbursement-platform/main.yml b/openapi/stellar-disbursement-platform/main.yml index 5abef3fb2..22e8c1b63 100644 --- a/openapi/stellar-disbursement-platform/main.yml +++ b/openapi/stellar-disbursement-platform/main.yml @@ -2,13 +2,13 @@ swagger: '2.0' info: title: Stellar Disbursement Platform API version: '' - description: '' + description: The Stellar Disbursement Platform (SDP) is a tool built for organizations to make bulk payments to a group of recipients over the Stellar network. You can read more about using the SDP [here](https://developers.stellar.org/docs/category/use-the-stellar-disbursement-platform). paths: /login: post: responses: - '201': - description: Created + '200': + description: OK headers: {} examples: application/json: @@ -50,7 +50,7 @@ paths: message: Invalid username or password summary: Log In operationId: Log In - description: '' + description: 'Allows credentialed SDP users to log in to the SDP dashboard with a password. Note: all passwords must be at least 8 characters long and a combination of uppercase letters, lowercase letters, numbers, and symbols.' tags: - Authentication parameters: @@ -59,20 +59,26 @@ paths: schema: type: object properties: - username: + email: type: string password: type: string + recaptcha_token: + type: string + description: "Token for reCAPTCHA validation. ReCAPTCHA token is only required when `ENABLE_RECAPTCHA` configuration is set to true." + required: + - email + - password example: - username: johndoe@mail.com + email: johndoe@mail.com password: mysecret produces: - application/json - /refresh_token: + /refresh-token: post: responses: - '201': - description: Created + '200': + description: Returns a new access token headers: {} examples: application/json: @@ -87,34 +93,12 @@ paths: token: >- eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjp7ImlkIjoidXNlci1pZCIsImVtYWlsIjoiZW1haWxAZW1haWwuY29tIiwicm9sZXMiOlt7Im5hbWUiOiJTdXBlcnZpc29yIn1dfSwiZXhwIjoxNjc1OTYyOTQ3fQ.4Zj9yBXch-iuFYF-kc_EhHPxjpwp_egMOLbOv4bZKO1MFvcmEgZ5MlXH1_1fZfgUxaNBcMCdRM6MGSqKocwGnA '400': - description: Bad Request - headers: {} - examples: - application/json: - error: Invalid token - extras: - status: 400 - message: Token is expired or invalid - schema: - type: object - properties: - error: - type: string - extras: - type: object - properties: - status: - type: number - message: - type: string - example: - error: Invalid token - extras: - status: 400 - message: Token is expired or invalid + $ref: '#/responses/BadRequestResponse' + '401': + $ref: '#/responses/UnauthorizedResponse' summary: Refresh Token operationId: Refresh Token - description: '' + description: 'A user’s token expires after 15 minutes. This endpoint handles refreshing the user’s token without disrupting their experience. It is triggered within the 30-second window before the token expires.' tags: - Authentication parameters: [] @@ -125,6 +109,7 @@ paths: /mfa: post: summary: Multi-factor authentication endpoint + description: 'Governs the multi-factor authentication process for SDP user login, including the ability to remember the device so MFA is not always required.' operationId: authenticateMFA tags: - Authentication @@ -144,7 +129,7 @@ paths: description: Boolean flag to remember the user recaptcha_token: type: string - description: Token for reCAPTCHA validation + description: "Token for reCAPTCHA validation. ReCAPTCHA token is only required when `ENABLE_RECAPTCHA` configuration is set to true." required: - mfa_code - in: header @@ -170,6 +155,7 @@ paths: /forgot-password: post: summary: Forgot password endpoint + description: 'Sends an email with a token to an SDP user who has gone through the Forgot Password process.' operationId: forgotPassword tags: - Authentication @@ -200,6 +186,7 @@ paths: /reset-password: post: summary: Reset password endpoint + description: 'Allows an SDP user who has gone through the Forgot Password process to set their new password with a token sent via email.' operationId: resetPassword tags: - Authentication @@ -240,7 +227,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: List All Disbursements operationId: List All Disbursements - description: '' + description: 'Fetches all disbursements the organization has created. This endpoint supports pagination. The response includes basic aggregations on payments within the disbursement.' tags: - Disbursements parameters: @@ -258,12 +245,12 @@ paths: default: 20 - name: q in: query - description: a search term used to query through the disbursements names. + description: A search term used to query through the disbursement names. required: false type: string - name: status in: query - description: exact match on the status of the disbursement. + description: Exact match on the status of the disbursement. required: false x-example: DRAFT type: string @@ -276,7 +263,7 @@ paths: - name: created_at_after in: query description: >- - only return disbursements that are created after this date. Format: + Only return disbursements that are created after this date. Format: YYYY-MM-DD required: false x-example: '2006-01-02' @@ -284,14 +271,14 @@ paths: - name: created_at_before in: query description: >- - only return disbursements that are created before this date. Format: + Only return disbursements that are created before this date. Format: YYYY-MM-DD required: false x-example: '2006-01-02' type: string - name: sort in: query - description: field used to sort disbursements + description: Field used to sort disbursements required: false type: string default: created_at @@ -300,7 +287,7 @@ paths: - created_at - name: direction in: query - description: direction for sorting disbursements. + description: Direction for sorting disbursements. required: false type: string default: asc @@ -349,7 +336,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Create Disbursements operationId: Create Disbursements - description: '' + description: 'Creates a new disbursement in ```draft``` state with basic details. Important: a disbursement is not triggered until the organization adds receivers through the Upload Disbursement Instructions endpoint and the status changes from ```draft``` to ```ready```.' tags: - Disbursements parameters: @@ -366,10 +353,11 @@ paths: type: string country_code: type: string + description: 'Two-character ISO 3166 code' example: name: My New Disbursement name wallet_id: e2de8544-b7e2-40a9-ad40-411f70d5c4bf - asset_id: e2de8544-b7e2-40a9-ad40-411f70d5c4bf + asset_id: d227a68c-2f40-11ee-be56-0242ac120002 country_code: ua produces: - application/json @@ -414,7 +402,7 @@ paths: message: Disbursement not found summary: Retrieve a Disbursement operationId: Retrieve a Disbursement - description: '' + description: 'Fetches information on a specific disbursement by ```id```.' tags: - Disbursements parameters: @@ -466,7 +454,7 @@ paths: message: Disbursement not found summary: List All Disbursement Receivers operationId: List All Disbursement Receivers - description: '' + description: 'Fetches a list of receivers within a specific disbursement using the disbursement ```id```. This endpoint supports pagination.' tags: - Disbursements parameters: @@ -563,7 +551,7 @@ paths: message: Disbursement not found summary: Upload Disbursement Instructions operationId: Upload Disbursement Instructions - description: Upload a CSV file with disbursement instructions. + description: 'Adds a file containing a list of receivers to a ```draft``` disbursement. This step is required before a disbursement can begin. The file must be a CSV and has a standard format that can be found at ```dev/sample/sample-disbursement.csv```. The operation is idempotent, guaranteed by deleting and recreating the disbursement attributes when this endpoint is called.' consumes: - multipart/form-data tags: @@ -654,7 +642,7 @@ paths: message: Disbursement not found summary: Download Disbursement Instructions operationId: Download Disbursement Instructions - description: '' + description: 'Allows an SDP user to download the raw CSV file that was uploaded when creating the disbursement. This will only return results after instructions have been attached to a draft disbursement.' tags: - Disbursements parameters: @@ -735,7 +723,7 @@ paths: message: Disbursement not found summary: Update a Disbursement Status operationId: Update a Disbursement Status - description: '' + description: 'Updates the status of a disbursement according to the state machine. The disbursement must move from ```draft``` to ```ready``` in order to start the disbursement and trigger payments. Payments will start as soon as this endpoint is hit. A disbursement can also be moved into ```paused``` state by an SDP user to prevent further payments from going out and restarted when they are ready.' tags: - Disbursements parameters: @@ -761,7 +749,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: List All Payments operationId: List All Payments - description: '' + description: 'Returns all individual payments matching the request criteria. This endpoint supports pagination and filtering on payment status, receiver ID, and timestamp. Each payment has details on the transaction itself, receiver, disbursement, asset, status history, and blockchain information.' tags: - Payments parameters: @@ -779,7 +767,7 @@ paths: default: 20 - name: status in: query - description: exact match on the status of the payment. + description: Exact match on the status of the payment. required: false x-example: DRAFT type: string @@ -792,14 +780,14 @@ paths: - FAILED - name: receiver_id in: query - description: uuid that represents a receiver in the database + description: UUID that represents a receiver in the database required: false x-example: b6b667ad-6cc2-46cf-9be7-561daace7d48 type: string - name: created_at_after in: query description: >- - only return payments that are created after this date. Format: + Only return payments that are created after this date. Format: YYYY-MM-DD required: false x-example: '2006-01-02' @@ -807,14 +795,14 @@ paths: - name: created_at_before in: query description: >- - only return payments that are created before this date. Format: + Only return payments that are created before this date. Format: YYYY-MM-DD required: false x-example: '2006-01-02' type: string - name: sort in: query - description: field used to sort payments + description: Field used to sort payments required: false type: string default: created_at @@ -822,7 +810,7 @@ paths: - created_at - name: direction in: query - description: direction for sorting payments. + description: Direction for sorting payments. required: false type: string default: asc @@ -872,7 +860,7 @@ paths: message: Payment not found summary: Retrieve a Payment operationId: Retrieve a Payment - description: '' + description: 'Fetches detailed information on a specific payment by ```id```.' tags: - Payments parameters: @@ -898,7 +886,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: List All Receivers operationId: List All Receivers - description: '' + description: 'Returns all receivers matching the request criteria. This endpoint supports pagination and filtering on receiver status, receiver attributes, and timestamp. Each payment has details on the receiver, high-level payments metrics, and wallets associated with the receiver.' tags: - Receivers parameters: @@ -917,13 +905,13 @@ paths: - name: q in: query description: >- - a search term used to query through the receivers phone_number, - email and ID. + A search term used to query through the receiver phone_number, + email, and ID. required: false type: string - name: status in: query - description: exact match on the status of the receiver wallet. + description: Exact match on the status of the receiver wallet. required: false x-example: DRAFT type: string @@ -935,7 +923,7 @@ paths: - name: created_at_after in: query description: >- - only return receivers that are created after this date. Format: + Only return receivers that are created after this date. Format: YYYY-MM-DD required: false x-example: '2006-01-02' @@ -943,14 +931,14 @@ paths: - name: created_at_before in: query description: >- - only return receivers that are created before this date. Format: + Only return receivers that are created before this date. Format: YYYY-MM-DD required: false x-example: '2006-01-02' type: string - name: sort in: query - description: field used to sort receivers + description: Field used to sort receivers required: false type: string default: created_at @@ -958,7 +946,7 @@ paths: - created_at - name: direction in: query - description: direction for sorting receivers. + description: Direction for sorting receivers. required: false type: string default: asc @@ -985,7 +973,7 @@ paths: summary: Retrieve a Receiver operationId: Retrieve a Receiver - description: '' + description: 'Fetches detailed information on a specific receiver by ```id```, including all associated wallets.' tags: - Receivers parameters: @@ -1014,7 +1002,7 @@ paths: $ref: '#/responses/NotFoundResponse' summary: Update the Receiver operationId: Update the Receiver - description: '' + description: 'This endpoint allows an organization to add and update information on the receiver, including email address, external ID, date of birth, personal PIN, and national ID number. The response includes all information on the receiver.' tags: - Receivers parameters: @@ -1044,7 +1032,7 @@ paths: $ref: '#/responses/UnauthorizedResponse' summary: Retrieve all Statistics operationId: Retrieve all Statistics - description: 'All statistics, including disbursement and receiver wallet data' + description: 'Fetches all metrics on all disbursements the organization has created. The response includes basic aggregations on payments, receivers, receiver wallets, and assets.' tags: - Statistics parameters: [] @@ -1065,7 +1053,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Retrieve Disbursement-specific Statistics operationId: Retrieve Disbursement-specific Statistics - description: '' + description: 'Fetches metrics on a specific disbursement by ```id```.' tags: - Statistics parameters: @@ -1083,9 +1071,7 @@ paths: summary: Load the PII Confirmation Webpage operationId: Load the PII Confirmation Webpage description: >- - This is the endpoint the browser will reach with the first token, so the - user can confirm their PII information and then launch the wallet through a deep link. - Requires a valid SEP-24 token in the request. + This is the endpoint the browser reaches with the first token so that the receiver can confirm their verification information through a webflow. Requires a valid SEP-24 token in the request. tags: - Registration produces: @@ -1116,9 +1102,7 @@ paths: summary: Send OTP to the provided phone number operationId: SendOTP description: >- - This endpoint generates a 6-digit OTP and sends it via SMS to the - phone number provided in the request body. A valid SEP-24 token should be - included in the Authorization header of the request. + This endpoint generates a 6-digit OTP and sends it via SMS to the phone number provided in the request body (after checking that the phone number matches a receiver phone number in the SDP). A valid SEP-24 token should be included in the Authorization header of the request. tags: - Registration consumes: @@ -1136,6 +1120,12 @@ paths: phone_number: type: string description: Phone number to which the OTP will be sent + recaptcha_token: + type: string + description: "Token for reCAPTCHA validation" + required: + - phone_number + - recaptcha_token - name: Authorization in: header description: "SEP-24 token for authorization (Format: 'Bearer {token}')" @@ -1171,9 +1161,7 @@ paths: summary: Verify Receiver Registration operationId: VerifyReceiverRegistration description: >- - This endpoint verifies the receiver's registration by validating the - OTP and other verification values provided in the request body. - A valid SEP-24 token should be included in the Authorization header of the request. + This endpoint verifies the receiver's registration by validating the OTP and other verification values provided in the request body. A valid SEP-24 token should be included in the Authorization header of the request. tags: - Registration consumes: @@ -1213,16 +1201,35 @@ paths: headers: {} examples: text/toml: > + ACCOUNTS=["GBC2HVWFIFN7WJHFORVBCDKJORXXXXXXXXXXXXXXXXXXXXXXXX", "GDA34JZ26FZY64XCSY46CUNSHLX762LHJXQXXXXXXXXXXXXXXXXXXXXXXXX"] + SIGNING_KEY="GDA34JZ26FZY64XCSY46XXXXXXXXXXXXXXXXXXXXXXXX" NETWORK_PASSPHRASE="Test SDF Network ; September 2015" - - SIGNING_KEY="GC4HAYCFQYQLJV5SE6FB3LGC37D6XGIXGMAXCXWNBLH7NWW2JH4OZLHQ" - - WEB_AUTH_ENDPOINT="https://localhost:8000/sep10_auth" - summary: Stellar toml - operationId: Stellar toml + HORIZON_URL="https://horizon-testnet.stellar.org" + WEB_AUTH_ENDPOINT="https://ap-stellar-disbursement-platform-backend-dev.stellar.org/auth" + TRANSFER_SERVER_SEP0024="https://ap-stellar-disbursement-platform-backend-dev.stellar.org/sep24" + + [[DOCUMENTATION]] + ORG_NAME="Stellar Aid" + + [[CURRENCIES]] + code = "EUROC" + issuer = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5" + is_asset_anchored = true + anchor_asset_type = "fiat" + status = "live" + desc = "EUROC" + + [[CURRENCIES]] + code = "USDC" + issuer = "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5" + is_asset_anchored = true + anchor_asset_type = "fiat" + status = "live" + desc = "USDC" + summary: Retrieve Stellar toml + operationId: Retrieve Stellar toml description: >- - This is the endpoint where the wallet will gather the SEP-10 server url - and SEP-10 signing public key. + Allows the wallet to fetch the SEP-10 server url, SEP-10 signing public key and SEP-24 server url. tags: - Anchor parameters: [] @@ -1275,13 +1282,7 @@ paths: summary: GET SEP-10 Challenge Transaction operationId: GET SEP-10 Challenge Transaction description: >- - The SEP-10 endpoint where the wallet will get the challenge transaction - to be signed. More information - [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md#challenge). - - - This endpoint can change, but will be provided in the tomle file under - the `WEB_AUTH_ENDPOINT` variable. + Allows the wallet to get the SEP-10 challenge transaction to be signed. More information [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md#challenge). The endpoint url can change but is provided in the Get Stellar toml endpoint response under the ```WEB_AUTH_ENDPOINT``` variable. tags: - Anchor parameters: @@ -1341,13 +1342,7 @@ paths: summary: POST SEP-10 Challenge Transaction operationId: POST SEP-10 Challenge Transaction description: >- - The SEP-10 endpoint where the wallet will get the challenge transaction - to be signed. More information - [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md#challenge). - - - This endpoint can change, but will be provided in the tomle file under - the `WEB_AUTH_ENDPOINT` variable. + Allows the wallet to post the signed SEP-10 challenge transaction. More information [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0010.md#challenge). The endpoint url can change but is provided in the toml file under the ```WEB_AUTH_ENDPOINT``` variable. tags: - Anchor parameters: @@ -1363,6 +1358,40 @@ paths: AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX+F4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST/fImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAvheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA+xM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3AsiYk3UAAABArIrkvqmA0V9lIZcVyCUdja6CiwkPwsV8BfI4CZOyR1Oq7ysvNJWwY0G42dpxN9OP1qz4dum8apG2hqvxVWjkDQ== produces: - application/json + /TRANSFER_SERVER_SEP0024/transactions/deposit/interactive: + post: + summary: Sep24 Deposit endpoint + description: > + The deposit endpoint allows a wallet to get deposit information from an anchor, + so a user has all the information needed to initiate a deposit. + + It also lets the anchor specify additional information that the user must submit interactively via a popup or embedded browser window to be able to deposit. + Please check the detailed documentation [here](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md#deposit-2). + externalDocs: + description: Find more info here + url: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md#deposit-2 + parameters: [] + tags: + - Anchor + responses: + '200': + description: An anchor requires the user to fill out information on a webpage hosted by the anchor. + schema: + type: object + properties: + type: + type: string + description: Always set to interactive_customer_info_needed. + example: "interactive_customer_info_needed" + url: + type: string + description: URL hosted by the anchor. The wallet should show this URL to the user as a popup. + example: "https://api.example.com/kycflow?account=GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI" + id: + type: string + description: The anchor's internal ID for this deposit / withdrawal request. The wallet will use this ID to query the /transaction endpoint to check status of the request. + example: "82fhs729f63dh0v4" + /profile: get: responses: @@ -1373,7 +1402,7 @@ paths: summary: Get Profile operationId: Get Profile - description: '' + description: 'Fetches the individual information of the logged in user to populate the Profile page.' tags: - Profile parameters: [] @@ -1398,8 +1427,7 @@ paths: summary: Patch User Profile operationId: Patch User Profile description: >- - Note that all fields are optional but at least one should be sent in the - request. + Updates the profile details of the logged in user, including changing password for authenticated/logged in users. Note: all fields are optional but at least one should be sent in the request. tags: - Profile parameters: @@ -1436,7 +1464,7 @@ paths: $ref: '#/responses/UnauthorizedResponse' summary: Get Organization Info operationId: Get Organization Info - description: '' + description: 'This endpoint returns the organization''s info. It is used in many places across the UI. It returns the name in the navbar and the public key of the organization’s distribution account.' tags: - Organization parameters: [] @@ -1459,6 +1487,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Patch Organization Profile operationId: Patch Organization Profile + description: 'Updates the organization profile details. Only account owners have permission to do this. Note: both fields are optional but at least one should be sent in the request. It is not necessary to set the header Content-Type for this request. It is set automatically by the HTTP client.' tags: - Organization parameters: [] @@ -1469,7 +1498,7 @@ paths: /organization/logo: get: summary: Retrieve Organization Logo - description: Retrieves the logo of the organization + description: 'Retrieves the logo of the organization for display in the UI navbar.' operationId: GetOrganizationLogo tags: - Organization @@ -1484,6 +1513,7 @@ paths: /countries: get: summary: Get a list of countries supported by this organization + description: 'Fetches the list of available countries to populate the dropdown box in the New Disbursement flow. The default list reflects geographic coverage of SDP-compatible wallet providers.' tags: - Organization responses: @@ -1499,9 +1529,12 @@ paths: $ref: '#/responses/ForbiddenResponse' produces: - application/json + security: + - BearerAuth: [] /assets: get: summary: Get a list of assets supported by this organization + description: 'Fetches the list of available assets to populate the dropdown box in the New Disbursement flow. Note: the organization must hold a balance in a particular asset to use it in a disbursement.' tags: - Organization responses: @@ -1517,9 +1550,110 @@ paths: $ref: '#/responses/ForbiddenResponse' produces: - application/json + security: + - BearerAuth: [] + post: + summary: Create Asset + description: 'This endpoint is used to create a new asset that can be used in a Disbursement. Note: the organization must hold a balance in a particular asset to use it in a disbursement.' + consumes: + - application/json + produces: + - application/json + tags: + - Organization + parameters: + - in: body + name: body + description: Asset to be created + required: true + schema: + type: object + properties: + code: + type: string + description: The asset code + example: 'USDC' + issuer: + type: string + description: The issuer + example: 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5' + required: + - code + - issuer + responses: + '201': + description: Asset created successfully + '400': + description: Bad request, invalid request body or the provided code/issuer is invalid. + security: + - BearerAuth: [] + /assets/{id}: + delete: + summary: Delete Asset + description: This endpoint is used to soft delete an asset. + produces: + - application/json + tags: + - Organization + parameters: + - name: id + in: path + description: ID of the asset to delete + required: true + type: string + responses: + '200': + description: Asset deleted successfully + '204': + description: Asset already deleted + '404': + description: Asset not found + security: + - BearerAuth: [] + patch: + summary: Update Asset + description: This endpoint is used to update the metadata of an existing asset. + consumes: + - application/json + produces: + - application/json + tags: + - Organization + parameters: + - name: id + in: path + description: ID of the asset to update + required: true + type: string + - in: body + name: body + description: Asset metadata to be updated + required: true + schema: + type: object + properties: + code: + type: string + description: The asset code + issuer: + type: string + description: The issuer + required: + - code + - issuer + responses: + '200': + description: Asset updated successfully + '400': + description: Bad request, invalid request body or the provided code/issuer is invalid + '404': + description: Asset not found + security: + - BearerAuth: [] /wallets: get: summary: Get a list of wallets supported by this organization + description: 'Fetches the list of available wallet providers to populate the dropdown box in the New Disbursement flow. The organization should coordinate with the wallet provider before selecting a particular wallet provider for a disbursement. The initial list reflects all SDP-compatible wallets.' tags: - Organization responses: @@ -1535,6 +1669,8 @@ paths: $ref: '#/responses/ForbiddenResponse' produces: - application/json + security: + - BearerAuth: [] /users: get: responses: @@ -1548,7 +1684,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Get All Users operationId: Get All Users - description: Returns all Users registered in the SDP. + description: 'Fetches all SDP users within the organization, whether they are active yet or not.' tags: - Users parameters: [] @@ -1568,7 +1704,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Create User operationId: Create User - description: Creates the authentication user and sends the invitation e-mail. + description: 'This endpoint creates a new SDP user as the result of an SDP owner adding their information in the UI. It also handles sending the invite email.' tags: - Users parameters: @@ -1613,7 +1749,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Patch User Activation operationId: Patch User Activation - description: Patchs the authentication user's activation in the SDP. + description: 'Updates the SDP user’s activation status. This endpoint is primarily used to move a user into active status when they accept the invite to join an SDP organization account and create a password.' tags: - Users parameters: @@ -1665,7 +1801,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Get All Roles operationId: Get All Roles - description: Returns all roles that exists in the SDP. + description: 'Fetches available SDP roles, such as owner, financial controller, business user, and developer.' tags: - Users parameters: [] @@ -1694,7 +1830,7 @@ paths: $ref: '#/responses/ForbiddenResponse' summary: Patch User Role operationId: Patch User Role - description: Patchs the authentication user's roles. + description: 'Updates an SDP user’s role by ```user_ID```.' tags: - Users parameters: @@ -1723,48 +1859,69 @@ definitions: properties: asset_code: type: "string" + example: 'USDC' asset_issuer: type: "string" + example: 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5' received_amount: type: "string" + example: '100.00' Asset: type: object properties: id: type: string + example: 'ffaec4b3-46b0-4db4-a4c4-6c3508057705' code: type: string + description: 'Asset code' + example: 'USDC' issuer: type: string + description: 'Asset issuer address' + example: 'GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5' created_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' updated_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' deleted_at: type: string format: date-time + example: '2023-06-03T10:55:51.000Z' Country: type: object properties: code: type: string + description: 'Country code in ISO 3166 alpha-3' + example: 'UKR' name: type: string + description: 'Country name' + example: 'Ukraine' created_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' updated_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' Disbursement: type: object properties: id: type: string + description: The unique identifier of the disbursement + example: '619da857-8725-4c58-933d-c120a458e0f5' name: type: string + description: The name of the disbursement + example: 'Disbursement Name' country: $ref: '#/definitions/Country' wallet: @@ -1772,22 +1929,78 @@ definitions: asset: $ref: '#/definitions/Asset' status: + description: The status of the disbursement $ref: '#/definitions/DisbursementStatus' + example: 'READY' verification_field: $ref: '#/definitions/VerificationField' + example: 'DATE_OF_BIRTH' status_history: $ref: '#/definitions/DisbursementStatusHistory' file_name: type: string - file_content: + example: 'disbursement-feb-03-2023.csv' + created_at: + type: string + format: date-time + example: '2023-02-03T10:45:51.000Z' + updated_at: + type: string + format: date-time + example: '2023-02-03T10:45:51.000Z' + total_payments: + type: integer + description: Total number of payments + example: 10 + total_payments_sent: + type: integer + description: Total number of successful payments + example: 8 + total_payments_failed: + type: integer + description: Total number of failed payments + example: 1 + total_payments_remaining: + type: integer + description: Total number of remaining payments + example: 1 + amount_disbursed: + type: string + description: The total amount disbursed so far + example: '800.00' + total_amount: + type: string + description: The total amount to be disbursed + example: '1000.00' + average_amount: + type: string + description: The average amount per payment + example: '100.00' + + DisbursementLite: + type: object + properties: + id: type: string - format: byte + format: uuid + description: The unique identifier of the disbursement + example: "c51ba1d5-52d3-412f-a59c-6ef32d59ab43" + name: + type: string + description: The name of the disbursement + example: "disbursement-june-29" + status: + $ref: '#/definitions/DisbursementStatus' created_at: type: string format: date-time + description: The creation timestamp of the disbursement + example: "2023-06-30T01:22:57.831975Z" updated_at: type: string format: date-time + description: The last update timestamp of the disbursement + example: "2023-06-30T01:22:58.316511Z" DisbursementPagination: type: "object" @@ -1798,18 +2011,68 @@ definitions: type: "array" items: $ref: '#/definitions/Disbursement' + example: + pagination: + next: "/disbursements?page=3&page_limit=1" + prev: "/disbursements?page=1&page_limit=1" + pages: 4 + total: 4 + data: + id: "619da857-8725-4c58-933d-c120a458e0f5" + name: "Disbursement Name" + country: + code: "UKR" + name: "Ukraine" + created_at: "2023-02-03T10:45:51.000Z" + updated_at: "2023-02-03T10:45:51.000Z" + wallet: + id: "e2de8544-b7e2-40a9-ad40-411f70d5c4bf" + name: "Vibrant" + homepage: "https://vibrantapp.com" + asset: + id: "25923001-508a-4629-9186-c41211b2a3d0" + code: "USDC" + issuer: "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5" + status: "READY" + verification_field: "DATE_OF_BIRTH" + status_history: [ + { + "user_id": null, + "status": "DRAFT", + "timestamp": "2023-02-03T10:45:51.000Z" + }, + { + "user_id": "2ec7f1f9-add3-4e6d-9d14-bd8ac5e88872", + "status": "READY", + "timestamp": "2023-02-03T10:45:51.000Z" + } + ] + file_name: "disbursement-february-03-2023.csv" + created_at: "2023-02-03T10:45:51.000Z" + updated_at: "2023-02-03T10:45:51.000Z" + total_payments: 10 + total_payments_sent: 8 + total_payments_failed: 1 + total_payments_remaining: 1 + amount_disbursed: '800.00' + total_amount: '1000.00' + average_amount: '100.00' DisbursementReceiver: type: object properties: id: type: string + example: 'ec3a57c0-5660-4b5a-af76-acadc7b09b93' email: type: string + example: 'receiver@mail.org' phone_number: type: string + example: '+15552368475' external_id: type: string + example: 'usr129001' receiver_wallet: $ref: '#/definitions/ReceiverWallet' payment: @@ -1817,9 +2080,11 @@ definitions: created_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' updated_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' DisbursementReceiverPagination: type: "object" @@ -1847,6 +2112,7 @@ definitions: type: integer description: Total number of receivers format: int64 + example: 100 DisbursementStatus: type: string @@ -1867,11 +2133,13 @@ definitions: properties: user_id: type: string + example: '3f351b9e-ed0f-40fa-a314-14757b42dab1' status: $ref: '#/definitions/DisbursementStatus' timestamp: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' GeneralStatistics: type: object @@ -1880,6 +2148,7 @@ definitions: type: integer description: Total number of disbursements format: int64 + example: 20 payment_counters: $ref: '#/definitions/PaymentCounters' payment_amounts_by_asset: @@ -1892,6 +2161,7 @@ definitions: type: integer description: Total number of receivers format: int64 + example: 1000 MessageResponse: type: object @@ -1906,38 +2176,45 @@ definitions: properties: name: type: string + example: 'Stellar Aid' logo_url: type: string + example: 'https://stellar-disbursement-platform-backend-dev.stellar.org/organization/logo' distribution_account_public_key: type: string + example: 'GCXAJ3XJ3VK3JFH3QMDFOSKM2NMMZBSO3VIT6EUPQWSDW2J74M23RRSL' timezone_utc_offset: type: string - example: - name: My Organization Name - logo_url: https://localhost:8000/organization/logo?token=mytoken - distribution_account_public_key: G... - timezone_utc_offset: '-03:00' + example: '+00:00' + Pagination: type: "object" properties: next: type: "string" + example: '?page=3&page_limit=2' prev: type: "string" + example: '?page=1&page_limit=2' pages: type: "integer" + example: 8 total: type: "integer" + example: 16 Payment: type: object properties: id: type: string + example: 'ddf22f55-3259-4822-a4e2-ce01334997f4' amount: type: string + example: '100.00' stellar_transaction_id: type: string + example: '0b339d1c89d314186b8147c2af4c9a9ed5bbdbcd7ada8d138633907649b' stellar_operation_id: type: string status: @@ -1945,17 +2222,19 @@ definitions: status_history: $ref: '#/definitions/PaymentStatusHistory' disbursement: - $ref: '#/definitions/Disbursement' + $ref: '#/definitions/DisbursementLite' asset: $ref: '#/definitions/Asset' receiver_wallet: - $ref: '#/definitions/ReceiverWallet' + $ref: '#/definitions/ReceiverWalletLite' created_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' updated_at: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' PaymentPagination: type: "object" @@ -1991,6 +2270,7 @@ definitions: timestamp: type: string format: date-time + example: '2023-02-03T10:45:51.000Z' PaymentCounters: type: object @@ -1998,29 +2278,37 @@ definitions: draft: type: integer format: int64 + example: 1 ready: type: integer format: int64 + example: 2 pending: type: integer format: int64 + example: 3 paused: type: integer format: int64 + example: 1 success: type: integer format: int64 + example: 5 failed: type: integer format: int64 + example: 1 total: type: integer format: int64 + example: 14 PaymentAmountsByAsset: type: object properties: asset_code: type: string + example: 'USDC' payment_amounts: $ref: '#/definitions/PaymentAmounts' PaymentAmounts: @@ -2028,30 +2316,41 @@ definitions: properties: draft: type: string + example: '100.00' ready: type: string + example: '200.00' pending: type: string + example: '300.00' paused: type: string + example: '100.00' success: type: string + example: '500.00' failed: type: string + example: '100.00' average: type: string + example: '100.00' total: type: string + example: '1400.00' Profile: type: object properties: first_name: type: string + example: 'Jane' last_name: type: string + example: 'Doe' email: type: string + example: 'jdoe@mail.org' roles: type: array items: @@ -2059,35 +2358,45 @@ definitions: organization_name: type: string example: - first_name: FirstName - last_name: LastName - email: email@email.com + first_name: Jane + last_name: Doe + email: jdoe@mail.org roles: - developer - organization_name: My Organization Name + organization_name: Stellar Aid Receiver: type: "object" properties: id: type: "string" + example: 'f83bb638-dda4-41e6-80c9-d03e6eec2aef' phone_number: type: "string" + example: '+15552368475' external_id: type: "string" + example: 'usr12334' email: type: "string" + example: 'jdoe@mail.org' created_at: type: "string" + example: '2023-02-03T10:45:51.000Z' total_payments: type: "string" + example: "2" successful_payments: type: "string" + example: "2" failed_payments: type: "string" + example: "0" remaining_payments: type: "string" + example: "0" registered_wallets: type: "string" + example: 1 received_amounts: type: "array" items: @@ -2102,6 +2411,7 @@ definitions: properties: id: type: "string" + example: '029e2ed0-feb6-4c40-8b47-0836a85741a2' ReceiverPagination: type: "object" @@ -2118,32 +2428,43 @@ definitions: properties: id: type: "string" + example: '803031d4-1d04-4879-b6d9-dc5641f9988e' receiver: $ref: '#/definitions/ReceiverLite' wallet: $ref: '#/definitions/WalletLite' stellar_address: type: "string" + example: 'GCXAJ3XJ3VK3JFH3QMDFOSKM2NMMZBSO3VIT6EUPQWSDW2J74M23RRSL' stellar_memo: type: "string" stellar_memo_type: type: "string" created_at: type: "string" + example: '2023-02-03T10:45:51.000Z' updated_at: type: "string" + example: '2023-02-03T10:45:51.000Z' invited_at: type: "string" + example: '2023-02-09T10:45:51.000Z' last_sms_sent: type: "string" + example: '2023-02-10T10:45:51.000Z' + description: 'timestamp when the receiver last received an SMS about this wallet' total_payments: type: "string" + example: "2" payments_received: type: "string" + example: "2" failed_payments: type: "string" + example: "0" remaining_payments: type: "string" + example: "0" received_amounts: type: "array" items: @@ -2155,24 +2476,51 @@ definitions: items: $ref: '#/definitions/ReceiversWalletStatusHistoryEntry' + ReceiverWalletLite: + type: "object" + properties: + id: + type: "string" + example: '803031d4-1d04-4879-b6d9-dc5641f9988e' + receiver: + $ref: '#/definitions/ReceiverLite' + wallet: + $ref: '#/definitions/WalletLite' + stellar_address: + type: "string" + example: 'GCXAJ3XJ3VK3JFH3QMDFOSKM2NMMZBSO3VIT6EUPQWSDW2J74M23RRSL' + created_at: + type: "string" + example: '2023-02-03T10:45:51.000Z' + updated_at: + type: "string" + example: '2023-02-03T10:45:51.000Z' + status: + $ref: '#/definitions/ReceiversWalletStatus' + ReceiverWalletsCounters: type: object properties: draft: type: integer format: int64 + example: 1 ready: type: integer format: int64 + example: 1 registered: type: integer format: int64 + example: 1 flagged: type: integer format: int64 + example: 1 total: type: integer format: int64 + example: 4 ReceiversWalletStatus: type: "string" @@ -2186,6 +2534,7 @@ definitions: timestamp: type: "string" format: "date-time" + example: '2023-02-10T10:45:51.000Z' Users: type: array @@ -2196,10 +2545,13 @@ definitions: properties: id: type: string + example: '1736bed3-7b92-4760-8ff2-51fb08ee079f' first_name: type: string + example: 'John' last_name: type: string + example: 'Doe' email: type: string roles: @@ -2241,30 +2593,40 @@ definitions: properties: id: type: string + example: '5ada9ed5-455a-4782-a0ee-160767e0deb1' name: type: string + example: 'Vibrant Assist' homepage: type: string + example: 'https://vibrantapp.com' sep_10_client_domain: type: string + example: 'api-dev.vibrantapp.com' deep_link_schema: type: string + example: 'https://vibrantapp.com/sdp-dev' created_at: type: string format: date-time + example: '2023-07-31T20:50:45.648Z' updated_at: type: string format: date-time + example: '2023-07-31T20:50:45.648Z' WalletLite: type: "object" properties: id: type: "string" + example: '5ada9ed5-455a-4782-a0ee-160767e0deb1' name: type: "string" + example: 'Vibrant Assist' homepage: type: "string" + example: 'https://vibrantapp.com' ReceiverRegistrationRequest: type: object @@ -2383,31 +2745,45 @@ securityDefinitions: type: "apiKey" name: "Authorization" in: "header" - description: "JWT used for authorization" + description: "JWT used for authentication, signed with an ES256 private key." tags: - name: Authentication - description: Endpoints related to authentication. + description: 'Authentication endpoints control the login, token refresh, and password management processes for SDP users.' - name: Disbursements - description: Endpoints related to disbursements. + description: 'Endpoints related to disbursements. A disbursement is a group of payments sent to multiple individuals at once. An SDP user with the appropriate role triggers a new disbursement through the SDP dashboard by uploading a list of receivers and amounts. When the receiver has linked their wallet to the SDP, the payment automatically begins. SDP users can track their disbursements in real-time through the SDP dashboard. Each disbursement must have a unique name defined by the organization.' - name: Payments - description: Endpoints related to payments. + description: 'Endpoints related to payments. An SDP payment is an individual payment from an organization to a receiver. Each payment is part of a disbursement and occurs on the Stellar network. Granular payment status is stored in the SDP database and can be viewed in real-time on the SDP dashboard. There is no POST endpoint because submitting payments to the Stellar network is handled by the Transaction Submission Service (TSS).' - name: Receivers description: >- - Endpoints related to receivers. The receiver is the user that is - going to receive the disbursement. + Endpoints related to receivers. A receiver is an individual receiving a payment in a disbursement. The receiver is tracked by phone number to reduce the need for personally identifiable information. Each receiver must be unique within the disbursement. + + + Each receiver will have at least one wallet associated with them. The wallet public key will remain null until the receiver registers with a wallet provider and links the wallet to the SDP through SEP-24. Receivers must verify their identity through that process, which requires the SDP to store verification information on receivers like date of birth, national ID number, or personal PIN. This information can be updated by the organization through the receiver endpoints. + - name: Statistics description: >- - Endpoints related to statistics that provide general aggregated data, as - well as disbursement-specific aggregated data. + Statistics endpoints return general aggregated data per organization, as well as disbursement-specific metrics. SDP users can use this data to monitor their disbursements over time. - name: Anchor description: >- - Endpoints related to authenticating a receiver wallet and initiating the registration - process with the Stellar Disbursement Platform. + These endpoints must be hit by the wallet provider to link the receiver’s new public key to the SDP. + - name: Registration description: >- - These endpoints will be used by the PII confirmation webpage during wallet registration. + The registration endpoints guide the process for a receiver to verify their identity and link their wallet address to an SDP. + + + The registration process only needs to happen once per receiver to link their wallet. Only SDP-compatible wallet providers can facilitate the registration process. These endpoints must be supported and hit by the wallet providers after the receiver gets the initial SMS invite. After the wallet address is successfully linked, the payment automatically begins. + + + The SDP<>wallet registration process uses SEP-10, SEP-24, and deep links. Please see the SDP [developer docs](https://developers.stellar.org/docs/category/use-the-stellar-disbursement-platform) for a full set of instructions for wallet providers to become SDP-compatible. - name: Profile - description: Endpoints related to user profiles. + description: >- + Profiles endpoints manage the process of getting and updating individual profile information. Profile information is set when the account is created and can be updated by the user on the SDP dashboard Profile page. Note: profiles never refer to receivers of funds. + + - name: Organization + description: >- + Organization endpoints manage the process of getting and updating organizational profile information. The organization’s profile has basic information set at the time of SDP deployment. It can be modified by the Owner. Organizations can also manage their preferences, like which assets to use, through these endpoints. + - name: Users description: >- - Defines all the endpoints regarding users of the SDP. \ No newline at end of file + The users endpoints facilitate the creation of new SDP users–including setting the appropriate role, sending an email invitation, and activating a user–and managing roles. \ No newline at end of file