Split Payments - Onboarding

Introduction

Split Payments provides an API to manage Subordinates on the platform. The Master must provide Subordinate information in order to use it during the Onboarding process.

Just like the Master, Subordinates also need to go through the KYC (Know Your Customer) process. It is necessary to validate the Subordinate and some documentation is required.

This KYC process is a required action by financial regulatory agencies.

The Subordinate’s onboarding process has the following steps:

Master requests Subordinate’s enrollment.
The Subordinate will be created in our system with status “Under Analysis”. That means the Subordinate cannot participate in the transaction until the KYC process is finished.
After the analysis, Master will be notified about the result of the KYC process and the Subordinate ID.

Environments

Sandbox

Onboarding API: https://splitonboardingsandbox.cieloecommerce.cielo.com.br

Production

Onboarding API: https://splitonboarding.cieloecommerce.cielo.com.br

Subordinate’s Enrollment

To enroll a Subordinate, Master should make a request with the Subordinate’s information.

There are two ways to establish agreements between Master and its Subordinates with Split Payments:

Setting the MDR (Merchant Discount Rate) to be charged for each transaction by Payment Arrangements and installments range.
If Master do not set the MDR for each Payment Arrangement and installments range, Split Payments will get the same agreements between Master and Acquirer and copy the values to the agreements between Master and Subordinate.

**Example: **

MDR from Master to Subordinate: 4%

Agreement Acquirer vs. Master	Visa	Master	Elo	Diners	Amex	Hiper
Debit	2.00%	2.00%	2.00%
Credit 1x	2.50%	2.50%	2.50%	2.50%	2.50%	2.50%
Credit 2x to 6x	3.00%	3.00%	3.00%	3.00%	3.00%	3.00%
Credit 7x to 12x	3.50%	3.50%	3.50%	3.50%	3.50%	3.50%

Agreement Master vs. Subordinate	Visa	Master	Elo	Diners	Amex	Hiper
Debit	4.00%	4.00%	4.00%
Credit 1x	4.00%	4.00%	4.00%	4.00%	4.00%	4.00%
Credit 2x to 6x	4.00%	4.00%	4.00%	4.00%	4.00%	4.00%
Credit 7x to 12x	4.00%	4.00%	4.00%	4.00%	4.00%	4.00%

Request

Setting the MDR by Payment Arrangements and installments range

