Onboarding Guide

Welcome to Adopay OpenAPI.

This guide walks you through confirming your integration model, registering your account, completing KYB/KYC verification, running Sandbox integration testing, and going live in production.

Onboarding Flow at a Glance

%%{init: {"flowchart": {"nodeSpacing": 30, "rankSpacing": 40, "wrappingWidth": 360}}}%%
flowchart LR
    START(["Start onboarding"]) --> MODE{"Confirm integration model"}
    MODE -->|"Merchant direct"| SIGN1["Sign with Adopay sales<br>Back-office account provisioning"]
    MODE -->|"Partner"| SIGN2["Sign with Adopay sales<br>Confirm accessMode and subMerchantNo"]
    SIGN1 --> REG["Register console account (admin + MFA)"]
    SIGN2 --> REG
    REG --> KYB["Prepare and submit KYB / KYC documents"]
    KYB --> AUDIT{"Compliance review"}
    AUDIT -->|"Documents required / EDD"| FIX["Supplement documents per console or email notice"]
    FIX --> AUDIT
    AUDIT -->|"Approved"| CONSOLE["Access the console"]
    CONSOLE --> CREDS["Obtain Sandbox credentials<br>Register P-256 public key"]
    CREDS --> DEV1["Implement signing, signature verification, and idempotency"]
    DEV1 --> DEV2["Configure webhook endpoint"]
    DEV2 --> TEST["Complete first cashin and cashout in Sandbox"]
    TEST --> PASS{"Integration testing accepted?"}
    PASS -->|"No, troubleshoot and fix"| DEV1
    PASS -->|"Yes"| PROD["Request production environment<br>Complete go-live checklist"]
    PROD --> LIVE(["Go live"])

1. Confirm Your Integration Model

Before getting started, confirm your customer type, account model, and required product capabilities with the Adopay sales team or implementation manager.

The account model is determined by your legal entity, business scenario, account provisioning documents, and compliance review results; it cannot be selected or changed unilaterally via the API.

Depending on your partnership plan, you can apply for capabilities such as accounts, Pix cashin and cashout, batch payouts, FX conversion, cross-border settlement, split payments, refunds and MED, and reporting and reconciliation. Actual products, currencies, and limits are subject to what is ultimately provisioned.

Two Integration Models

ADOPAY uses one shared capability platform + two integration models:

                       ADOPAY
                          │
             ┌────────────┴────────────┐
             │                         │
       Merchant (direct)         Partner
             │                         │
             │                    ┌────┼────┐
             │                    │    │    │
             │                   M-A  M-B  M-C
             │
        Own transactions / own funds

Dimension	Merchant (direct)	Partner
Intended for	Merchants processing their own transactions	Partners such as platforms, ISVs, PSPs, and acquirers managing multiple downstream merchants
API Credential	Held by the merchant	Held by the partner
API caller	Merchant	Partner (on behalf of downstream merchants)
Transaction owner	Merchant	Downstream merchant (subMerchantNo)
Webhook receiver	Merchant	Partner
Funds / settlement owner	Merchant	Configured per partnership model
Account provisioning	Offline contract with sales, back-office provisioning, no Create Merchant API	Partner credentials; downstream merchants managed as sub-merchants

How to choose:

• You only process your own transactions and funds -> Merchant API
• You need to integrate, call APIs, and receive callbacks on behalf of multiple downstream merchants -> Partner API

Both models reuse the same transaction core: Collection / Refund / Payout keep identical field and capability models; the Partner side only adds the sub-merchant dimension (accessMode, subMerchantNo).

Confirm Account Provisioning and Integration Parameters

1. Complete contract signing with the sales team; account provisioning is handled by ADOPAY operations — the merchant model has no online provisioning API.
2. In the Partner model, also confirm the integration model parameter accessMode (normal / saas_isv / acquirer / platform) and how sub-merchant IDs (subMerchantNo) are allocated.

2. Register a Console Account

After the partnership is confirmed, Adopay sends a console invitation to your administrator.

The administrator needs to:

1. Enter the administrator's name, work email, and mobile number;
2. Verify the email and mobile number;
3. Set a login password;
4. Accept the applicable service agreements;
5. Configure multi-factor authentication (MFA).

Successful console registration does not mean KYB/KYC is complete or that production transaction permissions have been granted.

Do not share the administrator account among multiple people. You can create separate users for engineering, finance, operations, and risk staff, and assign role permissions according to their responsibilities.

3. Complete KYB/KYC Verification

To meet the financial, payment, and anti-money-laundering regulatory requirements applicable in Brazil, you must complete the corresponding identity and business reviews.

Corporate KYB

Corporate clients usually need to submit:

• Certificate of company registration and the latest articles of association;
• Tax registration and proof of registered address;
• Shareholder register, ownership structure, and ultimate beneficial owner (UBO) information;
• Identity and address documents for the legal representative, UBOs, and authorized persons;
• Business proof such as an official website, business description, or customer contracts;
• Proof of a settlement account in the company's own name;
• Business model, fund flows, and expected transaction volume.

Additional Documents for Institutional Clients

Payment institutions, PSPs, ISVs, or platform clients may also need to provide:

• Applicable financial, payment, MSB, or VASP licenses;
• AML, sanctions, and merchant management policies;
• Downstream merchant types and main industries;
• Cashin, cashout, FX, and settlement fund flows;
• Complaint, refund, MED, and RFI handling mechanisms.

Individual KYC

The legal representative, UBOs, authorized signatories, or other key persons usually need to provide:

• Legal name and tax ID (CPF/CNPJ);
• A valid identity document;
• Proof of address;
• Facial recognition or a selfie holding the identity document;
• Mobile number and email verification.

4. Review and Document Supplements

