openapi: 3.0.3
info:
  title: RushPay Core API
  version: 2.1.0
  description: >-
    RushPay Core v2 is a JSON REST API for merchant checkout, wallet payments,
    mobile money, card funding, gift cards, settlements, and signed webhooks.
    Merchant server routes authenticate with the X-API-Key header. Browser
    checkout uses a short-lived X-RushPay-Widget-Session token scoped to a single
    payment_reference. Dashboard routes use a Bearer access token.
  contact:
    name: RushPay Developer Support
    url: https://core.rushpay.cash/api-docs
servers:
  - url: https://core.rushpay.cash
    description: Production
tags:
  - name: Merchant Applications
    description: Create and manage API applications (Bearer auth).
  - name: Merchant Payments
    description: Create checkouts, issue widget sessions, and verify payments.
  - name: Wallet & Platform
    description: Deposits, transfers, withdrawals, and transaction history.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Merchant API key. Server-side only; never expose in the browser.
    BearerAuth:
      type: http
      scheme: bearer
      description: Access token from POST /api/v1/auth/login. Used for dashboard routes.
    WidgetSession:
      type: apiKey
      in: header
      name: X-RushPay-Widget-Session
      description: Short-lived widget session token scoped to one payment_reference.
  schemas:
    SuccessEnvelope:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          additionalProperties: true
    ErrorEnvelope:
      type: object
      required: [success, message]
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Human-readable explanation
        code:
          type: string
          example: validation_error
    PaymentCreateRequest:
      type: object
      required: [amount]
      properties:
        amount:
          type: string
          description: Amount in GHS major units.
          example: "149.99"
        description:
          type: string
          example: Order #1042
        callback_url:
          type: string
          format: uri
          example: https://store.example/webhooks/rushpay
        metadata:
          type: object
          additionalProperties: true
          example:
            order_id: "1042"
            customer_email: ama@example.com
    WidgetSessionRequest:
      type: object
      required: [payment_reference]
      properties:
        payment_reference:
          type: string
          example: API1710000000000000123456
    UpdateMerchantRequest:
      type: object
      required: [payment_reference]
      properties:
        payment_reference:
          type: string
          example: API1710000000000000123456
        description:
          type: string
          example: Order #1042 - paid checkout
        metadata:
          type: object
          additionalProperties: true
          example:
            order_id: "1042"
            platform: woocommerce
    ApplicationCreateRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          example: My Store
        description:
          type: string
          example: Production checkout
        webhook_url:
          type: string
          format: uri
          example: https://store.example/webhooks/rushpay
    ApplicationRevokeRequest:
      type: object
      required: [public_id]
      properties:
        public_id:
          type: string
          example: app_xxxxxxxx
  responses:
    Success:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SuccessEnvelope"
    BadRequest:
      description: Validation error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorEnvelope"
security:
  - ApiKeyAuth: []
paths:
  /api/v1/merchant/applications:
    post:
      tags: [Merchant Applications]
      summary: Create an API application
      description: Create an API application. The response shows api_key, api_secret, and webhook_secret once.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationCreateRequest"
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
    get:
      tags: [Merchant Applications]
      summary: List API applications
      description: List your API applications. Secrets are not returned again.
      security:
        - BearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/applications/revoke:
    post:
      tags: [Merchant Applications]
      summary: Revoke an API application
      description: Deactivate an API application by public_id.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplicationRevokeRequest"
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/create:
    post:
      tags: [Merchant Payments]
      summary: Create a checkout
      description: Create a pending merchant checkout. Amount is in GHS major units as a string or number.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentCreateRequest"
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/widget-session:
    post:
      tags: [Merchant Payments]
      summary: Create a widget session
      description: Issue a short-lived widget_session_token for embedded checkout. Send only this token to the browser.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WidgetSessionRequest"
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/update-merchant:
    post:
      tags: [Merchant Payments]
      summary: Update merchant metadata
      description: Merge merchant metadata and/or update description after payment creation. Useful for legacy checkout flows.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMerchantRequest"
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/status:
    get:
      tags: [Merchant Payments]
      summary: Get payment status
      description: Poll payment status. Server checks use X-API-Key; widget checks can use X-RushPay-Widget-Session.
      security:
        - ApiKeyAuth: []
        - WidgetSession: []
      parameters:
        - name: payment_reference
          in: query
          required: true
          schema:
            type: string
          example: API1710000000000000123456
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/widget-context:
    get:
      tags: [Merchant Payments]
      summary: Get widget context
      description: Return checkout amount, description, status, and funding fee data for the widget.
      security:
        - WidgetSession: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/pay:
    post:
      tags: [Merchant Payments]
      summary: Complete a wallet payment
      description: Complete a wallet payment with email/account password or Bearer auth plus PIN. Optional giftcard_code can cover part of the amount.
      security:
        - WidgetSession: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/initiate-mobile-money:
    post:
      tags: [Merchant Payments]
      summary: Initiate mobile money funding
      description: Start guest mobile money funding for the checkout.
      security:
        - WidgetSession: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/initiate-card:
    post:
      tags: [Merchant Payments]
      summary: Initiate card funding
      description: Start guest card funding through Paystack inline.
      security:
        - WidgetSession: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/submit-momo-otp:
    post:
      tags: [Merchant Payments]
      summary: Submit mobile money OTP
      description: Submit provider OTP when mobile money requires it.
      security:
        - WidgetSession: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/validate-giftcard:
    post:
      tags: [Merchant Payments]
      summary: Validate a gift card
      description: Check whether an RRC gift card can cover a merchant checkout.
      security:
        - WidgetSession: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/payments/process-giftcard:
    post:
      tags: [Merchant Payments]
      summary: Process a gift card payment
      description: Complete checkout fully with a gift card when the card balance covers the order.
      security:
        - WidgetSession: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/balance:
    get:
      tags: [Wallet & Platform]
      summary: Get merchant balance
      description: Return merchant wallet balance for the API application owner.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/merchant/transactions:
    get:
      tags: [Wallet & Platform]
      summary: List merchant transactions
      description: Return merchant-scoped transaction history.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/deposits/initiate:
    post:
      tags: [Wallet & Platform]
      summary: Initiate a deposit
      description: Start a Paystack deposit by mobile money or card.
      security:
        - BearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/transfers:
    post:
      tags: [Wallet & Platform]
      summary: Create a wallet transfer
      description: Send a wallet transfer to another RushPay user. Requires Bearer auth plus PIN.
      security:
        - BearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/withdrawals/initiate:
    post:
      tags: [Wallet & Platform]
      summary: Initiate a withdrawal
      description: Withdraw to bank or mobile money. Requires Bearer auth plus PIN.
      security:
        - BearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /api/v1/transactions:
    get:
      tags: [Wallet & Platform]
      summary: List user transactions
      description: List authenticated user transaction history.
      security:
        - BearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/Success"
        "401":
          $ref: "#/components/responses/Unauthorized"
