API legada/Referência completa/Formas de pagamento

Endpoints de formas de pagamento

As URLs /api/payments: a coleção (listar e criar) e uma forma de pagamento individual (consultar, atualizar e excluir), com os valores de status e os processadores.

A API de formas de pagamento gerencia as opções de processamento de pagamento da loja. Esta página lista as URLs sob $BASE_URL/api e os métodos HTTP que cada uma aceita. Toda requisição precisa das credenciais HTTP Basic de um administrador ($EMAIL:$API_KEY).

São duas URLs: /api/payments para a coleção inteira e /api/payments/{id} para uma forma de pagamento, em que {id} é o identificador único dela (um inteiro).

A coleção de pagamentos

O caminho /api/payments recupera todas as formas de pagamento ou cria uma nova.

Método	Descrição	Uso
GET	Recuperar todas as formas de pagamento	Devolve a lista de todas as formas de pagamento disponíveis
POST	Criar uma nova forma de pagamento	Exige um corpo JSON com os dados da forma de pagamento

Listar formas de pagamento

GET/api/paymentsAdmin

Recupera todas as formas de pagamento

Parâmetros de consulta

pageintegerpadrão: 1

Página da lista, veja Paginação.

items_per_pageintegerpadrão: 10

Quantidade de formas de pagamento por página.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments"

200Resposta da listagem

json

{
  "payments": [
    {
      "payment_id": 1,
      "payment_name": "Credit Card - Mastercard",
      "processor": "stripe",
      "min_order_amount": 10.00,
      "max_order_amount": 10000.00,
      "position": 10,
      "status": "A"
    },
    {
      "payment_id": 2,
      "payment_name": "Credit Card - Visa",
      "processor": "stripe",
      "min_order_amount": 10.00,
      "max_order_amount": 10000.00,
      "position": 20,
      "status": "A"
    },
    {
      "payment_id": 3,
      "payment_name": "Boleto Bancário",
      "processor": "pagseguro",
      "min_order_amount": 5.00,
      "max_order_amount": 5000.00,
      "position": 30,
      "status": "A"
    }
  ]
}

Criar uma forma de pagamento

POST/api/paymentsAdmin

Cria uma nova forma de pagamento

Corpo da requisição

payment_namestring

Nome da forma de pagamento.

processorstring

stripepagseguropaypalmercadopagocustom

O processador de pagamento.

processor_paramsobject

Configurações do processador. O exemplo envia api_key, currency e payment_method_types.

instructionsstring

Instruções exibidas ao cliente.

min_order_amountnumber

Menor valor de pedido para a forma de pagamento.

max_order_amountnumber

Maior valor de pedido para a forma de pagamento.

positioninteger

Posição na lista.

statusstring

AHD

Status da forma de pagamento, veja os valores de status abaixo.

iconstring

Nome do arquivo do ícone, como mastercard.png.

bash

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_name": "Credit Card - Mastercard",
  "processor": "stripe",
  "processor_params": {
    "api_key": "pk_test_TYooMQauvdEDq54NiTphI7jx",
    "currency": "BRL",
    "payment_method_types": ["card"]
  },
  "instructions": "Enter your credit card details to complete the payment",
  "min_order_amount": 10.00,
  "max_order_amount": 10000.00,
  "position": 10,
  "status": "A",
  "icon": "mastercard.png"
}'

Uma forma de pagamento

O caminho /api/payments/{id} trabalha com uma única forma de pagamento, identificada pelo ID.

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

Método	Descrição	Uso
GET	Recuperar uma forma de pagamento	Devolve as informações detalhadas da forma de pagamento indicada
PUT	Atualizar uma forma de pagamento	Exige um corpo JSON com os campos a atualizar
DELETE	Excluir uma forma de pagamento	Remove a forma de pagamento do sistema de forma permanente

Consultar uma forma de pagamento

Envie uma requisição GET para /api/payments/{id}. A resposta é a forma de pagamento completa:

GET/api/payments/{id}Admin

Recupera uma forma de pagamento

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments/1"

200Resposta do detalhe

json

