Request accounts during sender onboarding

1. Select account capabilities

Include the optional capabilities array in POST /v2/senders:

{
  "type": "business",
  "fullName": "Example Trading Ltd",
  "email": "[email protected]",
  "identificationNumber": "12345678",
  "taxIdentificationNumber": "88-2448435",
  "capabilities": ["eur_account", "usd_account"]
}

Supported values are:

Omit capabilities to use the existing sender onboarding flow without requesting an account.

2. Check what Mesta accepted

Sender creation does not fail merely because an account capability is temporarily unavailable. The response reports the result using the requested capability values:

{
  "data": {
    "id": "sender-123",
    "acceptedCapabilities": ["eur_account"],
    "unavailableCapabilities": ["usd_account"]
  }
}

• acceptedCapabilities contains durable account intent registered for the sender.
• unavailableCapabilities contains valid selections that cannot currently be registered.
• Unknown capability values fail request validation instead of appearing as unavailable.

3. Complete the normal onboarding sequence

After sender creation:

1. Add all UBOs.
2. Add required Directors or Authorized Representatives through POST /v1/senders/associates.
3. Upload required sender and identity documents.
4. Obtain a selfie-verification URL for every UBO and every unlinked representative, and have each person complete verification.
5. Call POST /v1/senders/{senderId}/verify.

Requirements are documentation-led. API merchants do not call the portal validation-rules/senders/resolve endpoint.

Before implementing this flow, use the Onboarding requirement matrix for the exact public field, country condition, document type, and write endpoint for every capability requirement.

4. Linked UBO and Director

When a Director or Authorized Representative is the same person as a UBO, set linkedUboId while creating the associate. Mesta reuses the person's stored information and verification state instead of treating the two roles as different people.

5. Verify UBOs and representatives

After creating the people associated with the sender:

• For each UBO, call GET /v1/senders/ubo/{uboId}/verification-url and send the returned URL to that person.
• For each unlinked Director or Authorized Representative, call GET /v1/senders/associates/{associateId}/verification-url and send the returned URL to that person.
• Do not request a separate verification URL for a representative created with linkedUboId. The linked representative is the same natural person as the UBO and reuses that UBO's verification session and status.

The person follows the returned URL to complete selfie/liveness verification. Approval is asynchronous: completing the session does not mean the person is immediately approved.

Every UBO and every unlinked representative persisted for the sender must be approved before the business sender can become active. A linked representative is covered by the linked UBO's approval. Create only the representatives required for the sender because an unlinked representative left unverified can keep sender activation pending.

You may submit the sender once all required data and documents are present; person approvals do not need to finish before the submission request is made. However, sender activation and virtual bank account setup can remain blocked after submission while UBO or representative approval is pending. A virtual bank account setup response identifies this with ubo_verification_pending or associate_verification_pending and includes the affected person ID.

6. Verification and automatic setup

POST /v1/senders/{senderId}/verify runs the authoritative union of base sender requirements, country-specific requirements, requirements for every accepted capability, and country/role requirements for every persisted UBO and associate. Canonical data already stored for the sender is excluded. If no blockers remain, the existing verification process starts.

If data is incomplete, verification does not start. The standard Mesta error envelope uses uppercase CODE, MESSAGE, and DETAILS; each item in DETAILS has the same actionable public blocker semantics as a setup-request blocker. It identifies the affected person or missing role, the public fields required, and the API action to take:

{
  "error": {
    "CODE": "CAPABILITY_REQUIREMENTS_MISSING",
    "MESSAGE": "Sender capability requirements are incomplete",
    "DETAILS": [
      {
        "code": "missing_data",
        "requiredBy": ["usd_account"],
        "subject": {"type": "ubo", "id": "ubo-123"},
        "fields": [{"name": "identificationNumber", "label": "Tax identification number"}],
        "action": {
          "method": "PATCH",
          "path": "/v1/senders/ubo/ubo-123",
          "bodyFields": ["identificationNumber"]
        }
      },
      {
        "code": "missing_associate",
        "requiredBy": ["eur_account"],
        "subject": {"type": "associate", "roles": ["director"], "minimumCount": 1},
        "fields": [],
        "action": {
          "method": "POST",
          "path": "/v1/senders/associates",
          "bodyFields": ["senderId", "roles", "linkedUboId", "firstName", "lastName"]
        }
      }
    ]
  }
}

Follow each returned action; sender updates use the sender action returned by the API, UBO updates use PATCH /v1/senders/ubo/{uboId}, and sender documents use POST /v1/senders/{senderId}/documents. missing_associate is used when the merchant must create a Director or Authorized Representative; it replaces the vague missing_subject wording. requiredBy shows which accepted capabilities need the item. During the transition, a blocker may also include the deprecated legacy key (for example, person.tax_id), but integrations should use code, subject, fields, and action.

After verification, approval, and activation, Mesta automatically starts each accepted account setup when its own readiness gates pass. Do not call a separate provision endpoint.

Multiple capabilities

Shared sender and person data is collected once. Each capability is then evaluated and provisioned independently, so one account can progress while another waits for additional information or verification.