openapi: 3.0.3
info:
  title: Mobile Check Cashing SDK — Register PayPal Customer
  version: '1'
  description: |
    PayPal Partner specific. Register a PayPal customer with Ingo
    using the partner-encrypted PayPal `payerId` plus the customer's
    name, email, address, and risk attributes.

    Unlike Card Partners (which key customers by SSN + DOB), PayPal
    Partners key customers by the encrypted PayPal user identifier.
    This endpoint replaces the `/enroll-customer` and
    `/find-customer` flow used by Card Partners.

    On success the response contains both an `ssoToken` (in the body)
    and a `sessiontoken` (in the response headers) — pass these to
    the mobile SDK to initialize in the customer's context.

    PayPal partners use this endpoint plus the shared SDK partner
    endpoints (`/authenticate`, `/add-customer-attributes`,
    `/add-session-attributes`, `/get-transaction-history`). PayPal
    partners do NOT call `/authenticate-obo` (this endpoint already
    binds the session and returns the `ssoToken`), nor any of the
    Card-specific endpoints (`/get-registered-cards`,
    `/add-or-update-card`, `/add-or-update-tokenized-card`,
    `/update-account`, `/delete-card`).

    This endpoint requires an active SDK partner session — call
    `POST /api/v1/partners/authenticate` first to obtain the
    `SessionId` value passed in the request header. This call binds
    the partner session to the PayPal customer and returns the
    `ssoToken` directly, so PayPal partners do NOT call
    `/authenticate-obo`. Pass the returned `ssoToken` / `sessiontoken`
    to the mobile SDK to launch in the customer's context.
servers:
  - url: https://check-cashing-uat.spykemobile.net
    description: UAT (Sandbox)
  - url: https://check-cashing.spykemobile.net
    description: Production
security:
  - OAuth2:
      - sdkapi
tags:
  - name: PayPal Customer
    description: PayPal Partner specific customer registration.
paths:
  /api/v1/paypal/customers/register:
    post:
      tags:
        - PayPal Customer
      operationId: registerPaypalCustomer
      summary: Register a PayPal customer
      description: |
        Registers a PayPal customer with Ingo. The `payerId` is an
        encrypted PayPal user identifier provided by PayPal at
        partner onboarding. Returns `customerId`, `ssoToken`, and a
        `hasCompletedRegistration` flag. A `sessiontoken` is also
        returned in the response headers.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterPaypalCustomerRequest'
            example:
              payerId: encryptedUserId
              firstName: John
              middleInitial: G
              lastName: Smith
              email: john.smith@paypal.com
              address:
                addressLine1: 123 Peach Street
                addressLine2: APT
                city: Hendersonville
                state: TN
                zip: '37075'
              customerRiskAttributes:
                tenureInMonths: 12
                transactionsPerMonth: 5
                accountType: PERSONAL
      responses:
        '200':
          description: |
            PayPal customer registered. The response body contains
            `customerId`, `ssoToken`, and
            `hasCompletedRegistration`. The response headers
            additionally include `sessiontoken`.
          headers:
            sessiontoken:
              schema:
                type: string
              description: Session token to pass to the mobile SDK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterPaypalCustomerResponse'
              example:
                ssoToken: >-
                  OUp5YWtORmJoQlZlaEJsSTZJQ2Q0VkdkdTkyUXlWbWIwSlhZUXRHWlRKQ0xpUW1aamxqWWpsRE5sWldaMjB5TmtkVE90WTJNeFFUTDBVV016MENPMlVUWnhjRFprSmlPaUlYWnBaV2EwNVdaa2xrY2wxMmIwTlhkREpDTGlvMU4yZ1RNeVl6TXVJVE42a1RONkFqTVVSRE10Z0RNdGNUTXdJakk2SXlZMFZWWjBGR1I1Slhhd2hYUml3aUkwMFViT3hHYlVsVmVCcFhUMzFrTU9SWFR0NWtlblJGVHhjbWFOQkRNRDVrTXJSbFcwMTBSYUpUVkg5VWJHcG1UMlVrYVBSVFR0NUVic1JWVzVGa2VOZFhUeTRFZE4xbVQ2ZEdWTUZ6WnExRU13TWtUeXNHVmFSWFRIcGxNVmQwVHRaa2FPSmlPaVFXU3U5V2F6TlhaVEp5ZQ==
                customerId: dd71e568-31e4-413f-97d7-6efe49cb9cfd
                hasCompletedRegistration: false
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.spykemobile.net/connect/token
          scopes:
            sdkapi: Mobile Check Cashing SDK partner methods
  parameters:
    SessionIdHeader:
      name: SessionId
      in: header
      required: true
      schema:
        type: string
      description: Session identifier from `POST /authenticate`.
    DeviceIdHeader:
      name: DeviceId
      in: header
      required: true
      schema:
        type: string
      description: iovation BlackBox device identifier.
  schemas:
    RegisterPaypalCustomerRequest:
      type: object
      required:
        - payerId
        - firstName
        - lastName
        - email
        - address
      properties:
        payerId:
          type: string
          description: |
            Encrypted PayPal user identifier provided by PayPal during
            partner onboarding.
        firstName:
          type: string
          minLength: 1
          maxLength: 50
        middleInitial:
          type: string
          minLength: 0
          maxLength: 1
        lastName:
          type: string
          minLength: 1
          maxLength: 50
        email:
          type: string
          format: email
          minLength: 1
          maxLength: 100
          description: |
            PayPal customer's email address. Used as the primary
            identifier in the SDK's PayPal flow (replacing PAN).
        address:
          $ref: '#/components/schemas/PayPalAddress'
        customerRiskAttributes:
          $ref: '#/components/schemas/PayPalCustomerRiskAttributes'
    PayPalAddress:
      type: object
      required:
        - addressLine1
        - city
        - state
        - zip
      properties:
        addressLine1:
          type: string
          maxLength: 50
        addressLine2:
          type: string
          maxLength: 50
        city:
          type: string
          maxLength: 50
        state:
          type: string
          minLength: 2
          maxLength: 2
          description: Two-character US state code.
        zip:
          type: string
          minLength: 5
          maxLength: 5
          pattern: ^[0-9]{5}$
    PayPalCustomerRiskAttributes:
      type: object
      description: |
        Subset of customer relationship attributes specific to the
        PayPal registration flow. Additional attributes can be added
        post-registration via `POST /add-customer-attributes`.
      properties:
        tenureInMonths:
          type: integer
          minimum: 0
          description: Length of the customer's PayPal relationship in months.
        transactionsPerMonth:
          type: integer
          minimum: 0
        accountType:
          type: string
          enum:
            - PERSONAL
            - BUSINESS
          description: PayPal account type.
    RegisterPaypalCustomerResponse:
      type: object
      required:
        - customerId
        - ssoToken
      properties:
        ssoToken:
          type: string
          description: |
            Single-use SSO token to pass to the mobile SDK at
            initialization. Treat as a credential.
        customerId:
          type: string
          format: uuid
          description: Ingo-assigned customer identifier (GUID).
        hasCompletedRegistration:
          type: boolean
          description: |
            Indicates whether the PayPal customer has completed the
            full registration flow on the Ingo side. `false` is
            returned for new registrations; subsequent `register`
            calls may return `true` once the customer has gone
            through the SDK onboarding.