openapi: 3.1.0
info:
  title: PayKore Partner API
  version: 1.0.0
  description: >
    The PayKore Partner API enables fintech companies to embed wallets,
    payments,

    transfers, and KYC into their products.


    All requests require a Bearer JWT in the `Authorization` header.

    Amounts are always in **kobo** (1 NGN = 100 kobo).
servers:
  - url: https://api.paykore.com
    description: Production
  - url: https://sandbox.paykore.com
    description: Sandbox
security:
  - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Partner JWT issued at login. Pass as `Authorization: Bearer <token>`.
  parameters:
    cursor:
      name: cursor
      in: query
      description: Opaque pagination cursor from the previous response.
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Number of records to return (default 20, max 100).
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    partnerId:
      name: id
      in: path
      required: true
      description: Partner UUID.
      schema:
        type: string
        format: uuid
  schemas:
    FeeBreakdown:
      type: object
      description: Fee split for a transaction. All values in kobo.
      properties:
        customerFee:
          type: integer
          description: Fee charged to the end customer.
        merchantFee:
          type: integer
          description: Fee charged to the partner.
        platformFee:
          type: integer
          description: PayKore gross revenue on this transaction.
        mfbCost:
          type: integer
          description: Cost paid to the MFB for this transaction.
        netAmount:
          type: integer
          description: Amount received by the destination after fees.
    SplitEntry:
      type: object
      required:
        - wallet_id
        - amount
      properties:
        wallet_id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in kobo for this split destination.
        percentage:
          type: number
          format: float
    SplitConfig:
      type: object
      properties:
        splits:
          type: array
          items:
            $ref: '#/components/schemas/SplitEntry'
    BankAccount:
      type: object
      required:
        - bank_code
        - account_number
        - account_name
      properties:
        bank_code:
          type: string
          example: '044'
        account_number:
          type: string
          example: '0123456789'
        account_name:
          type: string
          example: Ada Okafor
    Wallet:
      type: object
      properties:
        id:
          type: string
          format: uuid
        partner_id:
          type: string
          format: uuid
        user_ref:
          type: string
          description: Partner-supplied identifier for the wallet owner.
        currency:
          type: string
          example: NGN
        status:
          type: string
          enum:
            - pending
            - active
            - frozen
            - closed
        account_number:
          type: string
          description: MFB-issued NUBAN. Empty until provisioning completes.
          example: '0123456789'
        account_name:
          type: string
          example: Ada Okafor / PayKore
        bank_code:
          type: string
          example: '090270'
        bank_name:
          type: string
          example: Anchor Microfinance Bank
        mfb_reference:
          type: string
          description: Internal MFB reference for this virtual account.
        account_status:
          type: string
          enum:
            - provisioning
            - active
            - suspended
            - closed
          description: Status of the underlying MFB virtual account.
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    LedgerEntry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        wallet_id:
          type: string
          format: uuid
        transaction_id:
          type: string
          format: uuid
        direction:
          type: string
          enum:
            - credit
            - debit
        amount:
          type: integer
          description: Amount in kobo.
        currency:
          type: string
          example: NGN
        balance_after:
          type: integer
          description: Wallet balance after this entry, in kobo.
        status:
          type: string
          enum:
            - pending
            - posted
            - reversed
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    Transaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
        partner_id:
          type: string
          format: uuid
        reference:
          type: string
          description: Partner-supplied idempotency reference.
        type:
          type: string
          enum:
            - wallet_funding
            - wallet_credit
            - wallet_debit
            - p2p_transfer
            - bank_transfer
            - ussd_payment
            - qr_payment
            - split_payment
            - fee_deduction
            - reversal
            - settlement_payout
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - reversed
            - expired
        amount:
          type: integer
          description: Amount in kobo.
        currency:
          type: string
          example: NGN
        source_wallet:
          type: string
          format: uuid
          nullable: true
        dest_wallet:
          type: string
          format: uuid
          nullable: true
        fee_breakdown:
          $ref: '#/components/schemas/FeeBreakdown'
        mfb_reference:
          type: string
          nullable: true
        description:
          type: string
        metadata:
          type: object
          additionalProperties: true
        failed_reason:
          type: string
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    APIKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
        partner_id:
          type: string
          format: uuid
        key_prefix:
          type: string
          description: First 12 chars of the key followed by "...". Never the full key.
          example: sk_live_abcd...
        environment:
          type: string
          enum:
            - live
            - sandbox
        label:
          type: string
        last_used_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
    Partner:
      type: object
      properties:
        id:
          type: string
          format: uuid
        business_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        status:
          type: string
          enum:
            - registered
            - pending_review
            - active
            - suspended
            - closed
        tier:
          type: string
          enum:
            - starter
            - growth
            - scale
        created_at:
          type: string
          format: date-time
    ComplianceStatus:
      type: object
      properties:
        overall_status:
          type: string
          enum:
            - incomplete
            - submitted
            - under_review
            - approved
            - rejected
            - suspended
        cac_number:
          type: string
        business_type:
          type: string
          enum:
            - llc
            - sole_prop
            - ngo
            - partnership
        terms_version:
          type: string
        rejection_reason:
          type: string
          nullable: true
        steps:
          type: object
          properties:
            business_info:
              type: boolean
            directors:
              type: boolean
            agreements:
              type: boolean
            use_case:
              type: boolean
        directors_submitted_at:
          type: string
          format: date-time
          nullable: true
        terms_accepted_at:
          type: string
          format: date-time
          nullable: true
        aml_policy_accepted_at:
          type: string
          format: date-time
          nullable: true
        dpa_accepted_at:
          type: string
          format: date-time
          nullable: true
        use_case_description:
          type: string
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
        partner_id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
          example:
            - transaction.completed
            - wallet.activated
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Machine-readable error code.
          example: NOT_FOUND
        message:
          type: string
          description: Human-readable error description.
  responses:
    Unauthorized:
      description: Missing or invalid authentication token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: INVALID_TOKEN
            message: invalid or expired token
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: NOT_FOUND
            message: resource not found
    UnprocessableEntity:
      description: Request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: VALIDATION_ERROR
            message: user_ref is required
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the rate limit window resets.
        X-RateLimit-Remaining:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: RATE_LIMIT_EXCEEDED
            message: too many requests
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: INTERNAL_ERROR
            message: internal server error
