Pagamentos

Todas as chamadas desta página partem do servidor do e-commerce, com a chave no cabeçalho Authorization (Autenticação e idempotência). Os exemplos usam:

export WP_API=https://pay-api.staging.bloomx.cloud
export WP_KEY='wp_test.<key_id>.<segredo>'

Criar um pagamento: POST /v1/payments

Permissão payments:write. Exige Idempotency-Key.

curl -s -X POST "$WP_API/v1/payments" \
  -H "Authorization: Bearer $WP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1234:autorizar' \
  -d '{
    "amount_cents": 15000,
    "installments": 1,
    "capture": true,
    "external_reference": "pedido-1234",
    "payment_source": { "source_type": "token", "token_id": "<tokenId do navegador>" },
    "customer": {
      "name": "Maria Teste",
      "email": "maria@example.com",
      "document": "12345678909",
      "phone": "11999999999",
      "address": {
        "zip_code": "01001000",
        "street": "Rua Teste",
        "number": "100",
        "complement": "Sala 1",
        "district": "Centro",
        "city": "Sao Paulo",
        "state": "SP"
      }
    }
  }'

Respostas:

Guarde o id do pagamento: é ele que as outras rotas e o webhook usam. A resposta também traz o cabeçalho Location com o endereço do pagamento.

Capturar uma pré-autorização: POST /v1/payments/{id}/capture

Permissão payments:write. Exige Idempotency-Key. Sem corpo, captura o valor total; com amount_cents, captura parcialmente (até o valor autorizado).

curl -s -X POST "$WP_API/v1/payments/<id>/capture" \
  -H "Authorization: Bearer $WP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1234:capturar' \
  -d '{ "amount_cents": 15000 }'

A captura responde 200 com o pagamento em captured. A pré-autorização vale pelo número de dias de preauth_ttl_days em GET /v1/capabilities (hoje, 7 dias); o fim da janela está em expires_at. Depois disso, a captura recebe 422 preauth_expired. Um pagamento que não está em pre_authorized recebe 409 invalid_state.

Cancelar ou estornar: POST /v1/payments/{id}/cancel

Permissão payments:write. Exige Idempotency-Key. A mesma rota desfaz uma pré-autorização ou estorna um pagamento capturado. Sem corpo, estorna o saldo todo; com amount_cents, estorna parcialmente.

curl -s -X POST "$WP_API/v1/payments/<id>/cancel" \
  -H "Authorization: Bearer $WP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pedido-1234:estorno-1' \
  -d '{ "amount_cents": 5000 }'

Estorno acima do saldo recebe 422 amount_exceeds_refundable. Cada estorno parcial leva a sua própria Idempotency-Key.

Consultar um pagamento: GET /v1/payments/{id}

Permissão payments:read. É a fonte da verdade sobre o pagamento e pode ser consultada a qualquer momento.

curl -s "$WP_API/v1/payments/<id>" -H "Authorization: Bearer $WP_KEY"

Listar pagamentos: GET /v1/payments

Permissão payments:read. Lista do mais novo para o mais antigo, em páginas.

curl -s "$WP_API/v1/payments?status=captured&limit=20" -H "Authorization: Bearer $WP_KEY"

A resposta traz items (os pagamentos) e next_cursor, que vem null na última página.

Guardar o cartão: POST /v1/cards

Permissão cards:write. Troca um token_id por um cartão guardado no cofre do provedor, para cobrar de novo sem pedir o cartão ao comprador. O token é consumido aqui: para pagar na mesma hora, gere outro token_id.

curl -s -X POST "$WP_API/v1/cards" \
  -H "Authorization: Bearer $WP_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "token_id": "<tokenId do navegador>" }'

{ "card_id": "<card_id>", "status": "active", "brand": "mastercard", "last4": "0020",
  "expiration_month": "12", "expiration_year": "2030", "holder_name": "MARIA TESTE" }

Depois, pague com "payment_source": { "source_type": "card", "card_id": "<card_id>" }. Guarde o card_id associado ao cliente no seu sistema; ele só serve com a chave do seu estabelecimento.

Status do pagamento