Skip to content
ApiqDevelopers
API v1.64.0Open console
API referencepayments

Receive psp source webhook

POST/v1/payments/psp-webhook/{provider}/{sourceRef}

The payment provider's notification about payments on ONE tenant's own account

The endpoint a tenant registers at its own provider account (provider key stripe; sourceRef is the tenant's credential set id).Show moreThe endpoint a tenant registers at its own provider account (provider key stripe; sourceRef is the tenant's credential set id). No platform credential (security is empty): the signature, made with THAT account's own webhook signing secret (the set's webhookSecret field), is the credential, verified before anything is read — a missing, invalid or stale signature, an unknown source or a revoked set is 401 UNAUTHENTICATED and nothing is applied. A verified notification applies to that tenant's payments on that credential set only: one tenant's secret can never move another tenant's payment, nor a payment on the platform's account (such a reference answers 400 VALIDATION details.reason UNKNOWN_PAYMENT_REF). Redelivery is 200 DUPLICATE.

Path parameters

  • providerstringRequired
    The payment-provider key, e.g. stripe
  • sourceRefstringRequired
    The tenant's credential set id the endpoint was registered for

Request bodyobject

    Responses

    • 200Verified; ACCEPTED (applied once, or acknowledged and ignored) or DUPLICATEPspWebhookAck
    • 400VALIDATION. details.reason UNKNOWN_PAYMENT_REF — including a payment of another tenant, another set or the platform's account — CURRENCY_MISMATCH or NOTICE_CONTRADICTS_PAYMENT.ApiErrorResponse
    • 401UNAUTHENTICATED: the signature is missing, invalid or stale, or the source is unknown or revoked (details.reason REJECTED_SIGNATURE | REJECTED_STALE | REJECTED_UNVERIFIABLE).ApiErrorResponse
    • 405
      VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
      ApiErrorResponse
    • 413
      VALIDATION — the request body is larger than the surface's limit.Show moreVALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
      ApiErrorResponse
    • 414
      VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
      ApiErrorResponse
    • 415
      VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show moreVALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
      ApiErrorResponse
    • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
    • 501
      NOT_IMPLEMENTED — this deployment serves no payments: no payment provider is configured (provider=none), so every payment route answers 501.Show moreNOT_IMPLEMENTED — this deployment serves no payments: no payment provider is configured (provider=none), so every payment route answers 501. Not a capabilities-doc bug: payments are deployment configuration.
      ApiErrorResponse

    Errors you should handle

    Branch on code and honour retryable — never on the HTTP status alone.

    400VALIDATION
    The notice names an unknown payment reference.
    		not retryable
    401UNAUTHENTICATED
    payment-provider webhook rejected at the ingestion edge
    		not retryable
    405VALIDATION
    This method is not served.
    		not retryable
    413VALIDATION
    The request body is larger than this API accepts (262144 bytes).
    		not retryable
    414VALIDATION
    The request URI is longer than 8 KiB.
    		not retryable
    415VALIDATION
    Send application/json.
    		not retryable
    500INTERNAL
    An unexpected error occurred. Quote the traceId to support.
    		retryable
    501NOT_IMPLEMENTED
    This deployment serves no payments: no payment provider is configured.
    		not retryable