Skip to main content
POST
/
recipients
/
{recipient_id}
/
onboardings
Create Onboarding
curl --request POST \
  --url https://api-sandbox.y.uno/v1/recipients/{recipient_id}/onboardings \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "account_id": "{{account-code}}",
  "type": "PREVIOUSLY_ONBOARDED",
  "workflow": "DIRECT",
  "callback_url": "https://merchant.example.com/webhook/onboarding",
  "provider": {
    "id": "VR",
    "connection_id": "d2c1f0e9-8a90-432a-ab7c-fdee4c7d58e4",
    "recipient_id": "test01",
    "recipient_type": "MULTI_BENEFITS"
  },
  "documentation": [
    {
      "file_name": "onboarding.pdf",
      "content_type": "application/pdf",
      "content_category": "IDENTIFICATION_DOCUMENT",
      "content": "VGV4dG8gZGUgZWplbXBsbyBwYXJhIEJhc2U2NA=="
    }
  ],
  "withdrawal_methods": {
    "bank": {
      "code": "002",
      "branch": "002",
      "account": "9876543210",
      "account_type": "CHECKINGS",
      "country": "US",
      "currency": "USD",
      "routing": "021000022"
    }
  },
  "terms_of_service": {
    "acceptance": true,
    "date": "2025-07-21T20:43:54.786342Z",
    "ip": "129.21.111.11"
  }
}
'
{
  "id": "61df26d9-3750-4206-baab-f2e20683f35b",
  "type": "PREVIOUSLY_ONBOARDED",
  "workflow": "DIRECT",
  "status": "SUCCEEDED",
  "callback_url": "https://merchant.example.com/webhook/onboarding",
  "provider": {
    "id": "STRIPE",
    "connection_id": "8fee3cc6-f3cb-455d-b139-973866111a03",
    "recipient_id": "acct_1RvpogA4Jk50vKRE",
    "redirect_url": null,
    "onboarding_url": null,
    "legal_entity": null
  },
  "documentation": [
    {
      "file_name": "recipient.pdf",
      "content_type": "application/pdf",
      "content_category": "IDENTIFICATION_DOCUMENT",
      "content": "recipient.pdf-20ac42c2-ef01-4a0c-80dd-0f9f71c9cde7"
    }
  ],
  "legal_representatives": [
    {
      "merchant_reference": "ONB_001",
      "first_name": "Tatiana",
      "last_name": "González",
      "email": "tatiana.gonzalez@example.com",
      "date_of_birth": "1985-05-20",
      "country": "BR",
      "nationality": "BR",
      "title": "CEO",
      "publicly_exposed_person": false,
      "ultimate_beneficial_owner": true,
      "document": {
        "document_type": "CC",
        "document_number": "0987654321"
      },
      "phone": {
        "number": "3109876543",
        "country_code": "+57"
      },
      "address": {
        "address_line_1": "Calle 26 # 13-19",
        "address_line_2": null,
        "country": "CO",
        "state": "Cundinamarca",
        "city": "Bogotá",
        "zip_code": "110311"
      }
    }
  ],
  "requirements": [],
  "withdrawal_methods": {
    "bank": {
      "code": "003",
      "branch": "003",
      "branch_digit": null,
      "account": "9876543210",
      "account_digit": null,
      "account_type": "CHECKINGS",
      "routing": "021000022",
      "country": "US",
      "currency": "USD"
    }
  },
  "terms_of_service": {
    "acceptance": true,
    "date": "2025-07-21T20:43:54.786342Z",
    "ip": "129.21.111.11"
  },
  "recipient": {
    "id": "5a37f0c0-7689-4065-8348-4b5ff5bf9cc7",
    "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
    "merchant_recipient_id": "MERCHANT_85ac5f5d-a169-46b3-bd87-80c0df2e6591",
    "national_entity": "INDIVIDUAL",
    "entity_type": "PRIVATE",
    "first_name": "Stebann",
    "last_name": "Castro",
    "legal_name": "Steban Castro",
    "email": "juan.perez@example.com",
    "date_of_birth": "1992-01-21",
    "country": "CO",
    "website": "https://juanperez.com",
    "industry": "Technology",
    "merchant_category_code": "5740",
    "document": {
      "document_number": "09082160000100",
      "document_type": "CNPJ"
    },
    "phone": {
      "country_code": "57",
      "number": "3001234567"
    },
    "address": {
      "address_line_1": "Carrera 7 # 32-16",
      "address_line_2": "Oficina 201",
      "city": "Bogotá",
      "country": "CO",
      "state": "Cundinamarca",
      "zip_code": "110311",
      "neighborhood": "Centro"
    },
    "legal_representatives": [
      {
        "merchant_reference": "REP_001",
        "first_name": "María",
        "last_name": "González",
        "email": "maria.gonzalez@example.com",
        "date_of_birth": "1985-05-20",
        "country": "CO",
        "nationality": "CO",
        "title": "CEO",
        "publicly_exposed_person": false,
        "ultimate_beneficial_owner": true,
        "document": {
          "document_type": "CC",
          "document_number": "0987654321"
        },
        "phone": {
          "number": "3109876543",
          "country_code": "+57"
        },
        "address": {
          "address_line_1": "Calle 26 # 13-19",
          "address_line_2": null,
          "country": "CO",
          "state": "Cundinamarca",
          "city": "Bogotá",
          "zip_code": "110311"
        }
      }
    ],
    "withdrawal_methods": {
      "bank": {
        "code": "001",
        "branch": "004",
        "branch_digit": "123",
        "account": "1234567890",
        "account_digit": "123",
        "account_type": "SAVINGS",
        "routing": "021000021",
        "country": "CO",
        "currency": "COP"
      }
    },
    "documentation": [
      {
        "file_name": "recipient.pdf",
        "content_type": "application/pdf",
        "content_category": "IDENTIFICATION_DOCUMENT",
        "content": "recipient.pdf-2bf73b44-33e3-49c7-b777-34a5178cfb45"
      }
    ],
    "created_at": "2025-08-22T17:54:05.711545Z",
    "updated_at": "2025-08-22T17:54:05.711561Z"
  },
  "history": {
    "id": "61df26d9-3750-4206-baab-f2e20683f35b",
    "type": "PREVIOUSLY_ONBOARDED",
    "workflow": "DIRECT",
    "status": "SUCCEEDED",
    "callback_url": "https://merchant.example.com/webhook/onboarding",
    "provider": {
      "id": "STRIPE",
      "connection_id": "8fee3cc6-f3cb-455d-b139-973866111a03",
      "recipient_id": "acct_1RvpogA4Jk50vKRE",
      "redirect_url": null
    },
    "documentation": [
      {
        "file_name": "recipient.pdf",
        "content_type": "application/pdf",
        "content_category": "IDENTIFICATION_DOCUMENT",
        "content": "recipient.pdf-20ac42c2-ef01-4a0c-80dd-0f9f71c9cde7"
      }
    ],
    "legal_representatives": [
      {
        "merchant_reference": "ONB_001",
        "first_name": "Tatiana",
        "last_name": "González",
        "email": "tatiana.gonzalez@example.com",
        "date_of_birth": "1985-05-20",
        "country": "BR",
        "nationality": "BR",
        "title": "CEO",
        "publicly_exposed_person": false,
        "ultimate_beneficial_owner": true,
        "document": {
          "document_type": "CC",
          "document_number": "0987654321"
        },
        "phone": {
          "number": "3109876543",
          "country_code": "+57"
        },
        "address": {
          "address_line_1": "Calle 26 # 13-19",
          "address_line_2": null,
          "country": "CO",
          "state": "Cundinamarca",
          "city": "Bogotá",
          "zip_code": "110311"
        }
      }
    ],
    "requirements": [],
    "withdrawal_methods": {
      "bank": {
        "code": "003",
        "branch": "003",
        "branch_digit": null,
        "account": "9876543210",
        "account_digit": null,
        "account_type": "CHECKINGS",
        "routing": "021000022",
        "country": "US",
        "currency": "USD"
      }
    },
    "terms_of_service": {
      "acceptance": true,
      "date": "2025-07-21T20:43:54.786342Z",
      "ip": "129.21.111.11"
    },
    "recipient": {
      "id": "5a37f0c0-7689-4065-8348-4b5ff5bf9cc7",
      "account_id": "c24d6c92-99a7-40bb-bc7b-efc40337f9f4",
      "merchant_recipient_id": "MERCHANT_85ac5f5d-a169-46b3-bd87-80c0df2e6591",
      "national_entity": "INDIVIDUAL",
      "entity_type": "PRIVATE",
      "first_name": "Stebann",
      "last_name": "Castro",
      "legal_name": "Steban Castro",
      "email": "juan.perez@example.com",
      "date_of_birth": "1992-01-21",
      "country": "CO",
      "website": "https://juanperez.com",
      "industry": "Technology",
      "merchant_category_code": "5740",
      "document": {
        "document_number": "09082160000100",
        "document_type": "CNPJ"
      },
      "phone": {
        "country_code": "57",
        "number": "3001234567"
      },
      "address": {
        "address_line_1": "Carrera 7 # 32-16",
        "address_line_2": "Oficina 201",
        "city": "Bogotá",
        "country": "CO",
        "state": "Cundinamarca",
        "zip_code": "110311",
        "neighborhood": "Centro"
      },
      "legal_representatives": [
        {
          "merchant_reference": "REP_001",
          "first_name": "María",
          "last_name": "González",
          "email": "maria.gonzalez@example.com",
          "date_of_birth": "1985-05-20",
          "country": "CO",
          "nationality": "CO",
          "title": "CEO",
          "publicly_exposed_person": false,
          "ultimate_beneficial_owner": true,
          "document": {
            "document_type": "CC",
            "document_number": "0987654321"
          },
          "phone": {
            "number": "3109876543",
            "country_code": "+57"
          },
          "address": {
            "address_line_1": "Calle 26 # 13-19",
            "address_line_2": null,
            "country": "CO",
            "state": "Cundinamarca",
            "city": "Bogotá",
            "zip_code": "110311"
          }
        }
      ],
      "withdrawal_methods": {
        "bank": {
          "code": "001",
          "branch": "004",
          "branch_digit": "123",
          "account": "1234567890",
          "account_digit": "123",
          "account_type": "SAVINGS",
          "routing": "021000021",
          "country": "CO",
          "currency": "COP"
        }
      },
      "documentation": [
        {
          "file_name": "recipient.pdf",
          "content_type": "application/pdf",
          "content_category": "IDENTIFICATION_DOCUMENT",
          "content": "recipient.pdf-2bf73b44-33e3-49c7-b777-34a5178cfb45"
        }
      ],
      "created_at": "2025-08-22T17:54:05.711545Z",
      "updated_at": "2025-08-22T17:54:05.711561Z"
    },
    "created_at": "2025-08-22T17:57:58.460711Z",
    "updated_at": "2025-08-22T17:57:58.460724Z"
  },
  "created_at": "2025-08-22T17:57:58.460711Z",
  "updated_at": "2025-08-22T17:57:58.460724Z"
}
Creates an onboarding for a recipient. This endpoint creates an onboarding for a recipient, enabling submerchants to be integrated with payment providers for split payment scenarios. Use this to register new submerchants or set up recipients before they can receive split payments.