After you submit your application, the Adopay compliance team will review it.

Review status and turnaround details: pending specification.

If documents need to be supplemented, Adopay will notify you via the console or the work email on record. Some clients or business scenarios may require enhanced due diligence (EDD).

Make sure all submitted documents are authentic, complete, clear, and within their validity period. Completing basic KYB/KYC does not mean all product capabilities will be enabled automatically.

5. Access the Console

Once the review is approved, you can use the Adopay console according to your assigned roles, including:

• Merchant and account management;
• Balance and fund flow queries;
• Pix Key and Pix transaction management;
• MED, RFI, and document supplement handling;
• Reconciliation report downloads;
• API credential and webhook configuration;
• Users, roles, and security settings.

Available features depend on the product permissions provisioned for you.

6. Obtain Sandbox Credentials

After the initial review is complete and the technical solution is confirmed, Adopay will provision the Sandbox environment.

At provisioning time, Adopay assigns a merchant ID and key version, and provides the Sandbox environment address plus the platform public key used for signature verification. The P-256 key pair is generated by you; the public key takes effect once submitted to Adopay for registration:

• Merchant ID: the merchant identifier assigned by Adopay, passed in requests via X-Merchant-Id; in Partner mode, the top-level merchant ID is used.
• Key version: identified by keyId in the Authorization header, used for key rotation.
• P-256 private key: generated and kept by you, used to generate the ES256 request signature.
• P-256 public key: submitted to Adopay for registration, used by Adopay to verify request signatures.
• Platform public key: provided with the provisioning documents, used to verify the ES256 signatures of responses and webhook notifications.
• Sandbox environment address: provided by Adopay at provisioning time.

Sandbox and Production use completely independent credentials. Keys must be kept only in a secure server-side environment; never embed them in frontend code, mobile apps, or public code repositories.

Before starting integration testing, read the Common Specifications: Authentication, Request Signing (including signature verification), Response Format / Response Status Codes, Idempotency, Error Codes, Date and Time / Amounts and Currencies, and Webhook Specification.

7. Start API Integration Testing

We recommend completing the integration in the following order.

Step 1: Implement Signing and Idempotency

Generate request signatures following the "Authentication and Signing" chapter.

All order creation, payment, refund, FX, and settlement requests must carry a unique idempotency key:

Idempotency-Key: {unique-value}

After a network timeout, query the original request's result first; do not simply change the idempotency key and resubmit.

Step 2: Configure Webhooks

POST /v4/webhook-endpoints

The webhook endpoint must use HTTPS and must be able to:

• Verify webhook signatures;
• Deduplicate by event_id;
• Handle duplicate or out-of-order notifications;
• Return a 2xx status code within the required time.

In the current documentation, the callback URL can also be specified via the notifyUrl field in order requests, or configured centrally in the merchant back office / by operations; for delivery, signature verification, retry, and response requirements, see the Webhook Specification.

Step 3: Complete Sandbox Testing and Your First Transactions

First get one cashin and one cashout working end to end, then cover each test focus item by item.

Complete your first cashin:

1. Call the cashin order creation API to create a Pix dynamic QR-code order:
   • Merchant: Create Payment / QR Code
   • Partner: cashin Order
2. Render the returned qrCodeUrl as a QR code or copy it to the payer.
3. Wait for the payment result webhook; you can also query proactively via the order inquiry API:
   • Merchant: Query Payment by Merchant Order ID
   • Partner: cashin Order Inquiry

Complete your first cashout:

1. Call the cashout API with the payee information and Pix Key:
   • Merchant: Create PIX Payout
   • Partner: cashout Request
2. Wait for the cashout result webhook; you can also query the order status proactively:
   • Merchant: Query PIX Payout
   • Partner: cashout Order Inquiry

Test focus:

• Authentication, signing, and idempotency;
• Webhook signature verification, retries, and deduplication;
• Merchants, accounts, and Pix Keys;
• Pix cashin, cashout, refunds, and exception states;
• Payment proof;
• FX quotes, rate locking, and execution;
• Transaction, balance, fee, and settlement reconciliation.

For asynchronous requests, the final result is determined by the resource inquiry API or the webhook notification.

8. Request the Production Environment

After Sandbox testing is complete, submit your go-live request to your Adopay implementation manager.

Before go-live, both parties need to confirm:

• KYB/KYC and any required EDD are complete;
• Contracts, quotations, and settlement terms are in effect;
• Product permissions, account model, currencies, and limits are confirmed;
• Same-name and non-same-name transaction rules are confirmed;
• Production IP allowlist and webhooks are configured;
• MED, RFI, and abnormal transaction handling processes are confirmed;
• Sandbox testing and reconciliation acceptance have passed.

Technical go-live checklist:

• Signing / signature verification passes in both Sandbox and production
• Webhook endpoint is publicly reachable, responds within 3 seconds, and verifies signatures and deduplicates
• All timeout / unknown-error scenarios re-query the order status — never assume a final state directly
• Idempotency: duplicate notifications for the same order ID do not cause duplicate entries
• Amount units and currencies are handled correctly (see Amounts and Currencies)
• Partner model: accessMode and subMerchantNo confirmed consistent with operations

After approval, Adopay will separately provide the Production Base URL and production environment credentials.

9. Practical Tips

• Document quality: uploaded documents should be clear and complete, with no obstruction, glare, or cropping.
• Account security: enable MFA and rotate API credentials regularly.
• Status determination: for asynchronous transactions, never judge the final result from the HTTP response alone.
• Environment isolation: Sandbox and production addresses, credentials, and data are fully independent.
• Technical support: when submitting an issue, provide the environment, API path, request time, X-Request-Id, and related resource IDs.
• Production permissions: passing Sandbox testing does not automatically grant production permissions.