Stellar Registration API

openapi: 3.1.0
info:
  version: 3.0.0
  title: Platform Server Accounts Registration API
  description: 'The platform server is an internal component. It should be hosted in a private network and should not be accessible from the Internet. This server enables the business to fetch and update the state of transactions using its API.

    '
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://platform-server.exampleanchor.com
tags:
- name: Registration
  description: '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 invite. After the wallet address is successfully linked, the payment automatically begins.


    There are two parts to the registration flow. First, the wallet must authenticate and initiate a registration flow using the Anchor Platform Endpoints defined below. Note that these endpoints are hosted on a different host than the Stellar Disursement Platform.


    The second part of the registration flow is handled by the webview that is opened within the wallet application. This webview uses the endpoints defined in the Stellar Disbursement Platfrom Endpoints section to complete the registration process. The wallet application can chose not to use the webview and intstead integrate directly with the API.

    '
paths:
  /sep24-interactive-deposit/info:
    get:
      tags:
      - Registration
      summary: Get Receiver Registration Info
      description: Returns the registration context for the receiver, including organization details and reCAPTCHA configuration.
      operationId: GetReceiverRegistrationInfo
      responses:
        '200':
          description: Registration context
          content:
            application/json:
              schema:
                type: object
                properties:
                  privacy_policy_link:
                    type: string
                  organization_name:
                    type: string
                  organization_logo:
                    type: string
                  truncated_contact_info:
                    type: string
                  is_registered:
                    type: boolean
                  is_recaptcha_disabled:
                    type: boolean
                  recaptcha_site_key:
                    type: string
              example:
                privacy_policy_link: https://example.com/privacy
                organization_name: Stellar Aid
                organization_logo: https://example.com/logo.png
                truncated_contact_info: '******1234'
                is_registered: false
                is_recaptcha_disabled: false
                recaptcha_site_key: 6Lc...site_key
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
      - SEP24Auth: []
  /sep24-interactive-deposit/otp:
    post:
      tags:
      - Registration
      summary: Send One-Time Passcode
      description: This endpoint generates a 6-digit OTP and sends it to the user contact (email or phone number SMS) provided in the request body, as long as it matches the receiver contact info stored in the SDP. A valid SEP-24 token should be included in this request's Authorization header.
      operationId: SendOneTimePasscode
      requestBody:
        description: Object containing phone number
        content:
          application/json:
            schema:
              required:
              - recaptcha_token
              type: object
              properties:
                phone_number:
                  type: string
                  description: Phone number to which the OTP will be sent. Either `phone_number` or `email` is required.
                email:
                  type: string
                  description: Email to which the OTP will be sent. Either `phone_number` or `email` is required.
                recaptcha_token:
                  type: string
                  description: Token for reCAPTCHA validation (required unless reCAPTCHA is disabled).
        required: true
      responses:
        '200':
          description: OTP sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  verification_field:
                    $ref: '#/components/schemas/VerificationField'
              example:
                message: if your phone number is registered, you'll receive an OTP
                verification_field: DATE_OF_BIRTH
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error
                  extras:
                    type: object
                    properties: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  extras:
                    type: object
                    properties:
                      status:
                        type: number
                      message:
                        type: string
                example:
                  error: Not authorized
                  extras:
                    status: 401
                    message: Not authorized
              example:
                error: Not authorized
                extras:
                  status: 401
                  message: Not authorized
      security:
      - SEP24Auth: []
      x-codegen-request-body-name: body
  /sep24-interactive-deposit/verification:
    post:
      tags:
      - Registration
      summary: Verify Receiver Registration
      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.
      operationId: VerifyReceiverRegistration
      requestBody:
        description: Verification data including phone_number/email, OTP, verification value, and reCAPTCHA token
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiverRegistrationRequest'
        required: true
      responses:
        '200':
          description: Verification successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: ok
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Details about the error
                  extras:
                    type: object
                    properties: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  extras:
                    type: object
                    properties:
                      status:
                        type: number
                      message:
                        type: string
                example:
                  error: Not authorized
                  extras:
                    status: 401
                    message: Not authorized
              example:
                error: Not authorized
                extras:
                  status: 401
                  message: Not authorized
      security:
      - SEP24Auth: []
      x-codegen-request-body-name: body
  /wallet-registration/start:
    get:
      tags:
      - Registration
      summary: Start Wallet Registration
      description: Serves the SEP-24 interactive registration UI.
      operationId: StartWalletRegistration
      parameters:
      - name: token
        in: query
        description: SEP-24 token for authorization.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: transaction_id
        in: query
        description: SEP-24 transaction ID.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: lang
        in: query
        description: Optional language override for the webview.
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: HTML webview for receiver registration.
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Bad Request
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
      - SEP24QueryAuth: []
  /.well-known/stellar.toml:
    get:
      tags:
      - Registration
      summary: Retrieve Stellar Info File
      description: Allows the wallet to fetch the SEP-10 server url, SEP-10 signing public key and SEP-24 server url.
      operationId: RetrieveStellarInfoFile
      responses:
        '200':
          description: Token is valid and the webpage will be loaded normally.
          content:
            text/toml:
              example: 'ACCOUNTS=["GBC2HVWFIFN7WJHFORVBCDKJORXXXXXXXXXXXXXXXXXXXXXXXX", "GDA34JZ26FZY64XCSY46CUNSHLX762LHJXQXXXXXXXXXXXXXXXXXXXXXXXX"] SIGNING_KEY="GDA34JZ26FZY64XCSY46XXXXXXXXXXXXXXXXXXXXXXXX" NETWORK_PASSPHRASE="Test SDF Network ; September 2015" HORIZON_URL="https://horizon-testnet.stellar.org" WEB_AUTH_ENDPOINT="https://ap-stellar-disbursement-platform-backend-dev.stellar.org/sep10/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"

                '
  /sep10/auth:
    get:
      tags:
      - Registration
      summary: Request Challenge Transaction
      description: 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.
      operationId: RequestChallengeTransaction
      parameters:
      - name: account
        in: query
        description: The client account (G...) that the client wishes to authenticate with the server.
        required: true
        style: form
        explode: true
        schema:
          type: string
      - name: memo
        in: query
        description: The memo to attach to the challenge transaction. Only permitted if a Stellar account (G...) is used. The memo must be of type id. Other memo types are not supported.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: home_domain
        in: query
        description: Home domain for SEP-10. Defaults to the server base domain if omitted.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: client_domain
        in: query
        description: Client domain for wallet attribution. Required when SEP-10 client attribution is enabled (default).
        required: false
        style: form
        explode: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  transaction:
                    type: string
                  network_passphrase:
                    type: string
                example:
                  transaction: AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX+F4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST/fImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAfheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA+xM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3Ag==
                  network_passphrase: Test SDF Network ; September 2015
              example:
                transaction: AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX+F4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST/fImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAfheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA+xM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3Ag==
                network_passphrase: Test SDF Network ; September 2015
        '400':
          description: Bad Request
          $ref: '#/components/responses/BadRequestResponse'
    post:
      tags:
      - Registration
      summary: Provide Signed Challenge Transaction
      description: 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.
      operationId: ProvideSignedChallengeTransaction
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction:
                  type: string
            example:
              transaction: AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX+F4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST/fImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAvheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA+xM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3AsiYk3UAAABArIrkvqmA0V9lIZcVyCUdja6CiwkPwsV8BfI4CZOyR1Oq7ysvNJWwY0G42dpxN9OP1qz4dum8apG2hqvxVWjkDQ==
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                transaction:
                  type: string
              example:
                transaction: AAAAAgAAAADIiRu2BrqqeOcP28PWCkD4D5Rjjsqh71HwvqFX+F4VXAAAAGQAAAAAAAAAAAAAAAEAAAAAXzrUcQAAAABfOtf1AAAAAAAAAAEAAAABAAAAAEEB8rhqNa70RYjaNnF1ARE2CbL50iR9HPXST/fImJN1AAAACgAAADB0aGlzaXNhdGVzdC5zYW5kYm94LmFuY2hvci5hbmNob3Jkb21haW4uY29tIGF1dGgAAAABAAAAQGdGOFlIQm1zaGpEWEY0L0VJUFZucGVlRkxVTDY2V0tKMVBPYXZuUVVBNjBoL09XaC91M2Vvdk54WFJtSTAvQ2UAAAAAAAAAAvheFVwAAABAheKE1HjGnUCNwPbX8mz7CqotShKbA+xM2Hbjl6X0TBpEprVOUVjA6lqMJ1j62vrxn1mF3eJzsLa9s9hRofG3AsiYk3UAAABArIrkvqmA0V9lIZcVyCUdja6CiwkPwsV8BfI4CZOyR1Oq7ysvNJWwY0G42dpxN9OP1qz4dum8apG2hqvxVWjkDQ==
        required: true
      responses:
        '200':
          description: SEP-10 handshake was successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                example:
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJHQTZVSVhYUEVXWUZJTE5VSVdBQzM3WTRRUEVaTVFWREpIREtWV0ZaSjJLQ1dVQklVNUlYWk5EQSIsImp0aSI6IjE0NGQzNjdiY2IwZTcyY2FiZmRiZGU2MGVhZTBhZDczM2NjNjVkMmE2NTg3MDgzZGFiM2Q2MTZmODg1MTkwMjQiLCJpc3MiOiJodHRwczovL2ZsYXBweS1iaXJkLWRhcHAuZmlyZWJhc2VhcHAuY29tLyIsImlhdCI6MTUzNDI1Nzk5NCwiZXhwIjoxNTM0MzQ0Mzk0fQ.8nbB83Z6vGBgC1X9r3N6oQCFTBzDiITAfCJasRft0z0
              example:
                token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJHQTZVSVhYUEVXWUZJTE5VSVdBQzM3WTRRUEVaTVFWREpIREtWV0ZaSjJLQ1dVQklVNUlYWk5EQSIsImp0aSI6IjE0NGQzNjdiY2IwZTcyY2FiZmRiZGU2MGVhZTBhZDczM2NjNjVkMmE2NTg3MDgzZGFiM2Q2MTZmODg1MTkwMjQiLCJpc3MiOiJodHRwczovL2ZsYXBweS1iaXJkLWRhcHAuZmlyZWJhc2VhcHAuY29tLyIsImlhdCI6MTUzNDI1Nzk5NCwiZXhwIjoxNTM0MzQ0Mzk0fQ.8nbB83Z6vGBgC1X9r3N6oQCFTBzDiITAfCJasRft0z0
        '400':
          description: Bad Request
          $ref: '#/components/responses/BadRequestResponse'
      x-codegen-request-body-name: body
  /sep24/info:
    get:
      tags:
      - Registration
      summary: SEP-24 Info
      description: Returns supported assets and feature flags for SEP-24 registration deposits.
      operationId: GetSEP24Info
      responses:
        '200':
          description: SEP-24 info response
          content:
            application/json:
              schema:
                type: object
                properties:
                  deposit:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        min_amount:
                          type: number
                        max_amount:
                          type: number
                  withdraw:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        enabled:
                          type: boolean
                        min_amount:
                          type: number
                        max_amount:
                          type: number
                  fee:
                    type: object
                    properties:
                      enabled:
                        type: boolean
                  features:
                    type: object
                    properties:
                      account_creation:
                        type: boolean
                      claimable_balances:
                        type: boolean
  /sep24/transactions/deposit/interactive:
    post:
      tags:
      - Registration
      summary: Request Registration URL
      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).

        '
      operationId: RequestRegistrationURL
      externalDocs:
        description: Find more info here
        url: https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0024.md#deposit-2
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - asset_code
              properties:
                asset_code:
                  type: string
                  description: Stellar asset code for the deposit.
                account:
                  type: string
                  description: Stellar account for the deposit; defaults to the SEP-10 subject.
                lang:
                  type: string
                  description: Language for the interactive flow.
                claimable_balance_supported:
                  type: string
                  description: Indicates if claimable balances are supported.
            example:
              asset_code: USDC
              account: GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI
              lang: en
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - asset_code
              properties:
                asset_code:
                  type: string
                  description: Stellar asset code for the deposit.
                account:
                  type: string
                  description: Stellar account for the deposit; defaults to the SEP-10 subject.
                lang:
                  type: string
                  description: Language for the interactive flow.
                claimable_balance_supported:
                  type: string
                  description: Indicates if claimable balances are supported.
            example:
              asset_code: USDC
              account: GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI
              lang: en
        required: false
      responses:
        '200':
          description: An anchor requires the user to fill out information on a webpage hosted by the anchor.
          content:
            application/json:
              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
        '400':
          description: Bad Request
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
      security:
      - SEP10Auth: []
components:
  responses:
    BadRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Details about the error
              extras:
                type: object
                properties: {}
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              extras:
                type: object
                properties:
                  status:
                    type: number
                  message:
                    type: string
          example:
            error: Not authorized
            extras:
              status: 401
              message: Not authorized
  schemas:
    VerificationField:
      type: string
      enum:
      - DATE_OF_BIRTH
      - YEAR_MONTH
      - PIN
      - NATIONAL_ID_NUMBER
    ReceiverRegistrationRequest:
      type: object
      properties:
        email:
          type: string
          description: Email associated with the receiver in the SDP database. Either `phone_number` or `email` is required.
        phone_number:
          type: string
          description: Phone number associated with the receiver in the SDP database. Either `phone_number` or `email` is required.
        otp:
          type: string
          description: One-Time Password received for verification
        verification:
          type: string
          description: Verification value provided by the user
        verification_field:
          $ref: '#/components/schemas/VerificationField'
        recaptcha_token:
          type: string
          description: Token received from Google reCAPTCHA