{"openapi":"3.2.0","info":{"title":"API U2D Pay","description":"Cobranças Pix, cartão e boleto pela API pública da U2D Pay.","version":"v1"},"servers":[{"url":"https://api.u2dpay.com.br","description":"Produção"},{"url":"https://api-sandbox.u2dpay.com.br","description":"Sandbox"}],"security":[{"oauth2":[]}],"tags":[{"name":"Cobranças","description":"Cobranças avulsas por Pix, cartão e boleto."}],"paths":{"/payments":{"get":{"tags":["Cobranças"],"summary":"Listar cobranças","description":"Lista as cobranças do lojista do token, com filtros, paginação e ordenação.","operationId":"listPayments","parameters":[{"name":"status","in":"query","description":"Status da cobrança; repita o parâmetro para mais de um","required":false,"schema":{"type":"array","items":{"type":"string","enum":["CREATING","PENDING","OVERDUE","CONFIRMED","RECEIVED","REFUNDING","CHARGEBACK","REFUNDED","CANCELED"]}},"example":"PENDING"},{"name":"billingType","in":"query","description":"Forma de pagamento; repita o parâmetro para mais de uma","required":false,"schema":{"type":"array","items":{"type":"string","enum":["PIX","CREDIT_CARD","DEBIT_CARD","BOLETO","UNDEFINED"]}},"example":"PIX"},{"name":"payerDocument","in":"query","description":"CPF (11) ou CNPJ (14) do pagador, só dígitos","required":false,"schema":{"type":"string","pattern":"\\d{11}|\\d{14}"},"example":12345678901},{"name":"dueDateFrom","in":"query","description":"Vencimento a partir desta data (inclusive)","required":false,"schema":{"type":"string","format":"date"},"example":"2030-01-01"},{"name":"dueDateTo","in":"query","description":"Vencimento até esta data (inclusive)","required":false,"schema":{"type":"string","format":"date"},"example":"2030-01-31"},{"name":"paidOnFrom","in":"query","description":"Pagas a partir desta data, horário de Brasília (inclusive)","required":false,"schema":{"type":"string","format":"date"},"example":"2030-01-01"},{"name":"paidOnTo","in":"query","description":"Pagas até esta data, horário de Brasília (inclusive)","required":false,"schema":{"type":"string","format":"date"},"example":"2030-01-31"},{"name":"createdFrom","in":"query","description":"Criadas a partir deste instante (inclusive), ISO-8601","required":false,"schema":{"type":"string","format":"date-time"},"example":"2030-01-01T00:00:00Z"},{"name":"createdTo","in":"query","description":"Criadas antes deste instante (exclusivo), ISO-8601","required":false,"schema":{"type":"string","format":"date-time"},"example":"2030-02-01T00:00:00Z"},{"name":"page","in":"query","description":"Página, a partir de 0; padrão 0","required":false,"schema":{"type":"integer","format":"int32","minimum":0},"example":0},{"name":"size","in":"query","description":"Itens por página, de 1 a 100; padrão 20","required":false,"schema":{"type":"integer","format":"int32","maximum":100,"minimum":1},"example":20},{"name":"sort","in":"query","description":"Campo (createdAt, dueDate, paidOn, amount) e direção (asc, desc); padrão createdAt,desc","required":false,"schema":{"type":"string","pattern":"(createdAt|dueDate|paidOn|amount)(,(asc|desc))?"},"example":"dueDate,asc"}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PageResponsePaymentResponse"}}}}}},"post":{"tags":["Cobranças"],"summary":"Criar cobrança","description":"Cria uma cobrança para o pagador. Um retry com a mesma Idempotency-Key devolve a cobrança já criada, sem cobrar de novo.","operationId":"createPayment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}}}}}},"components":{"schemas":{"AddressRequest":{"type":"object","properties":{"street":{"type":"string","example":"Avenida Paulista","maxLength":255,"minLength":0},"number":{"type":"string","example":"1000","maxLength":20,"minLength":0},"complement":{"type":"string","example":"Sala 12","maxLength":100,"minLength":0},"district":{"type":"string","example":"Bela Vista","maxLength":100,"minLength":0},"city":{"type":"string","example":"São Paulo","maxLength":100,"minLength":0},"state":{"type":"string","description":"UF","example":"SP","minLength":1,"pattern":"[A-Z]{2}"},"postalCode":{"type":"string","description":"CEP, só dígitos","example":"01310100","minLength":1,"pattern":"\\d{8}"}},"required":["city","district","number","postalCode","state","street"]},"CreatePaymentRequest":{"type":"object","properties":{"payer":{"$ref":"#/components/schemas/PayerRequest"},"amount":{"type":"number","description":"Valor em reais, decimal com ponto","example":49.9,"minimum":0},"dueDate":{"type":"string","format":"date","description":"Vencimento em ISO-8601 (AAAA-MM-DD), hoje ou no futuro","example":"2030-01-15"},"billingType":{"type":"string","description":"Opcional; sem valor, o pagador escolhe a forma de pagamento no checkout","enum":["PIX","CREDIT_CARD","DEBIT_CARD","BOLETO","UNDEFINED"],"example":"PIX"},"description":{"type":"string","example":"Pedido 1234","maxLength":500,"minLength":0},"pixExpiresInMinutes":{"type":"integer","format":"int32","description":"Opcional, só com billingType PIX: validade do QR Code em minutos, contada da criação e limitada ao fim do dueDate (horário de Brasília). Sem valor, vale o padrão da U2D (24h). Vencida, a cobrança deixa de ser pagável","example":30,"maximum":43200,"minimum":1}},"required":["amount","dueDate","payer"]},"PayerRequest":{"type":"object","properties":{"name":{"type":"string","example":"Maria Silva","maxLength":255,"minLength":0},"document":{"type":"string","description":"CPF ou CNPJ, só dígitos","example":"24971563792","minLength":1,"pattern":"\\d{11}|\\d{14}"},"email":{"type":"string","format":"email","example":"maria@example.com","maxLength":255,"minLength":0},"phone":{"type":"string","description":"Opcional; celular ou fixo com DDD, só dígitos","example":"11987654321","pattern":"\\d{10,11}"},"address":{"$ref":"#/components/schemas/AddressRequest","description":"Opcional; endereço do pagador"}},"required":["document","name"]},"PaymentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["CREATING","PENDING","OVERDUE","CONFIRMED","RECEIVED","REFUNDING","CHARGEBACK","REFUNDED","CANCELED"]},"billingType":{"type":"string","enum":["PIX","CREDIT_CARD","DEBIT_CARD","BOLETO","UNDEFINED"]},"amount":{"type":"number"},"dueDate":{"type":"string","format":"date"},"description":{"type":"string"},"invoiceUrl":{"type":"string","description":"Página de pagamento do provedor. Em Pix, prefira checkoutUrl: o conteúdo de invoiceUrl varia (página, imagem do QR Code ou nulo)","example":"https://www.asaas.com/i/080225913252"},"checkoutUrl":{"type":"string","description":"Checkout U2D da cobrança, para enviar ao pagador; nulo fora de billingType PIX","example":"https://checkout.u2dpay.com.br/c/Xb3kq9Lr2Vw8Yt5Nc1Hp7Jd4Fs6Gm0Az2Qe9Wu3Ri5O"},"fee":{"type":"number","description":"Taxa da U2D sobre amount, em reais, pelo preço vigente na criação; nula se não houver preço configurado para a forma de pagamento","example":0.74},"paidAmount":{"type":"number","description":"Valor efetivamente pago; nulo enquanto não pago. Pode diferir de amount por juros, multa ou desconto","example":49.9},"netAmount":{"type":"number","description":"Valor líquido, depois das tarifas do provedor; nulo enquanto não pago","example":48.91},"paidOn":{"type":"string","format":"date","description":"Data do pagamento (horário de Brasília); nula enquanto não pago","example":"2030-01-15"},"pix":{"$ref":"#/components/schemas/PixResponse","description":"Pix da cobrança; nulo fora de billingType PIX ou se o QR Code não pôde ser obtido"},"createdAt":{"type":"string","format":"date-time","description":"Criação da cobrança; é o campo da ordenação padrão da listagem","example":"2030-01-10T14:32:05Z"}}},"PixResponse":{"type":"object","properties":{"copyPaste":{"type":"string","description":"Copia-e-cola (BR Code) do Pix; o QR Code é gerado a partir dele","example":"00020101021226820014br.gov.bcb.pix..."},"expiresAt":{"type":"string","format":"date-time","description":"Fim da validade do QR Code; nulo se o provedor não a informar","example":"2030-01-16T02:59:59Z"}}},"PageMetadata":{"type":"object","properties":{"number":{"type":"integer","format":"int32","description":"Página atual, a partir de 0","example":0},"size":{"type":"integer","format":"int32","description":"Itens por página pedidos","example":20},"totalElements":{"type":"integer","format":"int64","description":"Total de itens que atendem aos filtros","example":57},"totalPages":{"type":"integer","format":"int32","description":"Total de páginas","example":3}}},"PageResponsePaymentResponse":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/PaymentResponse"}},"page":{"$ref":"#/components/schemas/PageMetadata"}}}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"Token do Keycloak (client credentials), enviado como Authorization: Bearer.","flows":{"clientCredentials":{"tokenUrl":"https://auth.u2dtecnologia.com.br/realms/u2d-pay/protocol/openid-connect/token"}}}}}}