API de parceiros

1. Abra a conta com os dados básicos (e, se tiver, os dados completos do KYC).
2. Envie os documentos e a prova de vida pela API, se o seu app tem câmera, ou mande ao titular o link de verificação para ele fazer pelo celular.
3. Envie para análise. A Arcano Pay roda a análise automática e a equipe decide, normalmente em até 1 dia útil.
4. Receba o resultado por webhook (kyc.approved, kyc.rejected ou kyc.resubmission_requested).
5. Integre a conta aprovada: gere a chave sk_live_ dela, cadastre os webhooks de vendas e, se quiser, convide o titular para o portal.

Use a chave de parceiro (pk_live_…) que a Arcano Pay enviou, no cabeçalho Authorization: Bearer. Ela só funciona em /partner/v1 e só enxerga as contas que você abriu. Guarde no servidor, nunca no app ou no navegador.

curl https://stage.arcanopay.com/partner/v1/me -H "Authorization: Bearer $ARCANO_PARTNER_KEY" -H "Content-Type: application/json"

type é individual (PF) ou company (PJ). Repetir o mesmo externalId devolve a conta já aberta (200, existing: true): seguro para novas tentativas. CPF/CNPJ ou e-mail que já tenham conta na Arcano Pay respondem 409.

curl -X POST https://stage.arcanopay.com/partner/v1/accounts -H "Authorization: Bearer $ARCANO_PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "type": "individual",
  "externalId": "cli-42",
  "document": "529.982.247-25",
  "name": "Maria Silva Souza",
  "email": "maria@exemplo.com",
  "phone": "11987654321",
  "person": { "birthDate": "1990-05-10", "motherName": "Ana Silva", "pep": false },
  "address": { "zipCode": "01001000", "street": "Praça da Sé", "number": "1",
           "neighborhood": "Sé", "city": "São Paulo", "state": "SP" }
}'

curl -X POST https://stage.arcanopay.com/partner/v1/accounts -H "Authorization: Bearer $ARCANO_PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "type": "company",
  "externalId": "loja-7",
  "document": "11.222.333/0001-81",
  "name": "Casa Dionísio Comércio LTDA",
  "tradeName": "Casa Dionísio",
  "email": "financeiro@casadionisio.com.br",
  "phone": "1133334444",
  "representative": { "name": "João Pereira Lima", "email": "joao@casadionisio.com.br",
                  "cpf": "111.444.777-35", "birthDate": "1985-02-20" },
  "company": { "businessActivity": "Comércio de vinhos", "monthlyRevenue": 5000000 },
  "address": { "zipCode": "01001000", "street": "Praça da Sé", "number": "1",
           "neighborhood": "Sé", "city": "São Paulo", "state": "SP" }
}'

A resposta traz account e kyc, com requirements e missing (o que ainda falta: person, company, address, idFront, companyDocument, liveness).

Completa ou corrige os dados depois da abertura. Envie só os blocos que quiser: person (titular ou representante: fullName, cpf, birthDate, motherName, phone, occupation, pep), company (legalName, cnpj, businessActivity…) e address. Só pode ser alterado antes do envio ou quando a análise pedir ajuste.

Envie como multipart/form-data (campos kind, docType e file) ou em JSON com contentBase64. JPG, PNG, WEBP ou PDF (PDF só para documento da empresa e comprovante), até 8 MB. Reenviar o mesmo kind substitui o anterior.

curl -X POST https://stage.arcanopay.com/partner/v1/accounts/cli-42/kyc/documents -H "Authorization: Bearer $ARCANO_PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "kind": "id_front", "docType": "cnh", "fileName": "frente.jpg",
  "contentBase64": "/9j/4AAQSkZJRgABAQ..."
}'

Para quem tem câmera no próprio app. A Arcano Pay sorteia os desafios; tire cada foto na hora, na ordem, e conclua em até 3 minutos. O passo 0 (olhar para a câmera) vira a selfie comparada com o documento.

# 1. começa: devolve sessionId e os passos (ex.: olhar para a câmera, virar à esquerda, sorrir…)
POST /partner/v1/accounts/:id/kyc/liveness
→ { "sessionId": "lvs_…", "expiresAt": "…", "steps": [{ "challenge": "look_straight", "instruction": "Olhe para a câmera" }, …] }

# 2. uma foto por passo (multipart com step e file, ou JSON com contentBase64)
POST /partner/v1/accounts/:id/kyc/liveness/:sessionId/frames   { "step": 0, "contentBase64": "…" }

