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
- Python 3.10 ou superior
- Uma conta de comerciante Cost+ — dashboard.costplus.io
Instalação
pip install nopayn-sdkIní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 UUID3. 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 "", 200Referência da API
NoPaynClient(api_key, merchant_id, base_url?)
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
api_key | str | Sim | — |
merchant_id | str | Sim | — |
base_url | str | Não | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Cria uma encomenda via POST /v1/orders/.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | int | Sim | Montante na menor unidade monetária (cêntimos) |
currency | str | Sim | Código ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | Não | A sua referência interna da encomenda |
description | str | Não | Descrição da encomenda |
return_url | str | Não | Redirecionamento após pagamento bem-sucedido |
failure_url | str | Não | Redirecionamento em cancelamento/expiração/erro |
webhook_url | str | Não | Notificações assíncronas de alteração de estado |
locale | str | Não | Idioma do HPP (en-GB, de-DE, nl-NL, etc.) |
payment_methods | list[str] | Não | Filtrar métodos do HPP |
expiration_period | str | Não | Duraçã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:
| Classe | Campos |
|---|---|
Order | id, amount, currency, status, created, modified, transactions, description, merchant_order_id, return_url, failure_url, order_url, completed |
Transaction | id, amount, currency, status, created, modified, payment_method, payment_url, expiration_period |
Refund | id, amount, status |
PaymentUrlResult | order_id, order_url, payment_url, signature, order |
VerifiedWebhook | order_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 errorEstados da Encomenda
| Estado | Final? | Descrição |
|---|---|---|
new | Não | Encomenda criada |
processing | Não | Pagamento em curso |
completed | Sim | Pagamento bem-sucedido — entregue a mercadoria |
cancelled | Sim | Pagamento cancelado pelo cliente |
expired | Sim | Link de pagamento expirou |
error | Sim | Falha técnica |
Boas Práticas para Webhooks
- 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. - Devolva HTTP 200 para confirmar a receção. Qualquer outro código desencadeia até 10 tentativas (com 2 minutos de intervalo).
- 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. - 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ão | Número | Notas |
|---|---|---|
| Visa (sucesso) | 4111 1111 1111 1111 | Qualquer CVV |
| Mastercard (sucesso) | 5544 3300 0003 7 | Qualquer CVV |
| Visa (recusado) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fundos insuficientes) | 4111 1111 1111 1151 | Insufficient 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.