--header "Authorization: Bearer {access_token}"
{
    "CorporateName":"Subordinate Corp.",
    "FancyName":"Subordinate Fancy Name",
    "DocumentNumber":"96462142000140",
    "DocumentType":"CNPJ",
    "MerchantCategoryCode":"5719",
    "ContactName":"George Silva",
    "ContactPhone":"11987654321",
    "MailAddress":"address@email.com",
    "Website":"https://www.website.com.br",
    "BankAccount": {
        "Bank":"001",
        "BankAccountType":"CheckingAccount",
        "Number":"0002",
        "Operation":"2",
        "VerifierDigit":"2",
        "AgencyNumber":"0002",
        "AgencyDigit":"2",
        "DocumentNumber":"96462142000140",
        "DocumentType":"CNPJ"
    },
    "Address":{  
        "Street":"Jhon st",
        "Number":"55",
        "Complement":"Rm 701",
        "Neighborhood":"Manhattan",
        "City":"New York",
        "State" : "NY",
        "ZipCode": "10038"
    },
    "Agreement":{
        "Fee" : 10,
        "MerchantDiscountRates": [{
            "PaymentArrangement": {
                "Product": "DebitCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 1,
            "FinalInstallmentNumber" : 1,
            "Percent" : 1.5
        },
        {
            "PaymentArrangement": {
                "Product": "CreditCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 1,
            "FinalInstallmentNumber" : 1,
            "Percent" : 2.0
        },
        {
            "PaymentArrangement": {
                "Product": "CreditCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 2,
            "FinalInstallmentNumber" : 6,
            "Percent" : 3.0
        },
        {
            "PaymentArrangement": {
                "Product": "CreditCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 7,
            "FinalInstallmentNumber" : 12,
            "Percent" : 4.0
        }]
    },
    "Notification": {
        "Url": "https://endpoint.com.br/api/subordinates",
        "Headers": [{
            "Key": "key1",
            "Value": "value1"
        },
        {
            "Key": "key2",
            "Value": "value2"
        }]
    },
    "Attachments": [{
        "AttachmentType": "ProofOfBankDomicile",
        "File": {
            "Name": "evidence",
            "FileType": "png",
            "Data": "iVBORw0KGgoAAAANSUhEUgAAAH4AAAAsCAMAAACUu/xGAAAAq1BMVEUAAABlZVJlZVKsrJthYU+zs6Grq5ylpZazs6FlZVJfX01lZVJlZVKsrJurq5urq5xlZVKtrZ1lZVJlZVKvr52zs6GysqCoqJeqqpmzs6Grq5xlZVJgYE6zs6Gnp5mrq5yiopRjY1CRkX2rq5yzs6FlZVKRkX2goJKKineRkX2Pj3yrq5yIiHWRkX2RkX2RkX1lZVKRkX2rq5yzs6GoqJdfX02goJKHh3SHh3VrpzVsAAAAMHRSTlMAQIDHx3+Ax0Ag7qBgIA9AEFCPMLOgMO7bYKBQ24+zYNuzkY9wcAXu0oiocPFBMHYlVbK0AAAD3UlEQVRYw6SW7Y6qMBCGB0IkLfKdnB9ocFmjru7HERL03P+VnXY6bdmWjcF9f2inxjydvjMDcHy99zP693oEpTpQYjBR7W4VmzA81GoZCDn/ycrValVmYOJcKBWL1/4HnUEpupLGxOI47iQmDkfc4GEBEFyNQkClzYDKQQs3VmJBufu6G7zRWNMeUzEHUnLVWs/gy9vg4NNB4wUIPOG2h7e8NcV0HRt7QPDxfzTd4ptleB5F6ro3NtsIc7UnjMKKXyuN30ZS+PuLRMW7PN+l2vlhAZ6yqCZmcrm05stfOrwVpvEBaJWStIOpVk/gC8Rb62tjRj25Fx/fEsgqE27cluKB8GR9hDFzeX44CFbmJb9/Cn8w1ldA5tO9VD/gc8FpveTbxfi1LXWOl10Z80c0Yx7/jpyyjRtd9zuxU8ZL8FEYJjZFpg6yIfOpKsf1FJ+EUkzddKkabQ+o0zCcwMN/vZm+uLh4UmW7nptTCBVq5nUF4Y0CgBaNVip18jsPn370909cfX708/gusF3fkQfrKZHXHh45Wi8meRefvfVCfwGOZ9zx8TZ9TjWY2M6vVf4jm8e3WYrDJ1Vj4N3FHwVd6vKFCxefBMFmq7ub6UI7TMZw0SEv8ryPDVaoxPiWufhL/02zY0cm3ZH1VgxIIYa1U/nIibH/EZjjp4M/9w/x9FijbyuqdzOVH+BbWQJxHMupd4pjINhDPKVH1lslBl9g6OKb73j0wmoBHrMj691nsJ0QLn4l0/09nrIm6wv7nGdQqwjGucvPJSWjN4z8aXyBlkfK+i2gmDI/HENGjXA9uPhsUJ22p2OQFg3daaFx0/9qnWBRbOl9hHlvOw3OW/xs4Hf4rcnYzj+OeFOIHj4dtG7/2y+b3IhBGAqjUiQWQ9JI/ErDpop6gcei9z9ZIXHIhLaLSGRW8zYxIuaTZccxqsGfHDXvH4cf37Z4e3ihxVOTp5bf4E8N2u+3PWB2SP7tXsfsFl80rtOeZX/gvz6//7tmnFFzD2mkxnFgL710ToHH1eCcm/LU2aA9m027v+kBH8ipyHbACxAMWaV5I4v2ZgAzIxkUGXIqkn3xrhw4wVe8hoMmOwBmYJMiJy+lHPriNcSyrvgEgUS2h/vl1BcvSqgcZsPbbABrhgdgvhgvS6hIYsPP8MwTVR5SLZA4573xHMpCV7xGZBFmxyProfR64yNCgKh4hygjXIuvpdcbPyEayA2vsEpRHcgl6gtzr8A9ho0RlgQnBPoK4tV45gBfGQZ6KQBDqzRcjdeAqQwHUfYp+SohcQdc1/Ukm4Gw4dV6vqTkM+uQpRv8E2VPF/sPp9xSb2qlGH4AAAAASUVORK5CYII="
        }
    }]
}

Property	Type	Size	Required	Description
`CorporateName`	Guid	36	Yes	Corporate Name
`FancyName`	String	50	Yes	Fancy Name
`DocumentNumber`	String	14	Yes	Document number (digits only)
`DocumentType`	String	-	Yes	Document Type. Valid values: `Cpf`, `Cnpj`
`MerchantCategoryCode`	String	4	Yes	A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides. List of MCC codes
`ContactName`	String	100	Yes	Name of the Merchant representative
`ContactPhone`	String	11	Yes	Merchant Representative’s phone number (digits only)
`MailAddress`	String	50	Yes	e-mail address
`Website`	String	200	No	Website address
`BankAccount.Bank`	String	3	Yes	Bank code. Bank codes in Brazil
`BankAccount.BankAccountType`	String	-	Yes	Account type. Accepted values: `CheckingAccount`, `SavingsAccount`
`BankAccount.Number`	String	20	Yes	Account Number
`BankAccount.Operation`	String	10	No	Operation code. Some bank institutions have a special code to identify the profile of its client
`BankAccount.VerifierDigit`	Char	1	Yes	Check digit of the account number
`BankAccount.AgencyNumber`	String	15	Yes	Agency number
`BankAccount.AgencyDigit`	Char	1	Yes	Check digit of agency number. Set `0` when n/a
`BankAccount.DocumentNumber`	String	14	Yes	Account holder document number (digits only)
`BankAccount.DocumentType`	String	-	Yes	Account holder document type. Valid values: `Cpf`, `Cnpj`
`Address.Street`	String	100	Yes	Street name
`Address.Number`	String	15	Yes	The number from street address
`Address.Complement`	String	80	No	Additional information of the address
`Address.Neighborhood`	String	50	Yes	Neighborhood
`Address.City`	String	50	Yes	City
`Address.State`	String	2	Yes	State postal abbreviation
`Address.ZipCode`	String	9	Yes	Zip code (digits only)
`Agreement.Fee`	Int	-	Yes	Fixed fee for each transaction. Value in cents. Ex: BRL 1.00 = `"Fee" : 100`
`Agreement.MerchantDiscountRates[].PaymentArrangement.Product`	String	-	Yes	Payment arrangement product of subordinate MDR. Accepted values: `CreditCard`, `DebitCard`
`Agreement.MerchantDiscountRates[].PaymentArrangement.Brand`	String	-	Yes	Payment arrangement brand of subordinate MDR. Accepted values: `Visa`, `Master`, `Amex`, `Elo`, `Diners`, `Discover`, `Hipercard`
`Agreement.MerchantDiscountRates[].InitialInstallmentNumber`	Int	-	Yes	The start number of the installments range of subordinate MDR. This number must be **between 1 and 12 (>0 and 0 and 0 and 0 and 0 and 0 and GET {split-onboarding-api}/api/subordinates/{subordinate-merchant-id}</aside>

Response

--header "Authorization: Bearer {access_token}"
{
    "MasterMerchantId": "665a33c5-0022-4a40-a0bd-daad04eb3236",
    "MerchantId": "b8ccc729-a874-4b51-a5a9-ffeb5bd98878",
    "CorporateName":"Subordinate Corp.",
    "FancyName":"Subordinate Fancy Name",
    "DocumentNumber":"96462142000140",
    "DocumentType":"CNPJ",
    "MerchantCategoryCode":"5719",
    "ContactName":"George Silva",
    "ContactPhone":"11987654321",
    "MailAddress":"address@email.mail.com",
    "Website":"https://www.website.com.br",
    "Blocked": false,
    "Analysis": {
        "Status": "Approved",
        "Score": 89,
        "DenialReason": null
    },
    "BankAccount": {
        "Bank":"001",
        "BankAccountType":"CheckingAccount",
        "Number":"0002",
        "Operation":"2",
        "VerifierDigit":"2",
        "AgencyNumber":"0002",
        "AgencyDigit":"2",
        "DocumentNumber":"96462142000140",
        "DocumentType":"CNPJ"
    },
    "Address":{  
        "Street":"Jhon st",
        "Number":"55",
        "Complement":"Rm 701",
        "Neighborhood":"Manhattan",
        "City":"New York",
        "State" : "NY",
        "ZipCode": "10038"
    },
    "Agreement":{
        "Fee" : 10,
        "MerchantDiscountRates": [{
            "MerchantDiscountRateId": "662e340f-07f2-4827-816d-b1878eb03eae",
            "PaymentArrangement": {
                "Product": "DebitCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 1,
            "FinalInstallmentNumber" : 1,
            "Percent" : 1.5
        },
        {
            "MerchantDiscountRateId": "eb9d6357-7ad1-4fe0-90fe-364cff7ff0fd",
            "PaymentArrangement": {
                "Product": "CreditCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 1,
            "FinalInstallmentNumber" : 1,
            "Percent" : 2.0
        },
        {
            "MerchantDiscountRateId": "d09fe9d3-98c7-4c37-9bd3-7c1c91ee15de",
            "PaymentArrangement": {
                "Product": "CreditCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 2,
            "FinalInstallmentNumber" : 6,
            "Percent" : 3.0
        },
        {
            "MerchantDiscountRateId": "e2515c24-fd73-4b8e-92ad-cfe2b95239de",
            "PaymentArrangement": {
                "Product": "CreditCard",
                "Brand": "Master"
            },
            "InitialInstallmentNumber" : 7,
            "FinalInstallmentNumber" : 12,
            "Percent" : 4.0
        }]
    },
    "Notification": {
        "Url": "https://endpoint.com.br/api/subordinates",
        "Headers": [{
            "Key": "key1",
            "Value": "value1"
        },
        {
            "Key": "key2",
            "Value": "value2"
        }]
    },
    "Attachments": [{
        "AttachmentType": "ProofOfBankDomicile",
        "File": {
            "Name": "evidence",
            "FileType": "png"
        }
    }]
}

Property	Type	Size	Required	Description
`MasterMerchantId`	Guid	36	Yes	ID of Subordinate’s master
`MerchantId`	Guid	36	Yes	Subordinate ID
`CorporateName`	Guid	36	Yes	Corporate Name
`FancyName`	String	50	Yes	Fancy Name
`DocumentNumber`	String	14	Yes	Document number
`DocumentType`	String	-	Yes	Document Type. Valid values: `Cpf`, `Cnpj`
`MerchantCategoryCode`	String	4	Yes	A Merchant Category Code (MCC) is a four-digit number listed in ISO 18245 for retail financial services. MCC is used to classify the business by the type of goods or services it provides. List of MCC codes
`ContactName`	String	100	Yes	Name of the Merchant representative
`ContactPhone`	String	11	Yes	Merchant Representative’s phone number (digits only)
`MailAddress`	String	50	Yes	e-mail address
`Website`	String	200	No	Website address
`Blocked`	Boolean	-	Yes	A flag to indicate if the Subordinate is blocked to participate in the transaction
`Analysis.Status`	String	-	Yes	KYC process status. Values may be: `Approved`, `ApprovedWithRestriction`, `Rejected`
`Analysis.Score`	Int	-	No	KYC process analysis score. Range from 1 to 100
`Analysis.DenialReason`	String	-	No	Reason why Subordinate has failed in the KYC process, when applicable
`BankAccount.Bank`	String	3	Yes	Bank code. Bank codes in Brazil
`BankAccount.BankAccountType`	String	-	Yes	Account type. Accepted values: `CheckingAccount`, `SavingsAccount`
`BankAccount.Number`	String	20	Yes	Account Number
`BankAccount.Operation`	String	10	No	Operation code. Some bank institutions have a special code to identify the profile of its client
`BankAccount.VerifierDigit`	Char	1	Yes	Check digit of the account number
`BankAccount.AgencyNumber`	String	15	Yes	Agency number
`BankAccount.AgencyDigit`	Char	1	Yes	Check digit of agency number. Set `0` when n/a
`BankAccount.DocumentNumber`	String	14	Yes	Account holder document number (digits only)
`BankAccount.DocumentType`	String	-	Yes	Account holder document type. Valid values: `Cpf`, `Cnpj`
`Address.Street`	String	100	Yes	Street name
`Address.Number`	String	15	Yes	The number from street address
`Address.Complement`	String	80	No	Additional information of the address
`Address.Neighborhood`	String	50	Yes	Neighborhood
`Address.City`	String	50	Yes	City
`Address.State`	String	2	Yes	State postal abbreviation
`Address.ZipCode`	String	9	Yes	Zip code
`Agreement.Fee`	Int	-	Yes	Fixed fee for each transaction. Value in cents. Ex: BRL 1.00 = `"Fee" : 100`
`Agreement.MerchantDiscountRates[].MerchantDiscountRateId`	Guid	36	Yes	MDR ID
`Agreement.MerchantDiscountRates[].PaymentArrangement.Product`	String	-	Yes	Payment arrangement product of subordinate MDR. Accepted values: `CreditCard`, `DebitCard`
`Agreement.MerchantDiscountRates[].PaymentArrangement.Brand`	String	-	Yes	Payment arrangement brand of subordinate MDR. Accepted values: `Visa`, `Master`, `Amex`, `Elo`, `Diners`, `Discover`, `Hipercard`
`Agreement.MerchantDiscountRates[].InitialInstallmentNumber`	Int	-	Yes	The start number of the installments range of subordinate MDR. This number must be **between 1 and 12 (>0 and 0 and POST {notification-url}</aside>

{
    "MerchantId": "b8ccc729-a874-4b51-a5a9-ffeb5bd98878",
    "Status": "Approved",
    "Score": 89,
    "DenialReason": null
}

Property	Type	Size	Required	Description
`MerchantId`	Guid	36	Yes	Subordinate ID
`Analysis.Status`	String	-	Yes	KYC process status. Values may be: `Approved`, `ApprovedWithRestriction`, `Rejected`
`Analysis.Score`	Int	-	No	KYC process analysis score. Range from 1 to 100
`Analysis.DenialReason`	String	-	No	Reason why Subordinate has failed in the KYC process, when applicable