Stellar Payments API

openapi: 3.1.0
info:
  version: 3.0.0
  title: Platform Server Accounts Payments 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: 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.
paths:
  /payments:
    get:
      tags:
      - Payments
      summary: List All Payments
      description: Returns all individual payments matching the request criteria. This endpoint supports pagination, and filtering on payment status, type, receiver ID, and timestamp. Each payment has details on the transaction itself, receiver, disbursement, asset, status history, and blockchain information.
      operationId: ListAllPayments
      parameters:
      - name: page
        in: query
        description: The page requested.
        required: false
        style: form
        explode: true
        schema:
          type: number
          default: 1
      - name: q
        in: query
        description: Search payments by ID, external_payment_id, receiver wallet address, or disbursement name.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: type
        in: query
        description: Type of payments
        required: false
        style: form
        explode: true
        schema:
          type: string
          enum:
          - DIRECT
          - DISBURSEMENT
      - name: page_limit
        in: query
        description: Define how many results will be returned in the response.
        required: false
        style: form
        explode: true
        schema:
          type: number
          default: 20
      - name: status
        in: query
        description: Exact match on the status of the payment.
        required: false
        style: form
        explode: true
        schema:
          type: string
          enum:
          - DRAFT
          - READY
          - PENDING
          - PAUSED
          - SUCCESS
          - FAILED
          - CANCELED
        example: DRAFT
      - name: receiver_id
        in: query
        description: UUID that represents a receiver in the database
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: b6b667ad-6cc2-46cf-9be7-561daace7d48
      - name: created_at_after
        in: query
        description: 'Only return payments that are created after this date. Format: YYYY-MM-DD'
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: '2006-01-02'
      - name: created_at_before
        in: query
        description: 'Only return payments that are created before this date. Format: YYYY-MM-DD'
        required: false
        style: form
        explode: true
        schema:
          type: string
        example: '2006-01-02'
      - name: sort
        in: query
        description: Field used to sort payments
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: updated_at
          enum:
          - updated_at
          - created_at
      - name: direction
        in: query
        description: Direction for sorting payments.
        required: false
        style: form
        explode: true
        schema:
          type: string
          default: desc
          enum:
          - asc
          - desc
      responses:
        '200':
          description: A paginated list of payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPagination'
        '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
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                example:
                  error: Forbidden
              example:
                error: Forbidden
      security:
      - BearerAuth: []
    post:
      tags:
      - Payments
      summary: Create Direct Payment
      description: Creates a new direct payment that is immediately sent to the specified receiver if they have a valid registered wallet. Direct payments bypass the disbursement workflow and are processed instantly.
      operationId: CreateDirectPayment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDirectPaymentRequest'
        required: true
      responses:
        '201':
          description: Direct payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Bad Request
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          description: Not Found
          $ref: '#/components/responses/NotFoundResponse'
      security:
      - BearerAuth: []
  /payments/{id}:
    get:
      tags:
      - Payments
      summary: Retrieve a Payment
      description: Fetches detailed information on a specific payment by  `id `.
      operationId: RetrieveAPayment
      parameters:
      - name: id
        in: path
        description: ID of the `Payment`.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '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
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                example:
                  error: Forbidden
              example:
                error: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  extras:
                    type: object
                    properties:
                      status:
                        type: number
                      message:
                        type: string
                example:
                  error: Not found
                  extras:
                    status: 404
                    message: Payment not found
              example:
                error: Not found
                extras:
                  status: 404
                  message: Payment not found
      security:
      - BearerAuth: []
  /payments/retry:
    patch:
      tags:
      - Payments
      summary: Retry Payments
      description: Retries failed payments by ID.
      operationId: RetryPayments
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - payment_ids
              properties:
                payment_ids:
                  type: array
                  items:
                    type: string
            example:
              payment_ids:
              - 9f687f8f-1f8f-4c8a-8e0f-1e67ed7c1330
              - 6c2b9f20-53fd-4f1b-b7e2-9a2b1eb1d7c0
        required: true
      responses:
        '200':
          description: Payments retried successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Payments retried successfully
        '400':
          description: Bad Request
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
      security:
      - BearerAuth: []
  /payments/{id}/status:
    patch:
      tags:
      - Payments
      summary: Update Payment Status
      description: Cancels a payment by setting its status to `CANCELED`.
      operationId: UpdatePaymentStatus
      parameters:
      - name: id
        in: path
        description: ID of the `Payment`.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              properties:
                status:
                  type: string
                  enum:
                  - CANCELED
            example:
              status: CANCELED
        required: true
      responses:
        '200':
          description: Payment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
              example:
                message: Payment canceled
        '400':
          description: Bad Request
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          description: Unauthorized
          $ref: '#/components/responses/UnauthorizedResponse'
        '403':
          description: Forbidden
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          description: Not Found
          $ref: '#/components/responses/NotFoundResponse'
      security:
      - BearerAuth: []
  /transactions/{transaction_hash}/payments:
    get:
      tags:
      - Payments
      summary: Retrieve a Transaction's Payments
      description: This endpoint returns the payments of a specific transaction.
      operationId: RetrieveATransactionsPayments
      parameters:
      - $ref: '#/components/parameters/HashParam'
      - $ref: '#/components/parameters/CursorParam'
      - $ref: '#/components/parameters/OrderParam'
      - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Links'
                - $ref: '#/components/schemas/Payment_2'
              examples:
                RetrieveATransactionsPayments:
                  $ref: '#/components/examples/RetrieveATransactionsPayments'
