A API AZ Pay segue os princípios de design REST: recursos orientados a URLs, verbos HTTP (POST, PUT, GET e DELETE) para leitura e escrita, códigos de status HTTP para indicar sucesso ou erro e autenticação por token bearer. Todas as respostas são em JSON, incluindo os erros.
\nSuportamos chamadas diretas a partir de outras origens (CORS), o que permite integrar aplicações web com segurança. Nesses casos, use sua chave pública no navegador e reserve a chave secreta para chamadas entre servidores.
\n\nSua conta possui chaves de acesso para dois ambientes. O ambiente de homologação é uma cópia do de produção, mas cartões e contas bancárias não são cobrados.
\n| Ambiente | URL base | Uso |
|---|---|---|
| Produção (LIVE) | https://api.azape.co | Cobranças reais |
| Homologação (TEST) | https://api.azape.dev | Desenvolvimento e testes, com os cartões de teste listados abaixo |
\n\n🚧 Novos endereços a partir de 01/12/2026
A partir de 1º de dezembro de 2026 a API passa a responder também nos novos endereços, que se tornam os oficiais:
\n\n
\n Ambiente Nova URL base \n Produção (LIVE) https://api.azpay.meHomologação (TEST) https://api.staging.azpay.meOs endereços atuais continuam ativos durante o período de transição, e a data de desligamento será comunicada com pelo menos 90 dias de antecedência. Recomendamos parametrizar a URL base na sua integração para trocar de endereço sem alterar código. Nesta coleção, use as variáveis
baseUrlebaseStagingUrl(endereços atuais) oubaseUrlNewebaseStagingUrlNew(novos endereços).
A autenticação usa token bearer. Sua chave de acesso é enviada pela equipe AZ Pay no e-mail de ativação da conta. Para uma nova chave, ou caso não tenha mais a sua, fale com o suporte.
\nEnvie a chave no cabeçalho Authorization de toda requisição:
Authorization: Bearer <sua_chave>Toda a comunicação deve ser feita por HTTPS. Requisições recebidas sem HTTPS são consideradas comprometidas e falham.
\n\n🚧 Primeiro uso
A primeira requisição ativa a sua chave. Se você receber HTTP 403 nos primeiros minutos, aguarde de 5 a 10 minutos e tente novamente. Se o problema persistir, escreva para api@azape.co.
\n\n❗️ Guarde suas chaves
Salve suas chaves de API em local seguro. Não compartilhe suas chaves com ninguém, nem mesmo nos canais de suporte da AZ Pay. Nenhum colaborador da AZ Pay está autorizado a pedir sua chave de API ou qualquer outro dado sensível.
Para testar sua integração sem cartões reais, use o ambiente de homologação. Os números abaixo simulam transações aprovadas:
\n| Número | Bandeira |
|---|---|
| 4539003370725497 | Visa (digitada) |
| 4761340000000035 | Visa (Chip & PIN) |
| 4716588836362104 | Visa (Tarja) |
| 4532650104137832 | Visa Electron (Débito) |
| 5356066320271893 | MasterCard (digitada) |
| 5201561050024014 | MasterCard (Chip & PIN) |
| 5577270004286630 | MasterCard (Tarja) |
| 5138692036125449 | MasterCard Maestro (Débito) |
Estes números \"mágicos\" geram respostas específicas, úteis para testar cenários de erro:
\n| Número | Descrição |
|---|---|
| 6011457819940087 | A transação será recusada com um código de \"card_declined\". |
| 4929710426637678 | A transação será recusada com um código \"card_declined\". |
| 4710426743216178 | A transação será recusada com um código \"service_request_timeout\". |
\n\n\n📘 Nota
Você pode usar qualquer
holder_name,expiration_month,expiration_yearesecurity_codenas transações digitadas. Não use esses números em produção.
Para proteger a plataforma contra abuso, a API limita o volume de chamadas. Os limites atuais:
\n| Escopo | Limite | Janela |
|---|---|---|
| Todas as rotas, por endereço IP | 300 requisições | 1 minuto |
Criação de compradores e vendedores (POST /buyers, POST /sellers/individuals, POST /sellers/businesses), por chave de acesso | 30 requisições | 1 hora |
Ao exceder um limite, a API responde 429 Too Many Requests com o corpo abaixo e o cabeçalho RateLimit (RFC 9331 / draft-8) indicando quando a janela reinicia:
{ \"error\": true, \"message\": \"Too many requests, try again later.\" }Trate o 429 com nova tentativa após o tempo informado no cabeçalho, com espera exponencial. Não crie o mesmo comprador ou vendedor repetidas vezes: consulte antes com GET /buyers/search ou GET /sellers/search/:cpf_cnpj.
Nas rotas de criação de compradores e vendedores, os campos abaixo são validados antes do processamento. Um valor presente e inválido retorna 400 Bad Request com { \"error\": true, \"message\": \"Invalid <campo>\" }.
| Campo | Regra |
|---|---|
taxpayer_id | CPF (11 dígitos) ou CNPJ (14 dígitos) com dígitos verificadores válidos. Pontuação é aceita e ignorada. |
ein | CNPJ com dígitos verificadores válidos (vendedor pessoa jurídica). |
email, business_email | Formato de e-mail válido, até 254 caracteres. |
phone_number, business_phone | Entre 10 e 13 dígitos, formato E.164 recomendado (+5511999999999). |
O corpo das requisições JSON é limitado a 1 MB. O envio de documentos (multipart/form-data) aceita arquivos de até 3 MB.
Existem apenas três resultados possíveis na interação entre a sua aplicação e a API: tudo funcionou, a aplicação fez algo errado, ou a API fez algo errado. Códigos 2xx indicam sucesso, 4xx indicam erro nas informações enviadas (parâmetro obrigatório ausente, transação recusada) e 5xx indicam erro nos servidores da AZ Pay.
\nOs códigos mais comuns retornados pela API:
\n| HTTP STATUS CODE | Texto | Descrição |
|---|---|---|
| 200 | OK | Tudo funcionou conforme o esperado. |
| 201 | Created | A requisição foi bem-sucedida e um novo recurso foi criado. |
| 304 | Not Modified | Não havia dados novos para retornar. |
| 400 | Bad Request | A requisição foi inválida ou não atingiu o servidor. Muitas vezes, falta um parâmetro obrigatório. |
| 401 | Unauthorized | As credenciais de autenticação estavam faltando ou foram incorretas. |
| 402 | Request Failed | Os parâmetros foram válidos mas a requisição falhou. |
| 403 | Forbidden | A requisição foi ok, mas foi recusado ou o acesso não foi permitido. Uma mensagem de erro que acompanha a mensagem explica o porquê. |
| 404 | Not Found | A URI solicitada é inválida ou o recurso solicitado, como por exemplo, um vendedor não existe ou foi excluído. |
| 413 | Payload Too Large | O corpo da requisição excede 1 MB. |
| 429 | Too Many Requests | Limite de requisições excedido. Veja \"Limites de requisições\" e aguarde o tempo indicado no cabeçalho RateLimit. |
| 500 | Internal Server Error | Algo está quebrado. Por favor, assegure-se de que a equipe AZ Pay esteja investigando. |
| 502 | Bad Gateway | A AZ Pay caiu ou está sendo atualizada. |
Quando uma requisição falha, a API retorna um código HTTP 4xx ou 5xx e um JSON com detalhes do erro, contendo:
\nstatus e status_code;type e category, que você pode usar para tratar os erros na sua aplicação;message, uma mensagem legível explicando o motivo.Os valores possíveis para tipo e categoria:
\n| Status Code | Tipo | Categoria | Descrição | Código da bandeira |
|---|---|---|---|---|
| 500 | processing_error | server_api_error | Ocorreu um erro de processamento na AZ Pay. Se você receber esta mensagem, entre em contato com api@azape.co | |
| 409 | invalid_request_error | duplicate_taxpayer_id | Customer with this taxpayer_id already exists. | |
| 408 | invalid_request_error | service_request_timeout | Credit card process is temporarily unavailable at the specified location. | |
| 404 | invalid_request_error | endpoint_not_found | The requested URL was not found on the server | |
| 401 | invalid_request_error | authentication_failed | The supplied user credentials failed validation for the requested service. | |
| 401 | invalid_request_error | expired_security_key | The API Key provided has expired or has been deleted. | |
| 401 | invalid_request_error | invalid_key_for_api_call | This API call cannot be made with a publishable API key. | |
| 400 | invalid_request_error | transaction_amount_error | The minimum amount is $0.50 (or equivalent in country currency). The amount must be a positive integer in cents representing how much to charge, e.g 1260 for $12.60. | |
| 400 | invalid_request_error | transfer_amount_error | The minimum transfer amount is $1.00 (or equivalent in country currency). The amount must be a positive integer in cents representing how much to charge, e.g 1260 for $12.60. | |
| 400 | invalid_request_error | missing_required_param | Missing required parameter(s). Please verify request parameters. | |
| 400 | invalid_request_error | unsupported_payment_type | Invalid request: unsupported payment type. | |
| 400 | invalid_request_error | invalid_payment_information | Invalid payment information. Please verify request parameters. | |
| 400 | invalid_request_error | invalid_parameter | Invalid parameter(s). Your parameter value is incorrect. Please verify request parameters. | |
| 402 | file_upload | file_size_too_large | ||
| 402 | invalid_request_error | insufficient_escrow_funds_error | Requested transfer exceeds remaining settled funds in escrow. | |
| 402 | invalid_request_error | capture_transaction_error | The capture request failed. Transaction could not be captured. | |
| 402 | invalid_request_error | no_action_taken | No action taken. Unable to back out prior transaction | |
| 402 | invalid_request_error | seller_authorization_refused | Seller has not been authorized to charge credit cards. Complete activation to start processing payments. | |
| 402 | invalid_request_error | void_transaction_error | The void request failed. Transaction could not be voided. | |
| 402 | card_error | invalid_expiry_month | Invalid expiry month value. Please verify request parameters. | |
| 402 | card_error | invalid_expiry_year | Invalid expiry year value. Please verify request parameters. | |
| 402 | card_error | card_customer_not_associated | Transaction denied. No active card. | |
| 402 | card_error | insufficient_funds_error | Requested credit exceeds remaining settled funds. | 51 |
| 402 | card_error | expired_card_error | The credit card has expired. | 33 |
| 402 | card_error | invalid_card_number | The card number is not a valid credit card number. | 15 |
| 402 | card_error | invalid_pin_code | Transaction denied. Invalid PIN code. | 55 |
| 402 | card_error | authorization_refused | Transação ilegal | 58 |
Para compatibilidade com novos códigos, interprete os intervalos: 200 a 299 como sucesso, 400 a 499 como erro do cliente e 500 a 599 como erro do servidor.
","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"4126294","team":1755755,"collectionId":"cc7bed68-1ef1-4955-bbc9-ec4318d53f25","publishedId":"2sBYB2qnBJ","public":true,"publicUrl":"https://docs.azpay.me","privateUrl":"https://go.postman.co/documentation/4126294-cc7bed68-1ef1-4955-bbc9-ec4318d53f25","customColor":{"top-bar":"201F23","right-sidebar":"303030","highlight":"965EF4"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":"Documentação da API AZ Pay: cobranças por cartão, boleto e Pix, split, vendedores, compradores, transferências, planos, assinaturas e webhooks. Ambientes de produção e homologação, cartões de teste e códigos de erro."},{"name":"title","value":"AZ Pay | Documentação da API"}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"965EF4"}},{"name":"light","logo":null,"colors":{"top-bar":"201F23","right-sidebar":"303030","highlight":"965EF4"}}]}},"version":"8.12.7","publishDate":"2026-09-22T15:46:34.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"AZ Pay | Documentação da API","description":"Documentação da API AZ Pay: cobranças por cartão, boleto e Pix, split, vendedores, compradores, transferências, planos, assinaturas e webhooks. Ambientes de produção e homologação, cartões de teste e códigos de erro."},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/1081002069ccfba0d3552e915b3ef230dabd01a8381bfbd8d59a8f120d33511f","favicon":"https://res.cloudinary.com/postman/image/upload/v1748876741/team/590274e8d186faf37b16b27a69a34059.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.azpay.me/view/metadata/2sBYB2qnBJ"}