Skip to main content

Integração Payments

Teste requisições assinadas no navegador no Sandbox da API — cole sua API key e secret, e o playground assina as requisições automaticamente.
Os exemplos abaixo mostram o header no formato wire Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. Para computar a assinatura no seu código, use o helper signedRequest em Autenticação.
A integração Payments é uma API REST agnóstica de provedor para as operações financeiras essenciais que todo backoffice precisa:
  1. Emitir Invoice (cobrança)POST /payments/invoices. Uma Invoice aqui é uma cobrança — um pedido de pagamento coletado via PIX, boleto, cartão, ACH ou SEPA dependendo da região.
  2. Cancelar InvoicePOST /payments/invoices/{id}/cancel (anula cobrança não paga).
  3. Emitir documento fiscal (NFS-e/NF-e/PEPPOL)POST /payments/invoices/{id}/tax-documents. Opcional, específico por região (Brasil hoje, Europa depois). Pode também ser auto-emitido na criação da Invoice.
  4. Pagar beneficiário (prêmio ou qualquer payout)POST /payments/payouts.
  5. Ler o extrato bancárioGET /payments/balance-transactions.
Toda transação carrega campos de controle de primeira classe usados pelo seu time financeiro para reconciliação: cost_center (centro de custos) e contractor_reference (número do contratante) você envia no request; our_number (nosso número) é gerado pelo SalesOS e devolvido no response (e em todo lançamento do extrato). Por baixo, o SalesOS roteia a requisição para o provedor certo — você não precisa escolher provedor a menos que queira.
Cobrança ≠ documento fiscal. Uma Invoice é o pedido de pagamento (boleto, PIX, cartão). O documento fiscal (NFS-e no BR, PEPPOL na UE) é um recurso separado e opcional anexado à Invoice. Essa separação mantém a API portável entre BR / US / UE.
A API segue convenções de mercado: modelo REST por recurso, valores em unidades menores inteiras, timestamps ISO-8601, RFC 9457 Problem Details para erros, header Idempotency-Key para retry seguro, paginação por cursor e webhooks assinados. Se você já integrou com qualquer API moderna de pagamentos, vai se sentir em casa.

Roteamento por Região

O SalesOS escolhe o backend correto automaticamente a partir de customer.country e currency. Você não precisa escolher. Payouts roteiam pelo destino: BRL → PIX cashout; demais moedas → transferência internacional.

Como Funciona

  1. Você obtém uma Chave de API no Dashboard do SalesOS (Admin > Integrações > Chaves de API) com os escopos corretos (payments:write, payments:read).
  2. Você emite Invoices (cobranças). O SalesOS cria o pedido de pagamento na região do cliente (BR ativo; US/UE em breve). Você recebe um artefato pagável: QR-code/copia-e-cola PIX, código de barras de boleto, URL de checkout de cartão.
  3. (Opcional) Um documento fiscal é anexado. Quando currency = BRL e tax_document.auto_issue: true, o SalesOS emite uma NFS-e automaticamente após a cobrança ser confirmada como paga. Você também pode chamar POST /invoices/{id}/tax-documents mais tarde para emitir ou tentar de novo.
  4. Você paga beneficiários (colaboradores, parceiros, ganhadores de prêmios). O SalesOS roteia BRL via PIX e demais moedas via transferência internacional.
  5. Você lê um extrato unificado — toda cobrança, payout, taxa e fee de documento fiscal em um único livro-razão, filtrável por cost_center, our_number, contractor_reference, período e provedor.
  6. Você escuta webhooks para eventos terminais (invoice.paid, invoice.canceled, tax_document.issued, payout.paid, …) em vez de fazer polling.

Início Rápido

1

Obtenha sua Chave de API

Vá até Admin > Integrações > Chaves de API no Dashboard do SalesOS. Crie uma nova chave com os escopos payments:write e payments:read. Copie a chave — ela só será exibida uma vez.Sua chave terá este formato: sk_live_a1b2c3d4e5f6g7h8i9j0...
2

Emita sua primeira Invoice (BR — cobrança PIX com NFS-e automática)