​
Overview

Onboarding is the first step in the split payments marketplace workflow. Each recipient (submerchant) must be onboarded with payment providers before they can receive split payments. The onboarding process supports two flows:
  • Pre-onboarded accounts: For submerchants already registered with providers. Use type: "PREVIOUSLY_ONBOARDED".
  • Dynamic onboarding: For new submerchant registration including KYC/KYB (Know Your Customer/Know Your Business) validation. Use type: "ONE_STEP_ONBOARDING" or type: "TWO_STEP_ONBOARDING" (previously type: "ONBOARD_ONTO_PROVIDER").
Two-Step OnboardingFor type: "TWO_STEP_ONBOARDING" flows, use the Continue Onboarding endpoint to complete the KYC process after account creation.

Authorizations

​
public-api-key
string
header
default:<Your public-api-key>
required
​
private-secret-key
string
header
default:<Your private-secret-key>
required

Path Parameters

​
recipient_id
string
required

ID of the new recipient to whom the onboarding will be transferred

Body

application/json
​
account_id
string
required

Unique id of the account in Yuno

Example:

"9104911d-5df9-429e-8488-ad41abea1a4b"

​
type
enum<string>
required

Type of onboarding flow. PREVIOUSLY_ONBOARDED for pre-existing accounts, ONE_STEP_ONBOARDING for account creation + KYC in one step, TWO_STEP_ONBOARDING for account creation first then KYC later

