Docs
PTENES Site Criar conta

PagamentosCriar Pagamento

Criar Pagamento

POST/v1/paymenthttps://api.securitypag.com

Autenticação: Bearer · chave de API

Para criar um pagamento, utilize a rota v1/payment. Essa rota é compatível com pagamentos via cartão de crédito, boleto bancário e PIX.

Formato de endereço: Os campos de endereço são renderizados automaticamente com base no valor informado em country.

Se country = BR, será exibido o formato brasileiro com os campos: state, city, district, street, number, complement e zipCode.

Para outros países, será exibido automaticamente o formato internacional com os campos: state, city, line1, line2 e zipCode.

Dica: basta informar o país corretamente — os campos serão ajustados automaticamente.

Corpo da requisição

Enviado em JSON.

  • amountintegerobrigatório

    Valor total do pagamento em centavos. Exemplo: R$ 1,00.

  • currencystringobrigatório

    Moeda do pagamento (ex: BRL, USD, EUR).

  • methodstringobrigatório

    Método de pagamento (PIX, BOLETO, CREDIT_CARD).

  • descriptionstringobrigatório

    Descrição do pagamento.

  • externalRefstring

    Referência externa do pagamento.

  • notificationUrlstring

    URL para onde os webhooks do pagamento serão enviados.

  • ipstring

    Endereço IP do cliente.

  • payerobjectobrigatório4 campos

    Dados de quem está realizando o pagamento.

    • namestringobrigatório

      Nome completo do pagador.

    • taxIdstringobrigatório

      Documento do pagador.

    • emailstring

      E-mail do pagador.

    • phonestring

      Telefone do pagador. Pode ser obrigatório em algumas operadoras.

  • itemsarray of objectsobrigatório4 campos

    Lista de produtos que compõem o pagamento.

    • quantityintegerobrigatório

      Quantidade do produto. Deve ser maior que zero.

    • namestringobrigatório

      Nome do produto.

    • priceintegerobrigatório

      Valor unitário do produto em centavos. Ex: 100 = R$ 1,00.

    • typestringobrigatório

      Tipo do produto [DIGITAL, PHYSICAL].

  • deliveryobject2 campos

    Entrega do pedido, obrigatório caso o produto seja do tipo PHYSICAL

    • feeintegerobrigatório

      Taxa de entrega do pedido em centavos (este valor não é adicionado ao amount). Exemplo: R$ 1,00.

    • addressobjectobrigatório8 campos

      Endereço de entrega. O formato do endereço depende do país informado. Se country = BR utilize o formato brasileiro (district, street, number). Para outros países utilize o formato internacional (line1, line2).

      • countrystringobrigatório

        Código do país no padrão ISO 3166-1 alpha-2 (ex: BR, US).

      • statestringobrigatório

        Estado ou província (ex: SP, CA, NY). Obrigatório quando country = BR.

      • citystringobrigatório

        Cidade. Obrigatório quando country = BR.

      • districtstringobrigatório

        Bairro. Obrigatório quando country = BR.

      • streetstringobrigatório

        Nome da rua ou logradouro. Obrigatório quando country = BR.

      • numberstringobrigatório

        Número do endereço. Obrigatório quando country = BR.

      • complementstring

        Complemento do endereço (apartamento, bloco, unidade, etc).

      • zipCodestringobrigatório

        CEP ou código postal.

  • splitsarray of strings

    Lista de IDs de splits. Exemplo: ["split_id_1", "split_id_2"].

  • cardobject3 campos

    Dados do cartão de crédito caso seja method = CREDIT_CARD.

    • tokenstringobrigatório

      Token do cartão.

    • installmentsintegerobrigatório

      Número de parcelas (1 a 12).

    • billingAddressobject8 campos

      Endereço de cobrança.

      • countrystringobrigatório

        Código do país no padrão ISO 3166-1 alpha-2 (ex: BR, US).

      • statestringobrigatório

        Estado ou província (ex: SP, CA, NY). Obrigatório quando country = BR.

      • citystringobrigatório

        Cidade. Obrigatório quando country = BR.

      • districtstringobrigatório

        Bairro. Obrigatório quando country = BR.

      • streetstringobrigatório

        Nome da rua ou logradouro. Obrigatório quando country = BR.

      • numberstringobrigatório

        Número do endereço. Obrigatório quando country = BR.

      • complementstring

        Complemento do endereço (apartamento, bloco, unidade, etc).

      • zipCodestringobrigatório

        CEP ou código postal.

  • boletoobject1 campos

    Dados obrigatórios caso seja method = BOLETO.

    • billingAddressobject8 campos

      O formato do endereço depende do país informado. Se country = BR utilize o formato brasileiro (district, street, number). Para outros países utilize o formato internacional (line1, line2).

      • countrystringobrigatório

        Código do país no padrão ISO 3166-1 alpha-2 (ex: BR, US).

      • statestringobrigatório

        Estado ou província (ex: SP, CA, NY). Obrigatório quando country = BR.

      • citystringobrigatório

        Cidade. Obrigatório quando country = BR.

      • districtstringobrigatório

        Bairro. Obrigatório quando country = BR.

      • streetstringobrigatório

        Nome da rua ou logradouro. Obrigatório quando country = BR.

      • numberstringobrigatório

        Número do endereço. Obrigatório quando country = BR.

      • complementstring

        Complemento do endereço (apartamento, bloco, unidade, etc).

      • zipCodestringobrigatório

        CEP ou código postal.

  • metadataobject9 campos

    Metadados do pagamento utilizados para rastreabilidade e controle.

    • providerstringobrigatório

      Identificador da origem responsável pela criação do pagamento, como checkout, aplicativo, painel administrativo ou integração externa.

    • orderIdstringobrigatório

      Identificador único do pedido no sistema.

    • sellerTaxIdstringobrigatório

      Documento fiscal do vendedor recebedor do pagamento.

    • sellerEmailstringobrigatório

      E-mail do vendedor recebedor do pagamento.

    • checkoutUrlstring

      URL do checkout onde o pagamento foi iniciado.

    • returnUrlstring

      URL de redirecionamento após o fluxo de pagamento.

    • shopUrlstring

      Página de venda ou oferta que originou a intenção de compra.

    • referrerLinkstring

      URL de origem imediata do acesso do usuário antes de chegar à página de venda.

    • extrastring

      Campo livre para armazenamento de metadados adicionais.

  • utmsobject7 campos

    Parâmetros UTM de origem do tráfego que gerou o pagamento.

    • utmSourcestring

      Origem do tráfego que gerou o acesso, como google, facebook ou newsletter.

    • utmMediumstring

      Meio ou canal utilizado pela campanha, como cpc, email ou social.

    • utmCampaignstring

      Nome da campanha responsável pelo acesso, como black-friday-2026.

    • utmContentstring

      Variação do anúncio ou criativo que originou o acesso.

    • utmTermstring

      Palavra-chave associada ao anúncio ou à busca que originou o acesso.

    • srcstring

      Código de origem do tráfego, repassado na URL como src. Usado para identificar a origem do clique.

    • sckstring

      Código secundário de rastreio, repassado na URL como sck. Usado para segmentar a origem dentro da campanha.