# 3. conclui
POST /partner/v1/accounts/:id/kyc/liveness/:sessionId/complete

Sem câmera no seu app? Gere um link e mande por e-mail, SMS ou WhatsApp. O titular (ou o representante da PJ) abre no celular, fotografa os documentos, faz a prova de vida e envia para análise, sem login e sem ver os dados cadastrais. O link deixa de valer depois do envio.

curl -X POST https://stage.arcanopay.com/partner/v1/accounts/cli-42/kyc/link -H "Authorization: Bearer $ARCANO_PARTNER_KEY" -H "Content-Type: application/json" -d '{ "expiresInHours": 48, "redirectUrl": "https://seu-sistema.com/pronto" }'
→ { "id": "kyl_…", "url": "https://portal.arcanopay.com/verificacao/kyl_…", "expiresAt": "…" }

Confere tudo e envia. Se faltar algo, responde 422 com details.missing. Enviado pelo link, não precisa chamar esta rota. A conta passa a in_review e você recebe kyc.submitted e, depois da análise automática, kyc.in_review.

Liste com filtros status, kycStatus, document, externalId, limit e offset. :id aceita o id da conta (mer_…) ou o seu externalId. /kyc traz o que falta, os documentos enviados e o histórico (events). Quando a análise pede ajuste, o motivo vem em account.kyc.reason: corrija e envie de novo.

Com a chave sk_live_ da conta, siga a documentação de pagamentos (Pix, cartão, estornos, saques e conciliação), disponível no portal da conta em Integração › Documentação.

Se a sua plataforma recebe pelos clientes (por exemplo, vende o serviço deles e repassa o valor), transfira do saldo disponível da sua conta Arcano Pay direto para a conta que você abriu para cada um. É na hora, sem Pix e sem tarifa: o valor sai da sua conta e entra na do cliente no mesmo instante, e os dois extratos mostram o lançamento (transfer_out e transfer_in). A conta de origem é a conta Arcano Pay da sua empresa, ligada ao seu cadastro de parceiro pela equipe Arcano Pay. Só contas active recebem.

curl -X POST https://stage.arcanopay.com/partner/v1/accounts/cli-42/transfers -H "Authorization: Bearer $ARCANO_PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "amount": 15840, "externalId": "repasse-981", "description": "Repasse · Troca de disjuntor"
}'
→ 201 { "existing": false, "transfer": { "id": "tr_…", "accountId": "mer_…", "externalId": "repasse-981",
         "amount": 15840, "description": "Repasse · Troca de disjuntor", "createdAt": "…" } }

Erros: 422 saldo disponível insuficiente (nada é transferido) ou dados inválidos; 409 conta de destino ainda não ativa, parceiro sem conta de origem ou externalId já usado em outra transferência; 404 conta de outro parceiro. Você recebe o webhook transfer.completed com data.transfer e data.account.

A conta é do titular; você gere o vínculo dela com a sua plataforma. Tudo também pode ser feito no Portal do Parceiro, onde sua equipe acompanha as contas e a comissão. O motivo (reason, de 5 a 300 caracteres) é obrigatório, menos para reativar.

A resposta traz account.link com status (active, paused ou revoked), reason e changedAt. Em conta desvinculada, as outras rotas devolvem 409 com code: account_revoked; a consulta da conta continua funcionando. Uma cobrança numa conta pausada devolve 403 com code: sales_paused.

Cadastre uma URL HTTPS com { "url": "https://…", "events": ["*"] }. A resposta traz o secret para verificar a assinatura Arcano-Signature: t=…,v1=HMAC-SHA256(secret, t + "." + corpo), igual aos webhooks de pagamento. Reenviamos em caso de falha (até 24 h) e você vê as entregas em GET /partner/v1/webhook-deliveries. A ordem de chegada não é garantida: use createdAt e o status em data.account.

{
  "id": "evt_…",
  "type": "kyc.approved",
  "createdAt": "2026-10-20T13:02:11.000Z",
  "data": {
"account": {
  "id": "mer_…", "externalId": "cli-42", "type": "individual", "status": "active",
  "kyc": { "id": "kyc_…", "status": "approved", "nextStep": "ready" }
}
  }
}

Para ser parceiro, fale com a Arcano Pay: cadastramos a sua empresa e enviamos a chave pk_live_.