paths:
  /v1/wallets:
    post:
      summary: Create a wallet
      description: |
        Creates a wallet in `pending` state and queues async NUBAN provisioning.
        The wallet transitions to `active` when the MFB provisions the account.
        Listen for the `wallet.activated` webhook event.
      operationId: createWallet
      tags:
        - Wallets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_ref
              properties:
                user_ref:
                  type: string
                  description: Unique identifier for the wallet owner in your system.
                currency:
                  type: string
                  default: NGN
                  description: Only NGN is supported.
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '202':
          description: Wallet created and provisioning queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Wallet'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: A wallet already exists for this user_ref.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/wallets/{id}:
    get:
      summary: Get a wallet
      description: Returns wallet details including current balance and account status.
      operationId: getWallet
      tags:
        - Wallets
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Wallet details with balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      wallet:
                        $ref: '#/components/schemas/Wallet'
                      balance_kobo:
                        type: integer
                        description: Current posted balance in kobo.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/wallets/{id}/transactions:
    get:
      summary: List wallet transactions
      operationId: listWalletTransactions
      tags:
        - Wallets
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Paginated list of transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/transfers/p2p:
    post:
      summary: Wallet-to-wallet transfer
      description: Transfers funds between two PayKore wallets instantly, with no NIP fee.
      operationId: p2pTransfer
      tags:
        - Transfers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source_wallet
                - dest_wallet
                - amount
                - reference
              properties:
                source_wallet:
                  type: string
                  format: uuid
                dest_wallet:
                  type: string
                  format: uuid
                amount:
                  type: integer
                  description: Amount in kobo.
                  minimum: 1
                reference:
                  type: string
                  description: Idempotency key — safe to retry with same value.
                description:
                  type: string
      responses:
        '200':
          description: Transfer completed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/transfers/bank:
    post:
      summary: Outbound bank transfer (NIP)
      description: >
        Initiates an outbound NIP transfer to any Nigerian bank account.

        The transaction starts as `processing` and moves to `completed` or
        `failed`

        via the `transfer_status` MFB webhook. Listen for
        `transaction.completed`

        and `transaction.failed` partner webhook events.
      operationId: bankTransfer
      tags:
        - Transfers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source_wallet
                - dest_account
                - amount
                - reference
              properties:
                source_wallet:
                  type: string
                  format: uuid
                dest_account:
                  $ref: '#/components/schemas/BankAccount'
                amount:
                  type: integer
                  description: Amount in kobo.
                  minimum: 1
                reference:
                  type: string
                  description: Idempotency key.
                description:
                  type: string
      responses:
        '202':
          description: Transfer accepted and processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/payments/qr/create:
    post:
      summary: Create a QR payment request
      operationId: createQRPayment
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - wallet_id
                - amount
                - reference
              properties:
                wallet_id:
                  type: string
                  format: uuid
                amount:
                  type: integer
                  minimum: 1
                reference:
                  type: string
                description:
                  type: string
                expires_in_seconds:
                  type: integer
                  default: 300
      responses:
        '200':
          description: QR payload created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      qr_code:
                        type: string
                        description: Base64-encoded QR image or payload string.
                      reference:
                        type: string
                      expires_at:
                        type: string
                        format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/payments/qr/pay:
    post:
      summary: Pay a QR payment request
      operationId: payQRPayment
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - qr_reference
                - source_wallet
              properties:
                qr_reference:
                  type: string
                source_wallet:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Payment completed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/payments/ussd/initiate:
    post:
      summary: Initiate a USSD payment
      operationId: initiateUSSDPayment
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - wallet_id
                - amount
                - reference
                - phone
              properties:
                wallet_id:
                  type: string
                  format: uuid
                amount:
                  type: integer
                  minimum: 1
                reference:
                  type: string
                phone:
                  type: string
                  description: Customer's phone number in E.164 format.
      responses:
        '200':
          description: USSD session initiated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ussd_code:
                        type: string
                        example: '*123*456#'
                      session_id:
                        type: string
                      expires_at:
                        type: string
                        format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/payments/split:
    post:
      summary: Split payment across multiple wallets
      operationId: splitPayment
      tags:
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - source_wallet
                - reference
                - splits
              properties:
                source_wallet:
                  type: string
                  format: uuid
                reference:
                  type: string
                description:
                  type: string
                splits:
                  type: array
                  minItems: 2
                  items:
                    $ref: '#/components/schemas/SplitEntry'
      responses:
        '200':
          description: Split payment completed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/kyc/bvn:
    post:
      summary: Submit BVN for verification
      operationId: submitBVN
      tags:
        - KYC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_ref
                - bvn
              properties:
                user_ref:
                  type: string
                bvn:
                  type: string
                  description: 11-digit Bank Verification Number.
                  pattern: ^\d{11}$
      responses:
        '202':
          description: BVN verification queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      verification_id:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                          - pending
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/kyc/nin:
    post:
      summary: Submit NIN for verification
      operationId: submitNIN
      tags:
        - KYC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user_ref
                - nin
              properties:
                user_ref:
                  type: string
                nin:
                  type: string
                  description: 11-digit National Identification Number.
                  pattern: ^\d{11}$
      responses:
        '202':
          description: NIN verification queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      verification_id:
                        type: string
                        format: uuid
                      status:
                        type: string
                        enum:
                          - pending
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/kyc/{userRef}/status:
    get:
      summary: Get KYC verification status for a user
      operationId: getKYCStatus
      tags:
        - KYC
      parameters:
        - name: userRef
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: KYC status for the user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      user_ref:
                        type: string
                      verifications:
                        type: array
                        items:
                          type: object
                          properties:
                            verification_id:
                              type: string
                              format: uuid
                            type:
                              type: string
                              enum:
                                - bvn
                                - nin
                            status:
                              type: string
                              enum:
                                - pending
                                - verified
                                - failed
                            created_at:
                              type: string
                              format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/webhooks:
    get:
      summary: List webhook endpoints
      operationId: listWebhooks
      tags:
        - Webhooks
      responses:
        '200':
          description: All registered webhook endpoints for this partner.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      summary: Register a webhook endpoint
      operationId: createWebhook
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - url
                - events
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  minItems: 1
                  items:
                    type: string
                  example:
                    - transaction.completed
                    - transaction.failed
                    - wallet.activated
                    - kyc.verified
                    - kyc.failed
      responses:
        '201':
          description: Webhook endpoint registered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/webhooks/{id}:
    delete:
      summary: Delete a webhook endpoint
      operationId: deleteWebhook
      tags:
        - Webhooks
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Endpoint deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/partner/compliance/status:
    get:
      summary: Get compliance status
      description: Returns the partner's KYB compliance record and step completion status.
      operationId: getComplianceStatus
      tags:
        - Compliance
      responses:
        '200':
          description: Compliance record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ComplianceStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/partner/compliance/business:
    post:
      summary: Submit business information
      description: >-
        Submits CAC number and business type. Can be resubmitted to correct
        mistakes.
      operationId: submitBusinessInfo
      tags:
        - Compliance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cac_number
                - business_type
              properties:
                cac_number:
                  type: string
                  description: CAC registration number (RC/BN/IT followed by 5–8 digits).
                  example: RC123456
                business_type:
                  type: string
                  enum:
                    - llc
                    - sole_prop
                    - ngo
                    - partnership
      responses:
        '200':
          description: Business info saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/partner/compliance/directors:
    post:
      summary: Submit directors / beneficial owners
      description: >
        Submits director information. BVN and NIN are encrypted at rest.

        BVN verification runs asynchronously — listen for the `kyc.verified`
        event.
      operationId: submitDirectors
      tags:
        - Compliance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - directors
              properties:
                directors:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                      - full_name
                      - role
                    properties:
                      full_name:
                        type: string
                      role:
                        type: string
                        example: CEO
                      bvn:
                        type: string
                        pattern: ^\d{11}$
                      nin:
                        type: string
                        pattern: ^\d{11}$
      responses:
        '200':
          description: Directors saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/partner/compliance/agreements:
    post:
      summary: Accept legal agreements
      description: All three agreements must be accepted simultaneously.
      operationId: acceptAgreements
      tags:
        - Compliance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - terms
                - aml_policy
                - dpa
              properties:
                terms:
                  type: boolean
                  enum:
                    - true
                  description: Must be true.
                aml_policy:
                  type: boolean
                  enum:
                    - true
                  description: Must be true.
                dpa:
                  type: boolean
                  enum:
                    - true
                  description: Must be true.
      responses:
        '200':
          description: Agreements accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/partner/compliance/use-case:
    post:
      summary: Submit use case description
      description: >
        Describes the partner's intended use of the PayKore API.

        Submitting this step when all others are complete automatically
        transitions

        the overall status to `submitted` for admin review.
      operationId: submitUseCase
      tags:
        - Compliance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - description
              properties:
                description:
                  type: string
                  minLength: 20
      responses:
        '200':
          description: Use case saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'