Respostas

200Objeto de resposta retornado em caso de sucesso na criação ou consulta do pagamento.
  • idstring

    Identificador único do pagamento no sistema.

  • amountintegerpadrão: 0

    Valor total do pagamento em centavos.

  • methodstring

    Método de pagamento utilizado (PIX, CREDIT_CARD, BOLETO).

  • currencystring

    Código da moeda utilizada no pagamento (ex: BRL).

  • statusstring

    Status atual do pagamento (ex: PENDING, PROCESSING, PAID, REFUSED, REFUNDED, MED, CHARGEDBACK).

  • descriptionstring

    Descrição do pagamento.

  • installmentsintegerpadrão: 1

    Número de parcelas do pagamento.

  • payerobject4 campos

    Dados do pagador.

    • namestring

      Nome completo do pagador.

    • taxIdstring

      Documento do pagador.

    • emailstring

      E-mail do pagador.

    • phonestring

      Telefone do pagador, incluindo DDD.

  • externalRefstring

    Referência externa do pagamento atribuída pelo integrador.

  • orderIdstring

    Identificador do pedido no sistema do integrador.

  • notificationUrlstring

    URL configurada para recebimento de notificações (webhooks).

  • paidAtstring

    Data e hora em que a transação foi paga.

  • refundedAtstring

    Data e hora do reembolso do pagamento, quando aplicável.

  • createdAtstring

    Data e hora de criação do pagamento.

  • updatedAtstring

    Data e hora da última atualização do pagamento.

  • dataobject8 campos

    Dados específicos do método de pagamento.

    • methodstring

      Método de pagamento relacionado aos dados retornados.

    • copypastestring

      Código Pix copia e cola (quando o método for PIX).

    • messagestring

      Mensagem de retorno da operadora do cartão.

    • cardHolderstring

      Nome impresso no cartão.

    • cardNumberstring

      Número do cartão mascarado.

    • cardExpMonthstring

      Mês de expiração do cartão.

    • cardExpYearstring

      Ano de expiração do cartão.

    • barcodestring

      Código de barras do boleto.

  • splitsarray of objects5 campos

    Configuração de split de pagamento.

    • amountintegerpadrão: 0

      Valor destinado ao recebedor do split em centavos.

    • currencystring

      Moeda do split.

    • percentinteger

      Percentual do split (ex: 100 = 100%).

    • storeIdstring

      Identificador da loja ou recebedor.

    • splitIdstring

      Identificador do split, quando existente.

  • itemsarray of objects4 campos

    Lista de produtos que compõem o pagamento.

    • quantityinteger

      Quantidade do produto. Deve ser maior que zero.

    • namestring

      Nome do produto.

    • priceinteger

      Valor unitário do produto em centavos. Ex: 100 = R$ 1,00.

    • typestring

      Tipo do produto [DIGITAL, PHYSICAL].

  • metadataobject9 campos

    Metadados do pagamento utilizados para rastreabilidade e controle.

    • providerstring

      Identificador da origem responsável pela criação do pagamento.

    • orderIdstring

      Identificador único do pedido no sistema.

    • sellerTaxIdstring

      Documento fiscal do vendedor recebedor do pagamento.

    • sellerEmailstring

      E-mail do vendedor recebedor do pagamento.

    • checkoutUrlstring

      URL do checkout onde o pagamento foi iniciado.

    • returnUrlstring

      URL para redirecionamento do usuário após o fluxo de pagamento.

    • shopUrlstring

      Página de venda ou oferta que originou a intenção de compra.

    • referrerLinkstring

      URL de origem imediata do acesso do usuário.

    • extrastring

      Campo livre para armazenamento de metadados adicionais.

  • utmsobject7 campos

    Parâmetros UTM de origem do tráfego associados ao pagamento.

    • utmSourcestring

      Origem do tráfego que gerou o acesso.

    • utmMediumstring

      Meio ou canal utilizado pela campanha.

    • utmCampaignstring

      Nome da campanha responsável pelo acesso.

    • utmContentstring

      Variação do anúncio ou criativo que originou o acesso.

    • utmTermstring

      Palavra-chave associada ao anúncio ou à busca que originou o acesso.

    • srcstring

      Código de origem do tráfego (parâmetro src) repassado na URL.

    • sckstring

      Código secundário de rastreio (parâmetro sck) repassado na URL.

400Objeto de resposta retornado quando a requisição contém dados inválidos.

Algo errado nesta página? Fale com o time