Crie uma cobrança PIX para um cliente brasileiro. O bloco opcional tax_document instrui o SalesOS a emitir a NFS-e automaticamente após a cobrança ser paga.
Resposta (201 Created):
Status passa por openpaid (na confirmação PIX, ~segundos) → tax_document.status: issued (emissão da NFS-e, segundos a minutos). Escute os webhooks invoice.paid e tax_document.issued em vez de fazer polling.
3

(Opcional) Emita uma Invoice para cliente US (em breve)

Para clientes US/UE o SalesOS roteia a cobrança para o backend internacional. Esse caminho está aguardando o onboarding da Play2Sell LLC — chamadas hoje retornam 501 provider_not_configured.
Sem bloco tax_document — US não possui documento fiscal nacional. Sales tax vai dentro de metadata ou de futuros line_items. O SSN do cliente não é coletado neste endpoint: cobranças B2C/B2B regulares nos EUA não exigem. Tratamento de SSN/EIN para reporting 1099 (quando você paga contractors US) é fluxo separado em Payouts, não em Invoices.
4

Pague um beneficiário

Pague um ganhador de prêmio via PIX (BRL — roteamento automático):
Resposta (201 Created):
Você receberá um webhook payout.paid em segundos no sandbox ou em menos de um minuto em produção (PIX).
5

Leia seu extrato

Liste todos os lançamentos com cost_center=CC-AWARDS no mês:
Resposta (200 OK):

Autenticação

Todas as requisições exigem uma Chave de API no header Authorization:
Consulte a página de Autenticação para detalhes sobre como criar e gerenciar Chaves de API.

Ambientes

URL Base: https://api.play2sell.comDashboard: https://dashboard.play2sell.com

Referência de Endpoints

Path base: /functions/v1/payments. Todos os endpoints aceitam e retornam JSON.

Invoices (Cobranças)

Uma Invoice é uma cobrança — um pedido de pagamento que será coletado do seu cliente via PIX, boleto, cartão ou outro método dependendo da região. A Invoice não inclui um documento fiscal por padrão; veja Tax Documents abaixo.

POST /functions/v1/payments/invoices — criar uma cobrança

object
obrigatório
Cliente que será cobrado.
string
obrigatório
ISO-3166-1 alpha-2 (BR, US, DE, …). Decide o roteamento de provedor.
string
CPF (11 dígitos) ou CNPJ (14 dígitos) para BR (obrigatório quando tax_document está presente). Para cobranças US/UE este campo não é obrigatório — deixe de fora a menos que seu fluxo contábil precise. SSN/EIN não são coletados aqui em cobranças normais.
string
obrigatório
Razão social ou nome completo (max 255 caracteres).
string
obrigatório
Email válido — usado para recibos e (quando aplicável) entrega do documento fiscal.
string
Telefone opcional (max 20 caracteres). Formato E.164 recomendado (ex.: +5511999000111). Alguns provedores usam para correspondência AML/KYC e notificações transacionais.
integer
obrigatório
Valor total em unidades menores (ex: 12345 = R$ 123,45). Deve ser positivo.
string
obrigatório
Código ISO-4217. Decide o roteamento de provedor junto com customer.country.
string
obrigatório
Descrição que aparece no artefato de pagamento e (quando emitido) na discriminação do documento fiscal (max 1000 caracteres).
O campo description é exibido ao pagador. Em cobranças PIX aparece no app bancário/carteira do pagador junto ao QR-code; em boleto vai impresso no documento; em NFS-e entra na discriminação do serviço. Escolha um valor que faça sentido nos três contextos (ex: "Consultoria — Abril/2026", não "INV-2026-000123 linha-billing-interna").
object
obrigatório
Como a cobrança será coletada.
string
obrigatório
Um de pix, boleto, bolepix, card (BR); card, ach_debit, bank_transfer (US — em breve); card, sepa_debit, bank_transfer (UE — em breve).
integer
Para pix / boleto / bolepix: por quanto tempo o artefato de pagamento permanece válido. Padrão 3600 (PIX) / 3 dias (boleto).
string
Para card: para onde redirecionar o cliente após o checkout do cartão.
object
Opcional. Quando presente, o SalesOS emitirá um documento fiscal automaticamente após a cobrança ser paga. Hoje apenas BR.
boolean
Quando true, o documento fiscal é emitido no momento em que a cobrança transita para paid. Quando false (ou ausente), use POST /v1/invoices/{id}/tax-documents mais tarde.
string
"nfse" (serviços BR — ativo), "nfe" (produtos BR — em breve), "peppol" (UE — em breve).
string
Código municipal de serviço, obrigatório quando type="nfse" (ex: "01.05" para consultoria em SP).
string
Código do centro de custos interno (max 64 caracteres). Opcional — quando omitido, a cobrança é classificada no centro de custos padrão do tenant. Enviar um código não cadastrado retorna 422 unknown_cost_center. Veja Campos de Controle Comuns.
string
Número do contratante — referência externa do cliente/contrato (max 64 caracteres).
object
Pares chave-valor livres (max 50 chaves, valor max 500 caracteres).
our_number (nosso número) não vai no request — o SalesOS gera no momento da emissão e devolve no response (formato: INV-<AAAA>-<sequência>). Armazene para reconciliação.