Available options:
PREVIOUSLY_ONBOARDED,
ONE_STEP_ONBOARDING,
TWO_STEP_ONBOARDING
Example:

"PREVIOUSLY_ONBOARDED"

​
workflow
enum<string>
required

Workflow of the onboarding

Available options:
HOSTED_BY_PROVIDER,
DIRECT
Example:

"HOSTED_BY_PROVIDER"

​
provider
object
required
​
description
string

Optional description of the onboarding (MAX 255; MIN 3).

Required string length: 3 - 255
​
callback_url
string<uri>

URL in case to redirect your customer after the onboarding process with the provider, if needed.

Example:

"https://www.google.com"

​
documentation
object[]

Specifies the documentation object.

​
withdrawal_methods
object

Specifies the withdrawal methods object.

​
legal_representatives
object[]

Object to indicate the owners of the organization. Adyen, Stripe and dlocal have fields related to that.

​
terms_of_service
object

Object describing terms of service.

Response

Created

​
id
string

The unique identifier of the recipient.

Example:

"3aaa4d82-11e8-48ce-8ef5-04eee3a10802"

​
account_id
string

The account identifier associated with this recipient.

Example:

"fe14c7c6-c75e-43b7-bdbe-4c87ad52c482"

​
merchant_recipient_id
string

