Partner API

The Partner API is intended for partners such as platforms, ISVs, PSPs, and acquirers that need to integrate once and process transactions for many downstream merchants.

Positioning

A partner integrates with ADOPAY using its own API credentials (primary merchant ID) and manages its downstream merchants as sub-merchants:

• The X-Merchant-Id request header carries the primary merchant ID, i.e. the partner credential.
• The subMerchantNo request field identifies the sub-merchant that owns the operation; its exact location is defined by each endpoint, and webhook events also carry it so notifications can be routed to the right merchant.
• The accessMode request field declares the integration model: normal (standard merchant), saas_isv (SaaS / ISV), acquirer (acquirer), platform (platform service provider).

Relationship to the Merchant API

The Partner API shares the same transaction core as the Merchant API: cashin, refund, and cashout keep identical field and capability models. The differences:

Difference	Merchant API	Partner API
Credential owner	The merchant itself	The partner (primary merchant ID)
Transaction owner	The merchant	Sub-merchant (subMerchantNo)
Integration-mode parameter	-	accessMode required

Integration Flow

Sign the commercial agreement; obtain the partner credentials (primary merchant ID / keys / keyId)
   ↓
Confirm accessMode and how sub-merchant numbers (subMerchantNo) are assigned
   ↓
Adopt the Common specs (authentication / signing / webhooks)
   ↓
Integrate by capability: Account -> cashin -> refund -> cashout -> MED

For the shared specs (authentication, request signing, response structure, idempotency, and webhook rules), see Common.

API Directory

Account

• Paginated account balance query (covering the primary merchant itself and its sub-merchants)

Merchant

• Create sub-merchant
• Sub-merchant creation webhook

Cashin

• Create payment / QR code (create a PIX QR code)
• Decode PIX payment QR code
• Query payment order (merchant order number / e2eId)
• Create refund
• Query refund detail
• Payment webhook
• Refund webhook

Cashout

• Create PIX Out
• Query PIX Out (merchant order number / e2eId)
• Get proof link
• PIX Out webhook

PixKey Management

Merchants and partners share the same set of PixKey APIs.

• Pix Key registration
• Send verification code (mobile / email)
• Pix Key list query
• Pix Key details query
• Pix Key modification
• Pix Key deletion (unbind)

Reconciliation Files

• File guide

MED API (special refund mechanism)

Handle Brazilian Central Bank MED fraud disputes on behalf of your sub-merchants: query, analyze, and process infraction reports.

• MED overview
• Query MED list
• Query MED details
• Get evidence requirements
• Upload evidence file
• Submit analysis
• Webhook callbacks

Planned Capabilities

The following capabilities have no published specification yet; do not integrate against them until they are officially released:

• Partner limit queries
• Merchant management (online)
• Settlement and settlement reports