Create a merchant platform, then optionally remind the merchant to sign.

arazzo: 1.0.0
info:
  title: Create a merchant platform
  summary: Board a business by creating its merchant platform and optionally
    sending a pricing-agreement reminder.
  description: |
    Creates the top-level merchant platform for a business — the root of the Payroc boarding tree. The single create call carries the business's legal details and a nested array of processing accounts; each processing account in turn nests its owners and contacts inline (there are no standalone createOwner/createContact operations — supply them in this payload). The gateway returns a merchantPlatformId and a processingAccountId per nested processing account; keep both for follow-on boarding actions (adding processing accounts, ordering terminals). Agent gotchas: owners carry a relationship with isControlProng (you must nominate one control prong) and equityPercentage; the pricing block references a reusable pricingIntentId rather than inline pricing; and the optional reminder step only works when the processing account requested the merchant's signature by email (signature.type = requestedViaEmail) — it fails for a direct-link signature.
  version: 1.0.0
sourceDescriptions:
  - name: payroc-api
    url: /openapi.yaml
    type: openapi
workflows:
  - workflowId: create-merchant-platform
    summary: Create a merchant platform, then optionally remind the merchant to sign.
    description: |
      Step 1 (createMerchant) boards the business and its nested processing accounts, owners and contacts in one POST. Step 2 (createReminder) is OPTIONAL: only invoke it when the merchant was asked to sign the pricing agreement by email and has not responded — it re-sends the signature email for a single processing account and returns 400 if the signature was requested via direct link or has already been signed.
    x-actors:
      - id: merchant
        name: Merchant / business owner
        type: human
        description: The business being boarded; signs the pricing agreement out of band
          (email or direct link). Not an API caller.
      - id: integrator
        name: Integrator
        type: client
        description: Calls the Payroc API on the merchant's behalf to board the business.
      - id: payroc-gateway
        name: Payroc gateway
        type: api
        description: The Payroc API surface these steps call.
    inputs:
      type: object
      required:
        - idempotencyKey
        - businessName
        - taxId
        - organizationType
        - doingBusinessAs
        - pricingIntentId
      properties:
        idempotencyKey:
          type: string
          description: Unique UUID v4 idempotency key generated per request.
          example: f32c9ad6-c97f-4998-9356-f3b6718b1b68
        businessName:
          type: string
          description: Legal name of the business.
          example: Example Corp
        taxId:
          type: string
          description: Tax ID (EIN) of the business.
          example: 12-3456789
        organizationType:
          type: string
          description: Type of organization.
          example: privateCorporation
        doingBusinessAs:
          type: string
          description: Trading (DBA) name of the processing account.
          example: Pizza Doe
        pricingIntentId:
          type: string
          description: Identifier of a previously created pricing intent applied to the
            processing account.
          example: "6123"
        reminderType:
          type: string
          description: Reminder type for the optional signature reminder step.
          example: pricingAgreement
    steps:
      - stepId: createMerchant
        x-actor: integrator
        x-actor-to: payroc-gateway
        x-label: create merchant platform
        description: |
          Board the business — send the legal business details plus a nested processingAccounts array; each processing account nests its owners (one flagged isControlProng) and contacts inline. Returns the merchantPlatformId and, for each processing account, a processingAccountId.
        operationId: createMerchant
        parameters:
          - name: Idempotency-Key
            in: header
            value: $inputs.idempotencyKey
        requestBody:
          contentType: application/json
          payload:
            business:
              name: $inputs.businessName
              taxId: $inputs.taxId
              organizationType: $inputs.organizationType
              countryOfOperation: US
              addresses:
                - type: legalAddress
                  address1: 1 Example Ave.
                  address2: Example Address Line 2
                  address3: Example Address Line 3
                  city: Chicago
                  state: Illinois
                  country: US
                  postalCode: "60056"
              contactMethods:
                - type: email
                  value: jane.doe@example.com
            processingAccounts:
              - doingBusinessAs: $inputs.doingBusinessAs
                owners:
                  - firstName: Jane
                    middleName: Helen
                    lastName: Doe
                    dateOfBirth: 1964-03-22
                    address:
                      address1: 1 Example Ave.
                      address2: Example Address Line 2
                      address3: Example Address Line 3
                      city: Chicago
                      state: Illinois
                      country: US
                      postalCode: "60056"
                    identifiers:
                      - type: nationalId
                        value: 000-00-4320
                    contactMethods:
                      - type: email
                        value: jane.doe@example.com
                    relationship:
                      equityPercentage: 48.5
                      title: CFO
                      isControlProng: true
                      isAuthorizedSignatory: false
                website: www.example.com
                businessType: restaurant
                categoryCode: 5999
                processor: tsys
                merchandiseOrServiceSold: Pizza
                businessStartDate: 2020-01-01
                timezone: America/Chicago
                address:
                  address1: 1 Example Ave.
                  address2: Example Address Line 2
                  address3: Example Address Line 3
                  city: Chicago
                  state: Illinois
                  country: US
                  postalCode: "60056"
                contactMethods:
                  - type: email
                    value: jane.doe@example.com
                processing:
                  transactionAmounts:
                    average: 5000
                    highest: 10000
                  monthlyAmounts:
                    average: 50000
                    highest: 100000
                  volumeBreakdown:
                    cardPresent: 77
                    mailOrTelephone: 3
                    ecommerce: 20
                funding:
                  fundingSchedule: nextday
                  acceleratedFundingFee: 1999
                  dailyDiscount: false
                  fundingAccounts:
                    - type: checking
                      use: creditAndDebit
                      nameOnAccount: Jane Doe
                      paymentMethods:
                        - type: ach
                          value:
                            routingNumber: "123456789"
                            accountNumber: "1234567890"
                pricing:
                  type: intent
                  pricingIntentId: $inputs.pricingIntentId
                signature:
                  type: requestedViaEmail
                contacts:
                  - type: manager
                    firstName: Jane
                    middleName: Helen
                    lastName: Doe
                    identifiers:
                      - type: nationalId
                        value: 000-00-4320
                    contactMethods:
                      - type: email
                        value: jane.doe@example.com
            metadata:
              customerId: "2345"
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          merchantPlatformId: $response.body#/merchantPlatformId
          processingAccountId: $response.body#/processingAccounts/0/processingAccountId
      - stepId: createReminder
        x-actor: integrator
        x-actor-to: payroc-gateway
        x-label: send signature reminder
        description: |
          OPTIONAL — re-send the pricing-agreement signature email for the processing account created in step 1. Only valid when that account's signature was requested by email (requestedViaEmail); returns 400 if the signature was requested via direct link, if no pricing agreement exists, or if the merchant has already signed.
        operationId: createReminder
        parameters:
          - name: Idempotency-Key
            in: header
            value: $inputs.idempotencyKey
          - name: processingAccountId
            in: path
            value: $steps.createMerchant.outputs.processingAccountId
        requestBody:
          contentType: application/json
          payload:
            type: pricingAgreement
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          reminderId: $response.body#/reminderId
      - stepId: signPricingAgreement
        x-actor: merchant
        x-actor-to: payroc-gateway
        x-label: sign pricing agreement
        description: |
          The merchant signs the pricing agreement out of band via the signature email sent at boarding (each processing account here uses signature.type requestedViaEmail; a direct-link signature is signed via its link instead). Not a Payroc REST operation; the optional reminder step above only re-sends the signature email.
        x-operation:
          method: GET
          url: https://{pricing-agreement-signing-link}
    outputs:
      merchantPlatformId: $steps.createMerchant.outputs.merchantPlatformId
      processingAccountId: $steps.createMerchant.outputs.processingAccountId
      reminderId: $steps.createReminder.outputs.reminderId