Cost+Docs

Python

SDK oficial Python para o gateway de pagamento Cost+

SDK oficial Python para o gateway de pagamento Cost+. Simplifica o fluxo de redirecionamento HPP (Página de Pagamento Alojada), assinatura de payloads HMAC e verificação de webhooks.

Funcionalidades

  • Dependências mínimas — apenas requests
  • Type hints completos e tipos de retorno com dataclasses frozen
  • Geração de assinaturas HMAC-SHA256 e verificação em tempo constante
  • Análise de webhooks + verificação de encomendas baseada na API
  • Testado com Python 3.10, 3.11 e 3.12

Requisitos

Instalação

pip install nopayn-sdk

Início Rápido

1. Inicializar o Cliente

from nopayn import NoPaynClient

client = NoPaynClient(
    api_key="your-api-key",
    merchant_id="your-project",
)

2. Criar um Pagamento e Redirecionar para o HPP

result = client.generate_payment_url(
    amount=1295,             # €12.95 in cents
    currency="EUR",
    merchant_order_id="ORDER-001",
    description="Premium Widget",
    return_url="https://shop.example.com/success",
    failure_url="https://shop.example.com/failure",
    webhook_url="https://shop.example.com/webhook",
    locale="en-GB",
    expiration_period="PT30M",
)

# Redirect the customer
# result.order_url   → HPP (customer picks payment method)
# result.payment_url → direct link to the first transaction's payment method
# result.signature   → HMAC-SHA256 for verification
# result.order_id    → NoPayn order UUID

3. Tratar o Webhook (Exemplo Flask)

@app.route("/webhook", methods=["POST"])
def webhook():
    verified = client.verify_webhook(request.get_data(as_text=True))

    print(verified.order.status)  # 'completed', 'cancelled', etc.
    print(verified.is_final)      # True when the order won't change

    if verified.order.status == "completed":
        # Fulfil the order
        pass

    return "", 200

Referência da API

NoPaynClient(api_key, merchant_id, base_url?)

ParâmetroTipoObrigatórioPredefinição
api_keystrSim
merchant_idstrSim
base_urlstrNãohttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Cria uma encomenda via POST /v1/orders/.

ParâmetroTipoObrigatórioDescrição
amountintSimMontante na menor unidade monetária (cêntimos)
currencystrSimCódigo ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNãoA sua referência interna da encomenda
descriptionstrNãoDescrição da encomenda
return_urlstrNãoRedirecionamento após pagamento bem-sucedido
failure_urlstrNãoRedirecionamento em cancelamento/expiração/erro
webhook_urlstrNãoNotificações assíncronas de alteração de estado
localestrNãoIdioma do HPP (en-GB, de-DE, nl-NL, etc.)
payment_methodslist[str]NãoFiltrar métodos do HPP
expiration_periodstrNãoDuração ISO 8601 (PT30M)

Métodos de pagamento disponíveis: credit-card, apple-pay, google-pay, vipps-mobilepay

client.get_order(order_id) -> Order

Obtém detalhes da encomenda via GET /v1/orders/{id}/.

client.create_refund(order_id, amount, description?) -> Refund

Emite um reembolso total ou parcial via POST /v1/orders/{id}/refunds/.

client.generate_payment_url(**kwargs) -> PaymentUrlResult

Método de conveniência que cria uma encomenda e devolve:

PaymentUrlResult(
    order_id="...",       # NoPayn order UUID
    order_url="...",      # HPP URL
    payment_url="...",    # Direct payment URL (first transaction)
    signature="...",      # HMAC-SHA256 of amount:currency:order_id
    order=Order(...),     # Full order object
)

client.generate_signature(amount, currency, order_id) -> str

Gera uma assinatura HMAC-SHA256 em hexadecimal.

client.verify_signature(amount, currency, order_id, signature) -> bool

Verificação em tempo constante de uma assinatura HMAC-SHA256.

client.verify_webhook(raw_body) -> VerifiedWebhook

Analisa o corpo do webhook, depois chama GET /v1/orders/{id}/ para verificar o estado real.

Utilitários HMAC Autónomos

from nopayn import generate_signature, verify_signature

sig = generate_signature("your-api-key", 1295, "EUR", "order-uuid")
ok = verify_signature("your-api-key", 1295, "EUR", "order-uuid", sig)

Tipos de Dados

Todas as respostas da API são devolvidas como dataclasses frozen:

ClasseCampos
Orderid, amount, currency, status, created, modified, transactions, description, merchant_order_id, return_url, failure_url, order_url, completed
Transactionid, amount, currency, status, created, modified, payment_method, payment_url, expiration_period
Refundid, amount, status
PaymentUrlResultorder_id, order_url, payment_url, signature, order
VerifiedWebhookorder_id, order, is_final

Tratamento de Erros

from nopayn import ApiError, NoPaynError, WebhookError

try:
    client.create_order(amount=100, currency="EUR")
except ApiError as exc:
    print(exc.status_code)  # 401, 400, etc.
    print(exc.error_body)   # Raw API error response
except NoPaynError as exc:
    print(exc)              # Network or parsing error

Estados da Encomenda

EstadoFinal?Descrição
newNãoEncomenda criada
processingNãoPagamento em curso
completedSimPagamento bem-sucedido — entregue a mercadoria
cancelledSimPagamento cancelado pelo cliente
expiredSimLink de pagamento expirou
errorSimFalha técnica

Boas Práticas para Webhooks

  1. Verifique sempre através da API — o payload do webhook contém apenas o ID da encomenda, nunca o estado. O verify_webhook() do SDK faz isto automaticamente.
  2. Devolva HTTP 200 para confirmar a receção. Qualquer outro código desencadeia até 10 tentativas (com 2 minutos de intervalo).
  3. Implemente um poller de backup — para encomendas com mais de 10 minutos que não atingiram um estado final, consulte get_order() como rede de segurança.
  4. Seja idempotente — pode receber o mesmo webhook várias vezes.

Cartões de Teste

Utilize estes cartões no modo de teste da Cost+ (website sandbox):

CartãoNúmeroNotas
Visa (sucesso)4111 1111 1111 1111Qualquer CVV
Mastercard (sucesso)5544 3300 0003 7Qualquer CVV
Visa (recusado)4111 1111 1111 1105Do Not Honor
Visa (fundos insuficientes)4111 1111 1111 1151Insufficient Funds

Utilize qualquer data de validade futura e qualquer CVC de 3 dígitos.

Aplicação de Demonstração

Uma aplicação de demonstração baseada em Flask está incluída no repositório GitHub para testar o fluxo completo de pagamento.

Suporte

Precisa de ajuda? Contacte a nossa equipa de suporte em support@costplus.io.

On this page