GET /functions/v1/payments/invoices/{id} — consultar

A resposta sempre inclui o artefato corrente de payment_method (QR PIX, código de barras de boleto, URL de checkout de cartão) e o resumo inline de tax_document quando presente.

GET /functions/v1/payments/invoices — listar

Filtros: status (open|paid|canceled|failed), payment_method.type, cost_center, our_number, contractor_reference, created[gte], created[lte]. Paginação por cursor via limit (≤ 100), starting_after, ending_before.

POST /functions/v1/payments/invoices/{id}/cancel — anular cobrança não paga

Se a Invoice tiver um tax_document anexado já em estado issued, o cancelamento é cascateado para o documento fiscal quando o município ainda está dentro da janela de cancelamento. Caso contrário, retorna cancellation_window_expired.
Estorno de cobrança paga não está exposto na v1. Se você precisa reverter um pagamento já liquidado, fale com o suporte — o time pode processar manualmente. Uma versão futura da API pode expor um fluxo de estorno programático conforme os casos de uso amadurecerem.

Tax Documents (Documentos Fiscais)

Um TaxDocument é o artefato fiscal anexado a uma Invoice — hoje NFS-e (serviços BR). Tem ciclo de vida próprio e pode ser emitido, consultado ou cancelado independentemente da cobrança subjacente. Use este recurso quando você optou por não usar auto_issue na criação da Invoice, quando uma tentativa de auto-emissão falhou e você quer retentar, ou quando precisa cancelar apenas o documento fiscal.

POST /functions/v1/payments/invoices/{id}/tax-documents — emitir/retentar

string
obrigatório
"nfse" hoje. Futuro: "nfe", "peppol".
string
Obrigatório quando type="nfse".
object
Metadata livre opcional, persistido no documento.
Resposta (202 Accepted):
A emissão é assíncrona. Escute os webhooks tax_document.issued (ou tax_document.failed). Em sucesso o documento traz document_number, xml_url, pdf_url e issued_at.

GET /functions/v1/payments/invoices/{id}/tax-documents/{doc_id} — consultar

POST /functions/v1/payments/invoices/{id}/tax-documents/{doc_id}/cancel — cancelar

Sujeito à janela de cancelamento do município (tipicamente o dia da emissão para NFS-e). cancellation_window_expired é retornado quando fora da janela.

Payouts (Pagamentos a Beneficiários)

POST /functions/v1/payments/payouts — pagar beneficiário