components:
  schemas:
    PaymentStatusHistoryEntry:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/PaymentStatus'
        status_message:
          type: string
        timestamp:
          type: string
          format: date-time
          example: '2023-02-03T10:45:51Z'
    PaymentStatusHistory:
      type: array
      description: An aggregated list of metadata objects containing the statuses and the timestamp of when these status changes occurred.
      items:
        $ref: '#/components/schemas/PaymentStatusHistoryEntry'
    id:
      type: string
    RegistrationContactType:
      type: string
      enum:
      - EMAIL
      - PHONE_NUMBER
      - EMAIL_AND_WALLET_ADDRESS
      - PHONE_NUMBER_AND_WALLET_ADDRESS
    ReceiversWalletStatusHistoryEntry:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ReceiversWalletStatus'
        timestamp:
          type: string
          format: date-time
          example: '2023-02-10T10:45:51Z'
    PaymentPagination:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
    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
        sep_10_client_domain:
          type: string
          example: api-dev.vibrantapp.com
        deep_link_schema:
          type: string
          example: https://vibrantapp.com/sdp-dev
        enabled:
          type: boolean
          example: true
        user_managed:
          type: boolean
          example: false
    VerificationField:
      type: string
      enum:
      - DATE_OF_BIRTH
      - YEAR_MONTH
      - PIN
      - NATIONAL_ID_NUMBER
    Links:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/link'
            next:
              $ref: '#/components/schemas/link'
            prev:
              $ref: '#/components/schemas/link'
    ReceiverWalletLite:
      type: object
      properties:
        id:
          type: string
          example: 803031d4-1d04-4879-b6d9-dc5641f9988e
        receiver:
          $ref: '#/components/schemas/ReceiverLite'
        wallet:
          $ref: '#/components/schemas/WalletLite'
        stellar_address:
          type: string
          example: GCXAJ3XJ3VK3JFH3QMDFOSKM2NMMZBSO3VIT6EUPQWSDW2J74M23RRSL
        stellar_memo:
          type: string
        stellar_memo_type:
          type: string
        sep24_transaction_id:
          type: string
        created_at:
          type: string
          example: '2023-02-03T10:45:51.000Z'
        updated_at:
          type: string
          example: '2023-02-03T10:45:51.000Z'
        invitation_sent_at:
          type: string
          example: '2023-02-09T10:45:51.000Z'
        status:
          $ref: '#/components/schemas/ReceiversWalletStatus'
        status_history:
          type: array
          items:
            $ref: '#/components/schemas/ReceiversWalletStatusHistoryEntry'
        otp_confirmed_at:
          type: string
          format: date-time
          example: '2023-02-10T10:45:51Z'
        otp_confirmed_with:
          type: string
    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
    MessageResponse:
      required:
      - message
      type: object
      properties:
        message:
          type: string
    Payment_2:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            records:
              type: array
              items:
                type: object
                properties:
                  _links:
                    type: object
                    properties:
                      self:
                        $ref: '#/components/schemas/link'
                      transaction:
                        $ref: '#/components/schemas/link'
                      effects:
                        $ref: '#/components/schemas/link'
                      succeeds:
                        $ref: '#/components/schemas/link'
                      precedes:
                        $ref: '#/components/schemas/link'
                    required:
                    - self
                    - transaction
                    - effects
                    - succeeds
                    - precedes
                  id:
                    $ref: '#/components/schemas/id'
                  paging_token:
                    type: string
                  transaction_successful:
                    type: boolean
                  source_account:
                    $ref: '#/components/schemas/address'
                  type:
                    type: string
                    example: payment
                  type_i:
                    type: string
                  created_at:
                    type: string
                  transaction_hash:
                    type: string
                  asset_type:
                    type: string
                  asset_code:
                    enum:
                    - native
                    - credit_alphanum4
                    - credit_alphanum12
                  asset_issuer:
                    $ref: '#/components/schemas/address'
                  from:
                    $ref: '#/components/schemas/address'
                  to:
                    $ref: '#/components/schemas/address'
                  amount:
                    type: string
                required:
                - id
                - paging_token
                - transaction_successful
                - source_account
                - type
                - type_i
                - created_at
                - transaction_hash
                - asset_type
                - from
                - to
                - amount
    CreateDirectPaymentRequest:
      type: object
      required:
      - amount
      - asset
      - receiver
      - wallet
      properties:
        amount:
          type: string
          description: The payment amount
        asset:
          type: object
          properties:
            id:
              type: string
              description: Asset ID (use either id or type)
            type:
              type: string
              enum:
              - native
              - classic
              - contract
              - fiat
              description: Asset type (use either id or type)
            code:
              type: string
              description: Asset code (required for classic and fiat assets)
            issuer:
              type: string
              description: Asset issuer address (required for classic assets)
            contract_id:
              type: string
              description: Contract ID (required for contract assets)
          description: Asset reference - specify either id or type with required fields
        receiver:
          type: object
          properties:
            id:
              type: string
              description: Receiver ID
            email:
              type: string
              description: Receiver email address
            phone_number:
              type: string
              description: Receiver phone number
            wallet_address:
              type: string
              description: Receiver wallet address (Stellar account or contract)
          description: Receiver reference - specify exactly one identifier
        wallet:
          type: object
          properties:
            id:
              type: string
              description: Wallet ID
            address:
              type: string
              description: Wallet address (Stellar account or contract)
          description: Wallet reference - specify either id or address
        external_payment_id:
          type: string
          description: Optional external payment identifier
    PaymentStatus:
      type: string
      description: The status of the payment
      enum:
      - DRAFT
      - READY
      - PENDING
      - PAUSED
      - SUCCESS
      - FAILED
      - CANCELED
    DisbursementStatusHistory:
      type: array
      items:
        $ref: '#/components/schemas/DisbursementStatusHistoryEntry'
    DisbursementStatus:
      type: string
      enum:
      - DRAFT
      - READY
      - STARTED
      - PAUSED
      - COMPLETED
    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:51Z'
        updated_at:
          type: string
          format: date-time
          example: '2023-02-03T10:45:51Z'
        deleted_at:
          type: string
          format: date-time
          example: '2023-06-03T10:55:51Z'
      description: The Stellar asset object
    DisbursementStatusHistoryEntry:
      type: object
      properties:
        user_id:
          type: string
          example: 3f351b9e-ed0f-40fa-a314-14757b42dab1
        status:
          $ref: '#/components/schemas/DisbursementStatus'
        timestamp:
          type: string
          format: date-time
          example: '2023-02-03T10:45:51Z'
    address:
      type: string
      pattern: G[A-Z0-9]{55}
    ReceiversWalletStatus:
      type: string
      enum:
      - DRAFT
      - READY
      - REGISTERED
      - FLAGGED
    DisbursementLite:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the disbursement
          format: uuid
          example: c51ba1d5-52d3-412f-a59c-6ef32d59ab43
        name:
          type: string
          description: The name of the disbursement
          example: disbursement-june-29
        receiver_registration_message_template:
          type: string
          description: 'The custom template used to send invitations to receivers. The `default` message isn''t returned. In the message''s content it''s possible to add the following template variables: `{{.OrganizationName}}` which is the Organization Name configured and `{{.RegistrationLink}}` which is the link generated by SDP to send to the receiver (in case this is not present in the message, it''s automatically appended at the end).'
          example: You have a payment waiting for you from {{.OrganizationName}}. Click {{.RegistrationLink}} to register.
        registration_contact_type:
          $ref: '#/components/schemas/RegistrationContactType'
        status:
          $ref: '#/components/schemas/DisbursementStatus'
        verification_field:
          $ref: '#/components/schemas/VerificationField'
        status_history:
          $ref: '#/components/schemas/DisbursementStatusHistory'
        file_name:
          type: string
          example: disbursement-feb-03-2023.csv
        created_at:
          type: string
          description: The creation timestamp of the disbursement
          format: date-time
          example: '2023-06-30T01:22:57.831975Z'
        updated_at:
          type: string
          description: The last update timestamp of the disbursement
          format: date-time
          example: '2023-06-30T01:22:58.316511Z'
    link:
      type: object
      properties:
        href:
          type: string
          format: link
        templated:
          type: boolean
      required:
      - href
    Payment:
      type: object
      properties:
        id:
          type: string
          example: ddf22f55-3259-4822-a4e2-ce01334997f4
        amount:
          type: string
          description: The amount of the payment
          example: '100.00'
        stellar_transaction_id:
          type: string
          description: The ID of the transaction in the Stellar network. It can be used tio track the payment in the Stellar network using [Stellar Laboratory](https://laboratory.stellar.org/), or [StellarExpert](https://stellar.expert/).
          example: 0b339d1c89d314186b8147c2af4c9a9ed5bbdbcd7ada8d138633907649b
        circle_transfer_request_id:
          type: string
          description: The Circle transfer request ID. It is only present when the payment was made using Circle.
          example: 74a68b6a-3f67-424b-b8b0-e593a19d7463
        stellar_operation_id:
          type: string
        status:
          $ref: '#/components/schemas/PaymentStatus'
        status_history:
          $ref: '#/components/schemas/PaymentStatusHistory'
        type:
          type: string
          description: The type of the payment.
          enum:
          - DISBURSEMENT
          - DIRECT
        disbursement:
          $ref: '#/components/schemas/DisbursementLite'
        asset:
          $ref: '#/components/schemas/Asset'
        receiver_wallet:
          $ref: '#/components/schemas/ReceiverWalletLite'
        external_payment_id:
          type: string
          description: Optional external payment identifier provided by the client.
          example: payment-001
        created_at:
          type: string
          format: date-time
          example: '2023-02-03T10:45:51Z'
        updated_at:
          type: string
          format: date-time
          example: '2023-02-03T10:45:51Z'
    ReceiverLite:
      type: object
      properties:
        id:
          type: string
          example: 029e2ed0-feb6-4c40-8b47-0836a85741a2
  parameters:
    OrderParam:
      name: order
      in: query
      required: false
      description: A designation of the order in which records should appear. Options include `asc` (ascending) or `desc` (descending). If this argument isn’t set, it defaults to `asc`.
      schema:
        type: string
        enum:
        - asc
        - desc
    CursorParam:
      name: cursor
      in: query
      required: false
      description: A number that points to a specific location in a collection of responses and is pulled from the paging_token value of a record.
      schema:
        type: integer
        example: 6606617478959105
    HashParam:
      name: transaction_hash
      in: path
      required: true
      description: Transactions are commands that modify the ledger state and consist of one or more operations.
      schema:
        type: string
        example: 5ebd5c0af4385500b53dd63b0ef5f6e8feef1a7e1c86989be3cdcce825f3c0cc
    LimitParam:
      name: limit
      in: query
      required: false
      description: The maximum number of records returned. The limit can range from 1 to 200 - an upper limit that is hardcoded in Horizon for performance reasons. If this argument isn’t designated, it defaults to 10.
      schema:
        type: integer
        example: 10
  responses:
    NotFoundResponse:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              extras:
                type: object
                properties:
                  status:
                    type: number
                  message:
                    type: string
          example:
            error: Not found
            extras:
              status: 404
              message: Resource not found
    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
    BadRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: Details about the error
              extras:
                type: object
                properties: {}
    ForbiddenResponse:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
          example:
            error: Forbidden
  examples:
    RetrieveATransactionsPayments:
      value:
        _links:
          self:
            href: https://horizon-testnet.stellar.org/transactions/f8929884dfc56ff9d8bc220c7bfba9e58208943eba96f33e8a0787a5bb8a4629/payments?cursor=&limit=10&order=asc
          next:
            href: https://horizon-testnet.stellar.org/transactions/f8929884dfc56ff9d8bc220c7bfba9e58208943eba96f33e8a0787a5bb8a4629/payments?cursor=3382840796385281&limit=10&order=asc
          prev:
            href: https://horizon-testnet.stellar.org/transactions/f8929884dfc56ff9d8bc220c7bfba9e58208943eba96f33e8a0787a5bb8a4629/payments?cursor=3382840796385281&limit=10&order=desc
        _embedded:
          records:
            _links:
              self:
                href: https://horizon-testnet.stellar.org/operations/3382840796385281
              transaction:
                href: https://horizon-testnet.stellar.org/transactions/f8929884dfc56ff9d8bc220c7bfba9e58208943eba96f33e8a0787a5bb8a4629
              effects:
                href: https://horizon-testnet.stellar.org/operations/3382840796385281/effects
              succeeds:
                href: https://horizon-testnet.stellar.org/effects?order=desc&cursor=3382840796385281
              precedes:
                href: https://horizon-testnet.stellar.org/effects?order=asc&cursor=3382840796385281
            id: '3382840796385281'
            paging_token: '3382840796385281'
            transaction_successful: true
            source_account: GCNEGL4IYJ4XH2GV62QK4PQ5D4YWSYZPBC3NVF6VMNSFUMBFW3V3DKKY
            type: account_merge
            type_i: 8
            created_at: '2024-07-29T19:33:23Z'
            transaction_hash: f8929884dfc56ff9d8bc220c7bfba9e58208943eba96f33e8a0787a5bb8a4629
            account: GCNEGL4IYJ4XH2GV62QK4PQ5D4YWSYZPBC3NVF6VMNSFUMBFW3V3DKKY
            into: GBFAIH5WKAJQ77NG6BZG7TGVGXHPX4SQLIJ7BENJMCVCZSUZPSISCLU5