Python
SDK oficial de Python para la pasarela de pago Cost+
SDK oficial de Python para la pasarela de pago Cost+. Simplifica el flujo de redireccion HPP (pagina de pago alojada), la firma de payloads HMAC y la verificacion de webhooks.
Caracteristicas
- Dependencias minimas — solo
requests - Type hints completos y tipos de retorno con dataclasses frozen
- Generacion de firma HMAC-SHA256 y verificacion en tiempo constante
- Analisis de webhooks + verificacion de pedidos basada en API
- Probado en Python 3.10, 3.11 y 3.12
Requisitos
- Python 3.10 o posterior
- Una cuenta de comerciante Cost+ — dashboard.costplus.io
Instalacion
pip install nopayn-sdkInicio rapido
1. Inicializar el cliente
from nopayn import NoPaynClient
client = NoPaynClient(
api_key="your-api-key",
merchant_id="your-project",
)2. Crear un pago y redirigir al 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. Gestionar el webhook (ejemplo con 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 "", 200Referencia de la API
NoPaynClient(api_key, merchant_id, base_url?)
| Parametro | Tipo | Obligatorio | Predeterminado |
|---|---|---|---|
api_key | str | Si | — |
merchant_id | str | Si | — |
base_url | str | No | https://api.nopayn.co.uk |
client.create_order(**kwargs) -> Order
Crea un pedido via POST /v1/orders/.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
amount | int | Si | Importe en la unidad monetaria mas pequena (centimos) |
currency | str | Si | Codigo ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchant_order_id | str | No | Tu referencia interna de pedido |
description | str | No | Descripcion del pedido |
return_url | str | No | Redireccion despues de pago exitoso |
failure_url | str | No | Redireccion en cancelacion/expiracion/error |
webhook_url | str | No | Notificaciones asincronas de cambio de estado |
locale | str | No | Idioma del HPP (en-GB, de-DE, nl-NL, etc.) |
payment_methods | list[str] | No | Filtrar metodos del HPP |
expiration_period | str | No | Duracion ISO 8601 (PT30M) |
Metodos de pago disponibles: credit-card, apple-pay, google-pay, vipps-mobilepay
client.get_order(order_id) -> Order
Obtiene los detalles del pedido via GET /v1/orders/{id}/.
client.create_refund(order_id, amount, description?) -> Refund
Emite un reembolso total o parcial via POST /v1/orders/{id}/refunds/.
client.generate_payment_url(**kwargs) -> PaymentUrlResult
Metodo de conveniencia que crea un pedido y devuelve:
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
Genera una firma HMAC-SHA256 en hexadecimal.
client.verify_signature(amount, currency, order_id, signature) -> bool
Verificacion en tiempo constante de una firma HMAC-SHA256.
client.verify_webhook(raw_body) -> VerifiedWebhook
Analiza el cuerpo del webhook, luego llama a GET /v1/orders/{id}/ para verificar el estado real.
Utilidades HMAC independientes
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 datos
Todas las respuestas de la API se devuelven como dataclasses frozen:
| Clase | 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 |
Gestion de errores
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 del pedido
| Estado | Final? | Descripcion |
|---|---|---|
new | No | Pedido creado |
processing | No | Pago en curso |
completed | Si | Pago exitoso — entregar los bienes |
cancelled | Si | Pago cancelado por el cliente |
expired | Si | El enlace de pago expiro |
error | Si | Fallo tecnico |
Mejores practicas para webhooks
- Verifica siempre via la API — el payload del webhook solo contiene el ID del pedido, nunca el estado. El metodo
verify_webhook()del SDK hace esto automaticamente. - Devuelve HTTP 200 para confirmar la recepcion. Cualquier otro codigo activa hasta 10 reintentos (cada 2 minutos).
- Implementa un poller de respaldo — para pedidos de mas de 10 minutos que no hayan alcanzado un estado final, consulta
get_order()como red de seguridad. - Se idempotente — puedes recibir el mismo webhook multiples veces.
Tarjetas de prueba
Usa estas tarjetas en modo de prueba de Cost+ (sitio web sandbox):
| Tarjeta | Numero | Notas |
|---|---|---|
| Visa (exito) | 4111 1111 1111 1111 | Cualquier CVV |
| Mastercard (exito) | 5544 3300 0003 7 | Cualquier CVV |
| Visa (rechazada) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondos insuficientes) | 4111 1111 1111 1151 | Insufficient Funds |
Usa cualquier fecha de caducidad futura y cualquier CVC de 3 digitos.
App de demostracion
Se incluye una app de demostracion basada en Flask en el repositorio de GitHub para probar el flujo completo de pago.
Soporte
Necesitas ayuda? Contacta a nuestro equipo de soporte en support@costplus.io.