VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API legada/Referência completa

Formas de pagamento

Gerencie as opções de pagamento da loja: liste, consulte, crie, atualize e desative formas de pagamento e a configuração do processador.

A API de formas de pagamento gerencia as opções que o cliente pode escolher no checkout. Uma forma de pagamento liga um processador (um gateway de cartão, o PayPal, uma transferência bancária etc.) às configurações que definem quando e como ela é oferecida: nome, instruções, limites de valor do pedido, países permitidos e uma taxa adicional opcional.

Você usa estas rotas ao montar uma loja, ao trocar as credenciais de um processador ou quando precisa ligar e desligar uma forma de pagamento sem abrir o painel. Elas ficam em $BASE_URL/api/2.0/payments, exigem uma conta de administrador e usam credenciais HTTP Basic ($EMAIL:$API_KEY).

Pontos principais
  • Toda forma de pagamento tem um código de categoria em payment_category: cc, paypal, bank, cod, pix ou boleto.
  • status é A (ativa) ou D (desativada).
  • As credenciais do processador vão dentro de processor_params. Mantenha-as no seu servidor.
  • DELETE em uma forma de pagamento a desativa.
  • A rota de listagem é paginada, veja Paginação. As URLs mais curtas, /api/payments, estão na página Endpoints.

Como funciona

Quando o cliente chega ao checkout, a loja oferece as formas de pagamento configuradas e ativas para o pedido. Da escolha até a confirmação, o fluxo é sempre o mesmo:

  1. Escolha da forma de pagamento
    O cliente escolhe uma forma de pagamento durante o checkout.
  2. Coleta dos dados de pagamento
    O sistema coleta as informações de pagamento que a forma escolhida exige.
  3. Processamento do pagamento
    O pagamento é enviado ao processador.
  4. Atualização do status do pedido
    O status do pedido é atualizado conforme o resultado do pagamento.
  5. Confirmação
    O cliente recebe a confirmação do pagamento.

Cada processador pode ter requisitos de integração próprios, então consulte a documentação do processador que você usa para conhecer as configurações dele.

A categoria da forma de pagamento é dada por payment_category:

Forma de pagamentoCódigoDescrição
Cartão de créditoccProcessa pagamentos pelas principais bandeiras de cartão. Aceita vários processadores.
PayPalpaypalPermite que o cliente pague com a conta PayPal.
Transferência bancáriabankGera as instruções para uma transferência bancária direta.
Pagamento na entregacodPagamento recebido no momento da entrega.
PIXpixSistema de pagamento instantâneo para lojistas brasileiros.
BoletoboletoSistema brasileiro de boleto bancário.

Conceitos principais

O objeto da forma de pagamento

Ao criar ou atualizar uma forma de pagamento, você envia a configuração dela. Este é um cartão de crédito configurado com um gateway de cartão:

json
{
  "payment_id": "16",
  "processor": "stripe",
  "payment_category": "cc",     
  "company_id": "1",
  "position": 10,
  "status": "A",           // A - active, D - disabled
  "processor_params": {
    "api_key": "sk_test_abcdefghijklmnopqrstuvwxyz",
    "publishable_key": "pk_test_abcdefghijklmnopqrstuvwxyz",
    "test_mode": false,
    "payment_types": ["visa", "mastercard", "amex"]
  },
  "localization": {
    "payment_name": "Credit Card",
    "description": "Pay securely with your credit card",
    "instructions": "Enter your card details to complete the payment"
  },
  "surcharge": 0,
  "tax_ids": ["1", "2"],
  "min_order_amount": 5.00,
  "max_order_amount": null,
  "allowed_countries": ["BR", "US", "CA"]
}

Campos da forma de pagamento

payment_idstring
Identificador da forma de pagamento (um número, devolvido como texto).
processorstring
O processador que cuida dos pagamentos, por exemplo stripe.
payment_categorystring
ccpaypalbankcodpixboleto
Categoria da forma de pagamento.
company_idstring
Identificador da empresa à qual a forma de pagamento pertence.
positioninteger
Posição da forma de pagamento na lista exibida ao cliente.
statusstring
AD
A para ativa, D para desativada.
processor_paramsobject
Configurações do processador. O exemplo traz api_key, publishable_key, test_mode e payment_types.
localizationobject
Textos exibidos ao cliente: payment_name, description e instructions.
surchargenumber
Taxa somada ao pedido quando o cliente escolhe esta forma de pagamento.
tax_idsarray
Identificadores dos impostos ligados à forma de pagamento.
min_order_amountnumber
Menor valor de pedido para o qual a forma de pagamento é oferecida.
max_order_amountnumber
Maior valor de pedido para o qual a forma de pagamento é oferecida. null significa sem limite.
allowed_countriesarray
Códigos dos países em que a forma de pagamento está disponível.
Aviso de segurança

Nunca exponha suas chaves de API nem outras credenciais sensíveis de pagamento em código do lado do cliente. Processe os pagamentos sempre de forma segura, pelo seu servidor.

Endpoints

MétodoCaminhoFinalidadeAutenticação
GET/api/2.0/paymentsDevolve a lista de todas as formas de pagamento configuradas na loja, veja abaixoAdmin
GET/api/2.0/payments/{payment_id}Devolve os detalhes da configuração de uma forma de pagamento, veja abaixoAdmin
POST/api/2.0/paymentsCria a configuração de uma nova forma de pagamento, veja abaixoAdmin
PUT/api/2.0/payments/{payment_id}Atualiza a configuração de uma forma de pagamento existente, veja abaixoAdmin
DELETE/api/2.0/payments/{payment_id}Desativa uma forma de pagamento, veja abaixoAdmin
GET, POST, e GET, PUT, DELETE em /api/payments/{id}/api/paymentsAs URLs mais curtas da coleção e de uma forma de pagamento, veja EndpointsAdmin

