Integração Payments
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.- 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. - Cancelar Invoice —
POST /payments/invoices/{id}/cancel(anula cobrança não paga). - 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. - Pagar beneficiário (prêmio ou qualquer payout) —
POST /payments/payouts. - Ler o extrato bancário —
GET /payments/balance-transactions.
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 decustomer.country e currency. Você não precisa escolher.
Payouts roteiam pelo destino: BRL → PIX cashout; demais moedas → transferência internacional.
Como Funciona
- 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). - 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.
- (Opcional) Um documento fiscal é anexado. Quando
currency = BRLetax_document.auto_issue: true, o SalesOS emite uma NFS-e automaticamente após a cobrança ser confirmada como paga. Você também pode chamarPOST /invoices/{id}/tax-documentsmais tarde para emitir ou tentar de novo. - Você paga beneficiários (colaboradores, parceiros, ganhadores de prêmios). O SalesOS roteia BRL via PIX e demais moedas via transferência internacional.
- 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. - 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 Resposta (201 Created):Status passa por
tax_document instrui o SalesOS a emitir a NFS-e automaticamente após a cobrança ser paga.open → paid (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 Sem bloco
501 provider_not_configured.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 Resposta (200 OK):
cost_center=CC-AWARDS no mês:Autenticação
Todas as requisições exigem uma Chave de API no headerAuthorization:
Ambientes
- Production
- Staging
URL Base:
https://api.play2sell.comDashboard: https://dashboard.play2sell.comReferê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
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
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 usarauto_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.
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
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 emGET 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 endpointsPOST 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:400 — bad_request
400 — bad_request
JSON malformado ou headers obrigatórios ausentes. Corrija a requisição e reenvie.
403 — insufficient_scope
403 — insufficient_scope
Chave válida mas sem o escopo necessário (
payments:write ou payments:read). Edite a chave no Dashboard.404 — not_found
404 — not_found
O ID do recurso não existe ou pertence a outro tenant.
409 — idempotency_key_reused
409 — idempotency_key_reused
Mesma
Idempotency-Key usada com body diferente. Use uma chave nova ou envie o body original.422 — validation_error e relacionados
422 — validation_error e relacionados
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 arrayerrors[]lista os problemas a nível de campo. Corrija os dados e reenvie comIdempotency-Keynova.unsupported_region— a combinaçãocountry/currencydo cliente ainda não está disponível (hoje apenasBR/BRLestá ativo). Aguarde a região ser liberada ou cobre um cliente em uma região suportada.unknown_cost_center— o códigocost_centerenviado 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.
429 — rate_limited
429 — rate_limited
Muitas requisições. O header
Retry-After indica quantos segundos aguardar.502 — provider_error
502 — provider_error
O backend downstream retornou erro. O campo
detail contém uma mensagem sanitizada. Reenvie com a mesma Idempotency-Key.500 — server_error
500 — server_error
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-Signature—t=<unix>,v1=<hex-hmac-sha256>. Verifique com o segredo configurado no Dashboard.X-Pay-Delivery— ID único de entrega, útil para deduplicação.
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.
Roteamento por região
O SalesOS roteia automaticamente porcustomer.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 verifiqueX-Pay-Signature e dedupe por X-Pay-Delivery.
Tratamento de falhas
- 422: corrija os dados e reenvie com
Idempotency-Keynova. - 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.
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