Roteamento automático: currency = "BRL" → PIX cashout; demais moedas → transferência internacional.
object
obrigatório
Destinatário do pagamento.
string
obrigatório
Nome completo ou razão social (max 255 caracteres).
string
obrigatório
Documento de identificação fiscal do beneficiário. CPF (11 dígitos) ou CNPJ (14 dígitos) para BR; passaporte ou identificador fiscal local para internacional. Obrigatório.
string
obrigatório
Telefone em formato E.164 (ex: "+5511999000111"). Obrigatório — usado para AML/KYC e notificações de status do payout.
string
Email opcional. Quando informado, recibos do payout são enviados para este endereço.
object
obrigatório
Conta destino. Para PIX, use type: "pix" com key_type (cpf|cnpj|email|phone|evp) e key. Para internacional, use type: "bank_transfer" com country, iban ou account_number + routing_number conforme exigências bancárias do país de destino.
integer
obrigatório
Valor em unidades menores. Deve ser positivo.
string
obrigatório
ISO-4217. Determina o roteamento de provedor.
string
obrigatório
Um de "prize", "commission", "vendor_payment", "other".
string
Código do centro de custos (max 64 caracteres). Opcional — quando omitido, o payout é classificado no centro de custos padrão do tenant. Enviar um código não cadastrado retorna 422 unknown_cost_center.
string
Número do contratante — referência externa (max 64 caracteres).
object
Pares chave-valor livres (max 50 chaves, valor max 500 caracteres).
our_number (nosso número) não vai no request — o SalesOS gera no momento da emissão e devolve no response (formato: PO-<AAAA>-<sequência>). Armazene para reconciliação.

GET /functions/v1/payments/payouts/{id} — consultar

GET /functions/v1/payments/payouts — listar

Filtros: status, provider, cost_center, our_number, contractor_reference, created[gte], created[lte]. Paginação por cursor.

POST /functions/v1/payments/payouts/{id}/cancel — cancelar

Disponível apenas para transferências internacionais nos estados created / incoming_payment_waiting. PIX é síncrono e final — uma vez aceito, não é cancelável; emita um payout no sentido oposto para compensar.

Balance Transactions (Extrato Bancário)

Livro-razão unificado entre provedores. Somente leitura.

GET /functions/v1/payments/balance-transactions — listar

Filtros:

GET /functions/v1/payments/balance-transactions/{id} — consultar

Cada lançamento expõe:
string
ID estável do lançamento (btxn_...).
string
charge | payout | fee | adjustment.
integer
Valor em unidades menores, com sinal. Negativo = saída, positivo = entrada.
string
ISO-4217.
integer
amount - fee para saídas; amount para entradas.
integer
Taxa do provedor em unidades menores, sempre positiva.
string
Data ISO-8601 de liquidação dos fundos.
string
Timestamp ISO-8601 do lançamento.
object
{ resource, id } — aponta para a nota/payout de origem.
string
Herdado do recurso de origem.
string
Herdado do recurso de origem.
string
Herdado do recurso de origem.

Campos de Controle Comuns

Toda Invoice, Payout e Balance Transaction carrega os mesmos campos de controle. Eles fazem round-trip em GET e são filtráveis em LIST.
Por que our_number é gerado no servidor. No banking brasileiro o cedente atribui o “nosso número” — mas nesta API o SalesOS é o gateway de emissão, então é o SalesOS que atribui o valor e devolve. Se você precisar carregar um identificador interno seu, use contractor_reference (top-level, indexado) ou metadata.* (livre).

Idempotência

Todos os endpoints POST exigem o header Idempotency-Key — uma string única à sua escolha (max 255 caracteres; recomendamos UUIDv4 ou uma chave determinística baseada no seu domínio).
  • A primeira chamada com a chave processa normalmente e a resposta é armazenada por 24 h.
  • Replays com a mesma chave e o mesmo body retornam a mesma resposta, com header Idempotent-Replay: true.
  • Replays com a mesma chave mas body diferente retornam 409 idempotency_key_reused.

Valores e Moeda

Valores são inteiros em unidades menores para evitar erros de ponto flutuante: Moedas seguem ISO-4217 (3 letras maiúsculas). Sempre pareie amount com currency. Rejeite no servidor qualquer payload que misture escalas (ex: enviar decimais).

Tratamento de Erros

