Referência Técnica

API de Cobranças PIX

Endpoints, parâmetros e exemplos para criação e consulta de cobranças

View as Markdown

Requisitos de autenticação

Para emitir cobranças PIX, use:

  • Authorization: Bearer {{accessToken}} com o token obtido no login do acesso INTEGRATION_ONLY
  • secret-key: {{secretKeyBase64}}
  • Origin: {{allowedOrigin}}

Os endpoints de consulta exigem:

  • Authorization: Bearer {{accessToken}}

Endpoints disponíveis

MétodoCaminhoFinalidade
POST/pix/create/brl/integrationEmite uma cobrança PIX em BRL para a integração documentada.
GET/pixLista cobranças PIX do usuário autenticado com filtro opcional por período.
GET/pix/{pixId}Consulta o detalhe de uma cobrança PIX específica.

Criar cobrança PIX em BRL

1POST https://api-pix.gomoney.me/pix/create/brl/integration
2Authorization: Bearer {{accessToken}}
3secret-key: {{secretKeyBase64}}
4Origin: {{allowedOrigin}}
5Content-Type: application/json

Corpo da requisição

CampoTipoObrigatórioDescrição
amountnumberSimValor da cobrança.
payerDocumentstringSimDocumento do pagador.
payerNamestringSimNome do pagador.
allowThirdPartyPaymentbooleanNãoPermite pagamento por terceiro.
correlationIdstringNãoReferência própria do integrador para conciliação.
isCreditGmcbooleanNãoDefine o comportamento operacional do crédito.
customerIdentifierstringSim_id ou taxId do customer associado à cobrança.

Regras operacionais

  • a secret-key precisa pertencer ao mesmo usuário do token Bearer;
  • o header Origin precisa corresponder ao domínio liberado na integração;
  • customerIdentifier é obrigatório e pode ser enviado como _id ou taxId;
  • as taxas PIX seguem a hierarquia customer -> user -> settings;
  • a wallet operacional do usuário precisa estar cadastrada e aprovada para o direcionamento dos recebimentos PIX em GMC.

Exemplo de requisição

1{
2  "amount": 150.5,
3  "payerDocument": "39053344705",
4  "payerName": "Pagador Externo",
5  "allowThirdPartyPayment": false,
6  "correlationId": "ORDER-1001",
7  "isCreditGmc": true,
8  "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001"
9}

Resposta de sucesso

1{
2  "_id": "66f0b1b5c1f7b7dc0ce40001",
3  "txid": "4b8f5a4f7d8c4b45a5a6258a7e2b1234",
4  "amount": 150.5,
5  "credit": 146.24,
6  "payerDocument": "39053344705",
7  "payerName": "Pagador Externo",
8  "userId": "66f0b1b5c1f7b7dc0ce20001",
9  "valueCreditInGmc": null,
10  "status": "opened",
11  "isCreditGmc": true,
12  "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001",
13  "pix": {
14    "id": 12001,
15    "qrcode": {
16      "emv": "0002010102122680...",
17      "png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
18    },
19    "formats": {
20      "default": {
21        "html": "https://pix.example.com/checkout/4b8f5a4f7d8c4b45a5a6258a7e2b1234",
22        "png": "https://pix.example.com/files/default.png",
23        "pdf": "https://pix.example.com/files/default.pdf"
24      },
25      "qrcode": {
26        "html": "https://pix.example.com/files/qrcode.html",
27        "png": "https://pix.example.com/files/qrcode.png",
28        "pdf": "https://pix.example.com/files/qrcode.pdf"
29      }
30    }
31  }
32}

Códigos de retorno

CódigoSignificadoAção recomendada
201Cobrança criada com sucesso.Persistir _id, txid, customerIdentifier e o material de pagamento.
400Dados inválidos, valor inconsistente ou customerIdentifier ausente/inválido.Revisar documento do pagador, valor e vínculo com customer.
401Token, secret-key ou Origin inválidos para a integração.Renovar o token e revisar credencial e domínio liberado.
403Usuário sem permissão para a operação.Confirmar que o acesso usado é do tipo INTEGRATION com INTEGRATION_ONLY ativo.
503Fluxo GMC indisponível temporariamente.Reprocessar em janela operacional permitida.

Listar cobranças PIX

1GET https://api-pix.gomoney.me/pix?initialDate=2026-07-01&finalDate=2026-07-31
2Authorization: Bearer {{accessToken}}

Parâmetros de query

ParâmetroTipoObrigatórioDescrição
initialDatestring (date)NãoData inicial do filtro.
finalDatestring (date)NãoData final do filtro.

Resposta de sucesso

1[
2  {
3    "_id": "66f0b1b5c1f7b7dc0ce40001",
4    "txid": "4b8f5a4f7d8c4b45a5a6258a7e2b1234",
5    "amount": 150.5,
6    "status": "opened",
7    "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001"
8  }
9]

Códigos de retorno

CódigoSignificadoAção recomendada
200Lista retornada com sucesso.Usar os identificadores recebidos para consulta ou conciliação.
401Token inválido.Renovar a sessão da API PIX com o acesso de integração correto.

Consultar cobrança PIX por ID

1GET https://api-pix.gomoney.me/pix/{{pixId}}
2Authorization: Bearer {{accessToken}}

Parâmetro de rota

ParâmetroTipoObrigatórioDescrição
pixIdstringSimIdentificador interno da cobrança PIX.

Resposta de sucesso

1{
2  "_id": "66f0b1b5c1f7b7dc0ce40001",
3  "txid": "4b8f5a4f7d8c4b45a5a6258a7e2b1234",
4  "amount": 150.5,
5  "credit": 146.24,
6  "status": "paid",
7  "customerIdentifier": "66f0b1b5c1f7b7dc0ce30001",
8  "paymentDate": 1783189200000,
9  "pix": {
10    "qrcode": {
11      "emv": "0002010102122680...",
12      "png": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
13    }
14  }
15}

Códigos de retorno

CódigoSignificadoAção recomendada
200Cobrança encontrada.Atualizar a conciliação e o estado interno da cobrança.
401Token inválido.Renovar a sessão da API PIX com o acesso de integração correto.
417Cobrança não encontrada ou sem vínculo com o usuário autenticado.Confirmar o identificador informado e a titularidade da conta.

Fluxo após o pagamento

Depois da confirmação do PIX, a plataforma:

  1. valida o valor recebido;
  2. localiza a cobrança correspondente;
  3. vincula o pagamento ao customer indicado;
  4. atualiza o status da cobrança;
  5. disponibiliza a cobrança atualizada para consulta;
  6. segue o fluxo operacional de notificação previsto para a conta.