/merchant/psp/sub-merchant/open-partner Create Sub-merchant

Background

/merchant/psp/sub-merchant/open-partner is provided for the primary merchant to create sub-merchants. Through this endpoint, the primary merchant submits the sub-merchant's legal entity information, registration information, business information, applied products, and expected transaction volume to create the sub-merchant.

Merchant Creation Flow Diagram

sequenceDiagram
    autonumber
    participant M as Primary merchant
    participant A as adopay
    participant O as adopay operations staff

    M->>A: Call the create sub-merchant endpoint
    A->>A: Validate and persist, recorded as pending review
    A-->>M: Return the application acceptance result
    A->>O: Submit the sub-merchant application for review
    O->>O: Review the merchant documents

    alt Review approved
        O->>A: Submit the approval result
        A->>A: Create the sub-merchant
        A->>A: Create the login account
        A->>A: Open the settlement account
        A-->>M: Callback with the final merchant creation result (SUCCESS)
        M-->>A: Acknowledge SUCCESS or OK
    else Review rejected
        O->>A: Submit the rejection final result
        A->>A: Terminate the creation flow and record the rejection result
        A-->>M: Callback with the merchant creation result (FAILED)
        M-->>A: Acknowledge SUCCESS or OK
    end

Integration Specifications

• Common integration specifications

Endpoint

Item	Value
Method	POST
Path	/merchant/psp/sub-merchant/open-partner
Content-Type	application/json
Purpose	Create a sub-merchant

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Primary merchant number.
X-Timestamp	Header	int	19	Yes	Unix timestamp of the request in seconds, used for request freshness validation.
X-Nonce	Header	string	64	Yes	Random string for anti-replay.
Digest	Header	string	52	Yes	Request body digest, in the format SHA-256=<BASE64_DIGEST>.
Authorization	Header	string	-	Yes	ES256 request signature information, where keyId is the merchant key version number.
seqNo	Body	string	128	Yes	Request sequence number, used as the idempotency key.
subMerchantNo	Body	string	64	No	Sub-merchant number. The request value takes priority; if empty, Adopay generates one automatically.
subMerchantName	Body	string	128	Yes	Sub-merchant name.
subjectType	Body	string	64	Yes	Legal entity type of the sub-merchant: COMPANY (company) / INDIVIDUAL (individual).
registrationCountry	Body	string	64	Yes	Country of registration.
registrationNo	Body	string	64	Yes	Legal entity registration number.
taxNo	Body	string	64	No	Tax ID (CPF/CNPJ).
industry	Body	string	32	Yes	Industry; see the "Industry Enum" section.
websiteUrl	Body	string	255	Yes	Official website URL.
bizDescription	Body	string	512	Yes	Business description.
bizModel	Body	string	16	Yes	Merchant business model: currently B2B (business to business) and B2C (business to customer), and BOTH (all).
appliedProduct	Body	string	16	Yes	Product to be enabled.
monthlyTransactionAmount	Body	decimal(25,4)	25,4	Yes	Expected monthly transaction amount.
monthlyTransactionCount	Body	int	19	No	Expected monthly transaction count.
averageOrderAmount	Body	decimal(25,4)	25,4	No	Average order value.
collectionScene	Body	string	16	No	cashin scene description.
payoutScene	Body	string	16	No	cashout scene description.
notifyUrl	Body	string	255	No	URL where the partner receives the sub-merchant creation result notification. The submitted value takes priority; otherwise the partner's configured URL is used.

Industry Enum

Enum Value	Description
ECOMMERCE	E-commerce / retail
GAMING	Gaming
DIGITAL_CONTENT	Digital content / streaming
SAAS	SaaS / software / tools
TRADE	B2B trade
PROFESSIONAL_SERVICES	Corporate / professional services
TRAVEL	Travel / hotels / ticketing
EDUCATION	Education
LOGISTICS	Logistics / transportation
FINANCIAL_SERVICES	Finance / fintech
ADVERTISING	Advertising / marketing
OTHER	Other

Request Examples

Request headers:

POST /merchant/psp/sub-merchant/open-partner HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1790200000
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=<BASE64_DIGEST>
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

Request body example:

{
  "seqNo":"2322342374234234423423",
  "subMerchantNo": "S10001",
  "subMerchantName": "Example Sub Merchant Ltda.",
  "subjectType": "business",
  "registrationCountry": "BR",
  "registrationNo": "12345678000190",
  "taxNo": "12345678000195",
  "industry": "SAAS",
  "websiteUrl": "https://merchant.example.com",
  "bizDescription": "Provide online software and payment services.",
  "bizModel": "B2B",
  "appliedProduct": "pix",
  "monthlyTransactionAmount": 100000.00,
  "monthlyTransactionCount": 1000,
  "averageOrderAmount": 100.00,
  "collectionScene": "ONLINE",
  "payoutScene": "SUPPLIER",
  "notifyUrl": "https://merchant.example.com/callback/sub-merchant/create"
}

Response Fields

The endpoint uses the standard status, msg, and data response structure. This endpoint has no business response fields; data returns an empty object. A status of 200 in the response body means the creation request was accepted.

Field	Type	Always Returned	Description
status	int	Yes	Response code
msg	string	Yes	Corresponds to status
data	object	Yes	Business response data; this endpoint has no business response fields and returns an empty object.

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": {}
}

Response Error Codes

• Response Status