Todos os erros seguem RFC 9457 Problem Details:
JSON malformado ou headers obrigatórios ausentes. Corrija a requisição e reenvie.
Chave de API ausente, inválida ou expirada. Verifique o header Authorization. Gere uma nova chave se expirada.
Chave válida mas sem o escopo necessário (payments:write ou payments:read). Edite a chave no Dashboard.
O ID do recurso não existe ou pertence a outro tenant.
Mesma Idempotency-Key usada com body diferente. Use uma chave nova ou envie o body original.
A requisição foi entendida mas não pode ser processada. Inspecione o campo code para desambiguar:
  • validation_error — validação do body falhou; o array errors[] lista os problemas a nível de campo. Corrija os dados e reenvie com Idempotency-Key nova.
  • unsupported_region — a combinação country / currency do cliente ainda não está disponível (hoje apenas BR / BRL está ativo). Aguarde a região ser liberada ou cobre um cliente em uma região suportada.
  • unknown_cost_center — o código cost_center enviado não está cadastrado para o seu tenant. Cadastre-o em Admin > Integrações > Centros de Custo antes de reenviar, ou omita o campo para usar o centro de custo padrão do tenant.
  • merchant_not_provisioned — o seu tenant não tem um merchant de pagamento ativo para o centro de custo resolvido. Contate o suporte para concluir o provisionamento antes de tentar novamente.
Muitas requisições. O header Retry-After indica quantos segundos aguardar.
O backend downstream retornou erro. O campo detail contém uma mensagem sanitizada. Reenvie com a mesma Idempotency-Key.
Erro interno. Reenvie com backoff exponencial (2s, 4s, 8s). Contate o suporte se persistir.

Webhooks

Configure um endpoint de webhook por ambiente em Admin > Integrações > Webhooks. O SalesOS fará POST com JSON assinado para todo evento terminal: Cada requisição inclui:
  • X-Pay-Event — tipo do evento (ex: payout.paid).
  • X-Pay-Signaturet=<unix>,v1=<hex-hmac-sha256>. Verifique com o segredo configurado no Dashboard.
  • X-Pay-Delivery — ID único de entrega, útil para deduplicação.
Verificação de assinatura (Node.js):
Payload de exemplo:

Exemplos Completos de Código


Boas Práticas

Higiene de centros de custo

Escolha um conjunto pequeno e estável de códigos (≤ 50). Documente no wiki do financeiro. Rejeite no servidor chamadas que referenciem código desconhecido — falhar alto é melhor que classificar errado em silêncio.

Use as duas chaves juntas para reconciliação

  • our_number (gerado pelo servidor) é sua chave bancária — impressa no boleto / enviada ao provedor, presente no arquivo do extrato bancário.
  • contractor_reference (você fornece) é sua chave de contrato — o PO, ID do contrato com fornecedor ou ID do evento referente; presente no seu ERP.
Cruzar as duas no fechamento mensal entrega reconciliação de 1 clique entre o banco, a API Payments do SalesOS e seu ERP.

Roteamento por região

O SalesOS roteia automaticamente por customer.country e currency. Você não precisa escolher backend; confie no roteamento.

Confiabilidade dos webhooks

Trate webhooks como fonte de verdade para status terminal. Polling funciona mas consome rate limit. Sempre verifique X-Pay-Signature e dedupe por X-Pay-Delivery.

Tratamento de falhas

  • 422: corrija os dados e reenvie com Idempotency-Key nova.
  • 429: aguarde conforme Retry-After.
  • 502 (provider_error): reenvie com a mesma Idempotency-Key — a requisição original não foi commit, então retry é seguro.
  • 5xx: backoff exponencial (2s, 4s, 8s). Contate o suporte se persistir.

Limites de Requisições

Cada chave de API possui um limite configurável (padrão: 1000 requisições por hora). O contador reinicia a cada hora. Respostas com rate limit incluem o header Retry-After (segundos).

Segurança

  • Chaves de API são hasheadas com bcrypt — nunca armazenadas em texto puro.
  • Cada chave é restrita a um único tenant — sem acesso entre tenants.
  • Listas de IPs permitidos podem ser configuradas por chave.
  • Todas as requisições são registradas em log para auditoria (imutável, retenção de 7 anos).
  • As chaves podem ser revogadas instantaneamente pelo Dashboard.
Nunca exponha sua chave de API em código client-side (JavaScript no navegador, apps mobile ou repositórios públicos). A API Payments deve ser chamada apenas do seu servidor backend.

Próximos Passos

Autenticação

Saiba como criar e gerenciar Chaves de API

Integração Activities

Envie atividades do CRM para o SalesOS

Suporte

Precisa de ajuda? Entre em contato com nosso time de suporte