Listar formas de pagamento

GET/api/2.0/paymentsAdmin

Devolve a lista de todas as formas de pagamento configuradas na loja

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/2.0/payments"

Consultar uma forma de pagamento

GET/api/2.0/payments/{payment_id}Admin

Devolve os detalhes da configuração de uma forma de pagamento

Parâmetros de caminho

payment_idintegerobrigatório
Identificador da forma de pagamento.
bash
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/payments/16"

Criar uma forma de pagamento

POST/api/2.0/paymentsAdmin

Cria a configuração de uma nova forma de pagamento

Corpo da requisição

processorstring
O processador de pagamento, por exemplo stripe.
payment_categorystring
ccpaypalbankcodpixboleto
Categoria da forma de pagamento.
company_idstring
Identificador da empresa.
positioninteger
Posição na lista de formas de pagamento.
statusstring
AD
A para ativa, D para desativada.
processor_paramsobject
Configurações do processador, como as chaves de API.
localizationobject
payment_name, description e instructions exibidos ao cliente.
surchargenumber
Taxa adicional desta forma de pagamento.
tax_idsarray
Identificadores dos impostos ligados.
min_order_amountnumber
Menor valor de pedido para a forma de pagamento.
max_order_amountnumber
Maior valor de pedido para a forma de pagamento, ou null para não ter limite.
allowed_countriesarray
Códigos dos países em que a forma de pagamento está disponível.
bash
curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/payments" \
  -H "Content-Type: application/json" \
  -d '{
  "processor": "stripe",
  "payment_category": "cc",
  "company_id": "1",
  "position": 10,
  "status": "A",
  "processor_params": {
    "api_key": "sk_test_abcdefghijklmnopqrstuvwxyz",
    "publishable_key": "pk_test_abcdefghijklmnopqrstuvwxyz",
    "test_mode": false,
    "payment_types": ["visa", "mastercard", "amex"]
  },
  "localization": {
    "payment_name": "Credit Card",
    "description": "Pay securely with your credit card",
    "instructions": "Enter your card details to complete the payment"
  },
  "surcharge": 0,
  "tax_ids": ["1", "2"],
  "min_order_amount": 5.00,
  "max_order_amount": null,
  "allowed_countries": ["BR", "US", "CA"]
}'

Atualizar uma forma de pagamento

PUT/api/2.0/payments/{payment_id}Admin

Atualiza a configuração de uma forma de pagamento existente

Parâmetros de caminho

payment_idintegerobrigatório
Identificador da forma de pagamento a atualizar.

Corpo da requisição

statusstring
AD
A para ativa, D para desativada.
processor_paramsobject
Novas configurações do processador.
localizationobject
Novos textos para o cliente.
surchargenumber
Nova taxa adicional.
min_order_amountnumber
Novo menor valor de pedido.
max_order_amountnumber
Novo maior valor de pedido.
allowed_countriesarray
Nova lista de códigos de país.

A documentação original não traz um corpo para esta rota; os campos acima são os do objeto da forma de pagamento. O exemplo abaixo desativa a forma de pagamento.

bash
curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/payments/16" \
  -H "Content-Type: application/json" \
  -d '{"status": "D"}'

Desativar uma forma de pagamento

DELETE/api/2.0/payments/{payment_id}Admin

Desativa uma forma de pagamento

Parâmetros de caminho

payment_idintegerobrigatório
Identificador da forma de pagamento a desativar.
bash
curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/2.0/payments/16"
Dica

Use o parâmetro surcharge para cobrar uma taxa adicional em formas de pagamento específicas, quando necessário. Isso é útil para formas de pagamento com custo de processamento mais alto.

Erros comuns

  • Colocar chaves do processador, como api_key, em código de navegador ou de aplicativo. Envie-as apenas a partir do seu servidor.
  • Ativar uma forma de pagamento em produção antes de testá-la no modo sandbox ou de teste.
  • Deixar sem definição os limites de valor do pedido (min_order_amount e max_order_amount), o que facilita a passagem de transações fraudulentas.
  • Oferecer uma forma de pagamento em países onde ela não é aceita. Preencha allowed_countries.
  • Manter as mesmas credenciais do processador para sempre. Troque-as periodicamente.
Nota

Os processadores de pagamento podem ter requisitos de integração diferentes. Consulte a documentação do processador para ver as orientações detalhadas de implementação.

Próximos passos

Endpoints
As URLs /api/payments, os processadores e os valores de status.
Paginação
Controle a página e o tamanho da página ao listar as formas de pagamento.
Impostos
Os impostos que uma forma de pagamento pode referenciar em tax_ids.
Anterior
Regras de imposto
Próxima
Endpoints de formas de pagamento
Nesta página
  • Como funciona
  • Conceitos principais
  • O objeto da forma de pagamento
  • Endpoints
  • Listar formas de pagamento
  • Consultar uma forma de pagamento
  • Criar uma forma de pagamento
  • Atualizar uma forma de pagamento
  • Desativar uma forma de pagamento
  • Erros comuns
  • Próximos passos