{"openapi":"3.0.4","info":{"title":"Payra Onboarding API","version":"1.0.0","description":"**Authentication:** `Authorization: Basic` — username = API **key id**, password = **secret**.\n\n**Scope of this document:** only **`POST /api/v1/applicants`** (and **`GET /health`**) are exposed for **tenant integration (ISV) keys**. Submit a **full** application in **one JSON request** (`payload`: company, address, contact, `individuals`, `documents` with base64 files).\n\n**Not listed here:** directory, listing applicants/merchants, and GET-by-id routes still exist on the bridge for **Payra admin / portal server** auth and **merchant-scoped** keys; they return **403** for a plain ISV integration key.\n\n**Portal server:** the hosted portal uses `X-Admin-Secret` + `X-Tenant-Id` (not Basic) for those operations."},"servers":[{"url":"https://demopaymentsapi.payra.com","description":"Payra onboarding API (hosted by Payra). Shows only `/api/v1/...` onboarding/application endpoints."}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Liveness","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"}}}}}}},"servers":[{"url":"https://demopaymentsapi.payra.com","description":"Payra onboarding API (hosted by Payra). Shows only `/api/v1/...` onboarding/application endpoints."}]},"servers":[{"url":"https://demopaymentsapi.payra.com","description":"Payra onboarding API (hosted by Payra). Shows only `/api/v1/...` onboarding/application endpoints."}]},"/api/v1/applicants":{"post":{"tags":["Bridge — Applications & accounts"],"summary":"Submit application (primary ISV onboarding operation)","description":"**Primary operation for ISV integrations:** create an applicant in one `application/json` request.\n\n**Authentication:** `Authorization: Basic` with your **tenant integration** API key id and secret (the key without a merchant scope).\n\n**Body:** `status` (`draft` or `submitted`) and `payload` containing business data, primary contact, `individuals` (controllers/officers), and `documents`.\n\n**Documents:** each item in `payload.documents` includes metadata plus `dataBase64` (standard base64 file bytes). Tag each file with `scope`: `organization` (business), `individual` (identity docs; set `individualIndex` to match `payload.individuals[i]`), or `other`. You can send the complete application—including every controller and every file—in a **single POST**.\n\nThe hosted Payra portal form is a reference implementation of the same `payload` shape; you can build your own UI and POST the equivalent JSON.","security":[{"basic":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApplicantRequest"}}}},"responses":{"201":{"description":"Created. Response includes `id` (applicant id). Listing that id via GET is not available with the tenant integration key.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"applicant":{"type":"object"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}},"servers":[{"url":"https://demopaymentsapi.payra.com","description":"Payra onboarding API (hosted by Payra). Shows only `/api/v1/...` onboarding/application endpoints."}]},"servers":[{"url":"https://demopaymentsapi.payra.com","description":"Payra onboarding API (hosted by Payra). Shows only `/api/v1/...` onboarding/application endpoints."}]}},"components":{"schemas":{"ApplicantDocument":{"type":"object","description":"One uploaded file embedded in the application. Prefer a **single** `POST` with all documents in `payload.documents` (base64). Set `scope` and `individualIndex` so reviewers can group files by organization vs each controller.","required":["label","fileName","contentType","sizeBytes","dataBase64"],"properties":{"label":{"type":"string","description":"Display name (e.g. \"Bank statement\", \"Passport\").","example":"Bank statement"},"fileName":{"type":"string","example":"statement.pdf"},"contentType":{"type":"string","example":"application/pdf"},"sizeBytes":{"type":"integer","example":240000},"dataBase64":{"type":"string","description":"Raw file bytes encoded as standard base64 (no data: URL prefix)."},"scope":{"type":"string","enum":["organization","individual","other"],"description":"`organization` — business docs; `individual` — identity docs for a person; `other` — voided check, etc."},"individualIndex":{"type":"integer","minimum":0,"description":"When `scope` is `individual`, index into `payload.individuals` (0 = first person)."}}},"ApplicantPayload":{"type":"object","description":"Full merchant onboarding snapshot. Send in one request with `status: submitted` (or `draft` while iterating). Matches the Payra portal demo form: business, address, contact, controllers/officers, embedded files.","properties":{"schemaVersion":{"type":"integer","example":1},"submittedAt":{"type":"string","format":"date-time"},"company":{"type":"object","properties":{"legalName":{"type":"string"},"dba":{"type":"string"},"ein":{"type":"string"},"entityType":{"type":"string"},"industry":{"type":"string"},"website":{"type":"string","format":"uri"}}},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string","example":"US"}}},"contact":{"type":"object","description":"Primary onboarding contact (may overlap with a controller).","properties":{"name":{"type":"string"},"title":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"individuals":{"type":"array","description":"Controllers, officers, beneficial owners (e.g. up to 3 in the hosted form). Each may have multiple `roles` and optional `ownershipPercent` when Owner.","items":{"$ref":"#/components/schemas/ApplicantIndividual"}},"notes":{"type":"string"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/ApplicantDocument"}}}},"ApplicantIndividual":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"jobTitle":{"type":"string"},"phone":{"type":"string"},"homeAddress":{"type":"object","properties":{"line1":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string"}}},"taxId":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"roles":{"type":"array","items":{"type":"string","enum":["director","signatory","owner"]},"description":"Person may have several roles."},"ownershipPercent":{"type":"number","description":"Relevant when `owner` is in `roles`."}}},"CreateApplicantRequest":{"type":"object","properties":{"status":{"type":"string","enum":["draft","submitted"],"description":"Use `submitted` when the payload is complete."},"payload":{"$ref":"#/components/schemas/ApplicantPayload"},"processorApplicationId":{"type":"string","nullable":true}}}},"securitySchemes":{"basic":{"type":"http","scheme":"basic"}}}}