Cost+Docs

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

Instalacion

pip install nopayn-sdk

Inicio 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 UUID

3. 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 "", 200

Referencia de la API

NoPaynClient(api_key, merchant_id, base_url?)

ParametroTipoObligatorioPredeterminado
api_keystrSi
merchant_idstrSi
base_urlstrNohttps://api.nopayn.co.uk

client.create_order(**kwargs) -> Order

Crea un pedido via POST /v1/orders/.

ParametroTipoObligatorioDescripcion
amountintSiImporte en la unidad monetaria mas pequena (centimos)
currencystrSiCodigo ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchant_order_idstrNoTu referencia interna de pedido
descriptionstrNoDescripcion del pedido
return_urlstrNoRedireccion despues de pago exitoso
failure_urlstrNoRedireccion en cancelacion/expiracion/error
webhook_urlstrNoNotificaciones asincronas de cambio de estado
localestrNoIdioma del HPP (en-GB, de-DE, nl-NL, etc.)
payment_methodslist[str]NoFiltrar metodos del HPP
expiration_periodstrNoDuracion 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:

ClaseCampos
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

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 error

Estados del pedido

EstadoFinal?Descripcion
newNoPedido creado
processingNoPago en curso
completedSiPago exitoso — entregar los bienes
cancelledSiPago cancelado por el cliente
expiredSiEl enlace de pago expiro
errorSiFallo tecnico

Mejores practicas para webhooks

  1. 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.
  2. Devuelve HTTP 200 para confirmar la recepcion. Cualquier otro codigo activa hasta 10 reintentos (cada 2 minutos).
  3. 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.
  4. Se idempotente — puedes recibir el mismo webhook multiples veces.

Tarjetas de prueba

Usa estas tarjetas en modo de prueba de Cost+ (sitio web sandbox):

TarjetaNumeroNotas
Visa (exito)4111 1111 1111 1111Cualquier CVV
Mastercard (exito)5544 3300 0003 7Cualquier CVV
Visa (rechazada)4111 1111 1111 1105Do Not Honor
Visa (fondos insuficientes)4111 1111 1111 1151Insufficient 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.

On this page