Unique identifier of the recipient defined by the merchant.

Example:

"MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6"

​
national_entity
string

Beneficiary's national entity type.

Example:

"INDIVIDUAL"

​
entity_type
string

Beneficiary's type of organization.

Example:

"PRIVATE"

​
first_name
string

Beneficiary's name.

Example:

"Juan"

​
last_name
string

Beneficiary's last name.

Example:

"Perez"

​
legal_name
string | null

Beneficiary's legal name.

Example:

null

​
email
string

The Beneficiary's email.

Example:

"juan.perez@example.com"

​
date_of_birth
string

Beneficiary's date of birth.

Example:

"1990-01-15"

​
country
string

The Beneficiary's country.

Example:

"CO"

​
website
string

The seller's website URL.

Example:

"https://juanperez.com"

​
industry
string

The seller's industry.

Example:

"Technology"

​
merchant_category_code
string

The merchant category code (MCC) (MAX 235; MIN 1).

Example:

"5734"

​
document
object
​
phone
object
​
address
object
​
legal_representatives
object[]
​
withdrawal_methods
object
​
documentation
object[]
​
onboardings
object[]
​
split_configuration
object

Rules for automatic split calculation at the recipient level.

​
created_at
string<date-time>

Recipient creation date (ISO 8601 MAX 27; MIN 27).

Example:

"2025-08-27T15:41:19.497413Z"

​
updated_at
string<date-time>

Last Recipient updated date (ISO 8601 MAX 27; MIN 27).

Example:

"2025-08-27T15:41:19.497425Z"