{
  "payment_id": 1,
  "payment_name": "Credit Card - Mastercard",
  "processor": "stripe",
  "processor_params": {
    "api_key": "pk_live_TYooMQauvdEDq54NiTphI7jx",
    "currency": "BRL",
    "payment_method_types": ["card"]
  },
  "instructions": "Enter your Mastercard credit card details to complete the payment",
  "min_order_amount": 10.00,
  "max_order_amount": 10000.00,
  "position": 10,
  "status": "D",
  "icon": "mastercard.png",
  "last_modified": "2025-04-16T10:25:32Z"
}

Atualizar uma forma de pagamento

Envie uma requisição PUT para /api/payments/{id} somente com os campos que você quer alterar:

PUT/api/payments/{id}Admin

Atualiza uma forma de pagamento

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

Corpo da requisição

statusstring

AHD

Status da forma de pagamento.

processor_paramsobject

Configurações do processador.

instructionsstring

Instruções exibidas ao cliente.

bash

curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments/1" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "D",
  "processor_params": {
    "api_key": "pk_live_TYooMQauvdEDq54NiTphI7jx"
  },
  "instructions": "Enter your Mastercard credit card details to complete the payment"
}'

Excluir uma forma de pagamento

Envie uma requisição DELETE para /api/payments/{id}:

DELETE/api/payments/{id}Admin

Exclui uma forma de pagamento

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

bash

curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments/1"

Valores de status da forma de pagamento

Status	Descrição
`A`	Ativa: a forma de pagamento está disponível para o cliente escolher
`H`	Oculta: a forma de pagamento existe, mas não aparece para os clientes
`D`	Desativada: a forma de pagamento está temporariamente desativada

Processadores de pagamento aceitos

Processador	Descrição
`stripe`	Gateway de pagamento Stripe para processar cartões de crédito
`pagseguro`	Gateway de pagamento PagSeguro para as formas de pagamento brasileiras
`paypal`	Gateway de pagamento PayPal para contas PayPal
`mercadopago`	Gateway de pagamento Mercado Pago para as formas de pagamento da América Latina
`custom`	Forma de pagamento personalizada, para pagamentos offline ou processamento manual

Veja também

Formas de pagamento

O objeto de forma de pagamento da API 2.0 e suas rotas.

Paginação

Page e items_per_page na listagem.

API legada/Referência completa/Formas de pagamento

Endpoints de formas de pagamento

As URLs /api/payments: a coleção (listar e criar) e uma forma de pagamento individual (consultar, atualizar e excluir), com os valores de status e os processadores.

São duas URLs: /api/payments para a coleção inteira e /api/payments/{id} para uma forma de pagamento, em que {id} é o identificador único dela (um inteiro).

A coleção de pagamentos

O caminho /api/payments recupera todas as formas de pagamento ou cria uma nova.

Método	Descrição	Uso
GET	Recuperar todas as formas de pagamento	Devolve a lista de todas as formas de pagamento disponíveis
POST	Criar uma nova forma de pagamento	Exige um corpo JSON com os dados da forma de pagamento

Listar formas de pagamento

GET/api/paymentsAdmin

Recupera todas as formas de pagamento

Parâmetros de consulta

pageintegerpadrão: 1

Página da lista, veja Paginação.

items_per_pageintegerpadrão: 10

Quantidade de formas de pagamento por página.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments"

200Resposta da listagem

json

{
  "payments": [
    {
      "payment_id": 1,
      "payment_name": "Credit Card - Mastercard",
      "processor": "stripe",
      "min_order_amount": 10.00,
      "max_order_amount": 10000.00,
      "position": 10,
      "status": "A"
    },
    {
      "payment_id": 2,
      "payment_name": "Credit Card - Visa",
      "processor": "stripe",
      "min_order_amount": 10.00,
      "max_order_amount": 10000.00,
      "position": 20,
      "status": "A"
    },
    {
      "payment_id": 3,
      "payment_name": "Boleto Bancário",
      "processor": "pagseguro",
      "min_order_amount": 5.00,
      "max_order_amount": 5000.00,
      "position": 30,
      "status": "A"
    }
  ]
}

Criar uma forma de pagamento

POST/api/paymentsAdmin

Cria uma nova forma de pagamento

Corpo da requisição

payment_namestring

Nome da forma de pagamento.

