Create Onboarding

Start the onboarding process for a recipient with a payment provider.

POST /v1/recipients/{recipient_id}/onboardings

Request

{
  "type": "ONBOARD_ONTO_THE_PROVIDER",
  "workflow": "DIRECT",
  "provider": {
    "id": "PAGARME",
    "connection_id": "322d48b6-f423-4438-8ffb-0b9b5059a2e9"
  },
  "withdrawal_methods": [
    {
      "bank": {
        "code": "246",
        "branch": "123",
        "account": "1093333333",
        "account_type": "CHECKINGS",
        "country": "US",
        "currency": "USD"
      }
    }
  ]
}

Creates a new onboarding process for a recipient, registering them with a payment provider for marketplace split payments. The recipient must exist before starting onboarding.

A recipient can have multiple onboardings. One per provider connection. Each onboarding tracks the registration lifecycle independently.

Path Parameters

recipient_id · string · required

The unique identifier of the recipient.

Request Body

type · string · required

Type of onboarding.

Values: PREVIOUSLY_ONBOARDED, ONBOARD_ONTO_THE_PROVIDER

• PREVIOUSLY_ONBOARDED. Recipient already exists at the provider; link them in Yuno.
• ONBOARD_ONTO_THE_PROVIDER. Register the recipient with the provider through Yuno.

workflow · string · required

Workflow type for the onboarding process.

Values: HOSTED_BY_PROVIDER, DIRECT

• HOSTED_BY_PROVIDER. Provider handles the onboarding UI (redirect flow).
• DIRECT. Yuno sends the data directly to the provider API.

callback_url · string

URL to redirect the recipient after completing a provider-hosted onboarding flow.

Example: https://www.your-site.com/onboarding-complete

provider · object · required

Payment provider details.

Show provider

id · string · required

Provider identifier.

Values: PAGARME, STRIPE, ADYEN, ALELO, EDENRED, PLUXEE, VR

connection_id · string · required

Yuno connection identifier for this provider.

recipient_id · string

Provider’s own recipient identifier. Required for PREVIOUSLY_ONBOARDED type.

recipient_type · string

Recipient classification at the provider level.

Values: MEAL, FOOD, MULTI_BENEFITS, FLEET

documentation · array

Supporting documents for the onboarding (identity, business registration, etc.).

Show documentation item

file_name · string

Document filename.

content_type · string

Document classification (e.g., RECEIPT).

content_category · string

Category (e.g., INVOICE, ID_PROOF).

content · string

Base64-encoded file content. Max 1 MB.

withdrawal_methods · array

Bank account details for receiving payouts.

Show withdrawal method

bank.code · string

Bank identifier code.

bank.branch · string

Branch code.

bank.account · string

Account number.

bank.account_type · string

Account type: CHECKINGS or SAVINGS.

bank.country · string

ISO 3166-1 alpha-2 country code.

bank.currency · string

ISO 4217 currency code.

Request

{
  "type": "ONBOARD_ONTO_THE_PROVIDER",
  "workflow": "DIRECT",
  "provider": {
    "id": "PAGARME",
    "connection_id": "322d48b6-f423-4438-8ffb-0b9b5059a2e9"
  },
  "withdrawal_methods": [
    {
      "bank": {
        "code": "246",
        "branch": "123",
        "account": "1093333333",
        "account_type": "CHECKINGS",
        "country": "US",
        "currency": "USD"
      }
    }
  ]
}

Related Pages

• Onboarding Statuses. Status lifecycle reference
• Get Onboarding. Retrieve onboarding details
• Update Onboarding. Modify an existing onboarding
• Continue Onboarding. Resume a paused onboarding
• Cancel Onboarding. Cancel an in-progress onboarding