Aplicativos OAuth

Portal do desenvolvedor

Crie e gerencie aplicativos de parceiros em https://apps.makecrypto.io. As aplicações pertencem a uma empresa MakeCrypto e definem os URIs de redirecionamento, escopos OAuth permitidos, webhooks, ícone, contato de suporte, política de privacidade e termos exibidos durante o consentimento.

Cada aplicativo confidencial possui um segredo do cliente. O segredo é exibido uma vez quando é criado ou girado e é armazenado apenas como um hash. Aplicativos públicos devem utilizar PKCE e não recebem sigilo.

Código de autorização com PKCE

MakeCrypto suporta OAuth delegado pela empresa para aplicativos de parceiros. Inicia o fluxo enviando o usuário para o terminal de autorização com um URI de redirecionamento registrado exato e um desafio PKCE S256.

GET https://makecrypto.io/oauth/authorize
  ?response_type=code
  &client_id=mco_app_...
  &redirect_uri=https%3A%2F%2Fpartner.example%2Fcallback
  &scope=company%3Aread%20makepay%3Apayment-links%3Aread
  &resource=https%3A%2F%2Fmakecrypto.io%2Fapi%2Fpartner%2Fv1
  &code_challenge=BASE64URL_SHA256_VERIFIER
  &code_challenge_method=S256

O usuário escolhe a empresa, analisa as permissões solicitadas e aprova ou rejeita o acesso. Se você aprovar, MakeCrypto o redirecionará de volta com um código de autorização de curta duração.

Troque o código no endpoint do token. Clientes confidenciais autenticam-se com client_secret_basic ou client_secret_post; clientes públicos são autenticados com seu verificador client_id e PKCE.

POST https://makecrypto.io/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code
&code=mco_code_...
&redirect_uri=https%3A%2F%2Fpartner.example%2Fcallback
&code_verifier=ORIGINAL_PKCE_VERIFIER

Os tokens de acesso são portadores JWT de curta duração. Os tokens de atualização são alternados a cada uso, e a reutilização de um token de atualização revoga a família de tokens.

Integrações nativas oficiais, como o plugin WordPress do MakePay, não usam o portal do desenvolvedor ou um segredo de cliente compartilhado. Eles registram uma instalação pública por loja em POST /oauth/native/installations, usam correspondência exata de URI de retorno de chamada e recebem tokens vinculados a DPoP que devem ser enviados com Authorization: DPoP e um cabeçalho de teste DPoP correspondente.

SDK oficial

Use o SDK oficial quando desejar integração do lado do servidor sem criar o cliente HTTP, cargas úteis de link de pagamento e verificação de assinatura webhooks do zero.

SDK	Usar	Guia
SDK PHP de MakePay	PHP, Laravel, Symfony, checkout customizado e criação backend de links pagos.	SDK PHP
SDK MakePay NPM	Back-ends Node.js, Next.js, TypeScript e manipuladores do lado do servidor webhooks.	SDK NPM

Pontos finais

Propósito	Ponto final
Autorização	GET /oauth/authorize
Troca de tokens	POST /oauth/token
Revogação	POST /oauth/revoke
Introspecção	POST /oauth/introspect
Solicitação de autorização enviada	POST /oauth/par
Log de instalação nativa	POST /oauth/native/installations
JWKS	GET /oauth/jwks.json
Metadados do servidor de autorização	GET /.well-known/oauth-authorization-server
Metadados de recursos protegidos	GET /.well-known/oauth-protected-resource

Escopo

escopo	Acesso
company:read	Leia a identidade e as configurações básicas da empresa selecionada.
wallet:balances:read	Leia os saldos da carteira da empresa selecionada.
wallet:activity:read	Leia a atividade e liquidação da carteira.
makepay:payment-links:read	Leia os links de pagamento MakePay e o status do pagamento.
makepay:payment-links:write	Crie e atualize links de pagamento MakePay.
makepay:customers:read	Leia os registros do cliente MakePay.
makepay:customers:write	Crie e atualize registros de clientes MakePay.
makepay:subscriptions:read	Leia os logs de assinatura MakePay.
makepay:subscriptions:write	Crie e atualize assinaturas MakePay.
makepay:settings:read	Leia as configurações do comerciante MakePay e os ativos ativados.
makepay:settings:write	Atualize as configurações do comerciante MakePay e a configuração de retorno de chamada.
makepay:webhooks:read	Leia os endpoints webhook MakePay e os logs de entrega.
makepay:webhooks:write	Crie, atualize, teste e tente novamente entregas de webhook MakePay.

Permissões de rota API

Rota	Método	Escopo necessário
/api/partner/v1/makepay/payment-links	GET	makepay:payment-links:read
/api/partner/v1/makepay/payment-links	POST	makepay:payment-links:write
/api/partner/v1/makepay/customers	GET	makepay:customers:read
/api/partner/v1/makepay/customers	POST	makepay:customers:write
/api/partner/v1/makepay/subscriptions	GET	makepay:subscriptions:read
/api/partner/v1/makepay/subscriptions	POST	makepay:subscriptions:write
/api/partner/v1/makepay/settings	GET	makepay:settings:read
/api/partner/v1/makepay/settings	PUT	makepay:settings:write
/api/partner/v1/makepay/webhook-requests	GET	makepay:webhooks:read
/api/partner/v1/companies/{id}/wallet/balances	GET	wallet:balances:read
/api/partner/v1/companies/{id}/wallet/activity	GET	wallet:activity:read

Assinatura de webhooks

Os aplicativos webhookss incluem um cabeçalho makecrypto-signature com carimbo de data/hora e valores de assinatura v1. Verifica a atualização do carimbo de data/hora, reconstrói a carga assinada como timestamp.rawBody e compara a assinatura com o segredo webhook mostrado uma vez ao criar ou girar o terminal.

Gerenciamento de aplicativos conectados

As concessões OAuth aprovadas ficam visíveis no painel da empresa em Integrations -> Connected apps. Os administradores corporativos podem revisar o status do aplicativo, o último acesso e os escopos concedidos, além de revogar o acesso quando uma conexão de parceiro precisar ser interrompida.