processorstring

stripepagseguropaypalmercadopagocustom

O processador de pagamento.

processor_paramsobject

Configurações do processador. O exemplo envia api_key, currency e payment_method_types.

instructionsstring

Instruções exibidas ao cliente.

min_order_amountnumber

Menor valor de pedido para a forma de pagamento.

max_order_amountnumber

Maior valor de pedido para a forma de pagamento.

positioninteger

Posição na lista.

statusstring

AHD

Status da forma de pagamento, veja os valores de status abaixo.

iconstring

Nome do arquivo do ícone, como mastercard.png.

bash

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_name": "Credit Card - Mastercard",
  "processor": "stripe",
  "processor_params": {
    "api_key": "pk_test_TYooMQauvdEDq54NiTphI7jx",
    "currency": "BRL",
    "payment_method_types": ["card"]
  },
  "instructions": "Enter your credit card details to complete the payment",
  "min_order_amount": 10.00,
  "max_order_amount": 10000.00,
  "position": 10,
  "status": "A",
  "icon": "mastercard.png"
}'

Uma forma de pagamento

O caminho /api/payments/{id} trabalha com uma única forma de pagamento, identificada pelo ID.

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

Método	Descrição	Uso
GET	Recuperar uma forma de pagamento	Devolve as informações detalhadas da forma de pagamento indicada
PUT	Atualizar uma forma de pagamento	Exige um corpo JSON com os campos a atualizar
DELETE	Excluir uma forma de pagamento	Remove a forma de pagamento do sistema de forma permanente

Consultar uma forma de pagamento

Envie uma requisição GET para /api/payments/{id}. A resposta é a forma de pagamento completa:

GET/api/payments/{id}Admin

Recupera uma forma de pagamento

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments/1"

200Resposta do detalhe

json

{
  "payment_id": 1,
  "payment_name": "Credit Card - Mastercard",
  "processor": "stripe",
  "processor_params": {
    "api_key": "pk_live_TYooMQauvdEDq54NiTphI7jx",
    "currency": "BRL",
    "payment_method_types": ["card"]
  },
  "instructions": "Enter your Mastercard credit card details to complete the payment",
  "min_order_amount": 10.00,
  "max_order_amount": 10000.00,
  "position": 10,
  "status": "D",
  "icon": "mastercard.png",
  "last_modified": "2025-04-16T10:25:32Z"
}

Atualizar uma forma de pagamento

Envie uma requisição PUT para /api/payments/{id} somente com os campos que você quer alterar:

PUT/api/payments/{id}Admin

Atualiza uma forma de pagamento

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

Corpo da requisição

statusstring

AHD

Status da forma de pagamento.

processor_paramsobject

Configurações do processador.

instructionsstring

Instruções exibidas ao cliente.

bash

curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments/1" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "D",
  "processor_params": {
    "api_key": "pk_live_TYooMQauvdEDq54NiTphI7jx"
  },
  "instructions": "Enter your Mastercard credit card details to complete the payment"
}'

Excluir uma forma de pagamento

Envie uma requisição DELETE para /api/payments/{id}:

DELETE/api/payments/{id}Admin

Exclui uma forma de pagamento

Parâmetros de caminho

idintegerobrigatório

O identificador único da forma de pagamento.

bash

curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/payments/1"

Valores de status da forma de pagamento

Status	Descrição
`A`	Ativa: a forma de pagamento está disponível para o cliente escolher
`H`	Oculta: a forma de pagamento existe, mas não aparece para os clientes
`D`	Desativada: a forma de pagamento está temporariamente desativada

Processadores de pagamento aceitos

Processador	Descrição
`stripe`	Gateway de pagamento Stripe para processar cartões de crédito
`pagseguro`	Gateway de pagamento PagSeguro para as formas de pagamento brasileiras
`paypal`	Gateway de pagamento PayPal para contas PayPal
`mercadopago`	Gateway de pagamento Mercado Pago para as formas de pagamento da América Latina
`custom`	Forma de pagamento personalizada, para pagamentos offline ou processamento manual

Veja também

Formas de pagamento

O objeto de forma de pagamento da API 2.0 e suas rotas.

Paginação

Page e items_per_page na listagem.