API Error

  • message
    Type: string
    max length:  
    40000
    required

    A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.

  • type
    Type: stringenum
    required

    The type of error returned.

    values
    • api_error

      The request could not be processed because of an internal Paypercut or upstream issue.

    • card_error

      A payment attempt failed because of card, issuer, network, or authentication behavior.

    • idempotency_error

      The request conflicts with an earlier request made with the same idempotency key.

    • invalid_request_error

      The request is malformed, contains invalid parameters, or cannot be processed in its current state.

  • advice_code
    Type: string
    max length:  
    5000

    For card errors resulting from an issuer decline, a short string indicating how to proceed if advice is available.

  • checkout_session
  • code
    Type: string | null
    max length:  
    5000

    For some errors that can be handled programmatically, a short string indicating the error reported.

  • decline_code
    Type: string
    max length:  
    5000

    For card errors resulting from an issuer decline, a short string indicating the issuer's reason if one is available.

  • network_advice_code
    Type: string
    max length:  
    5000

    For card errors resulting from an issuer decline, a network-provided advice code when available.

  • network_decline_code
    Type: string
    max length:  
    5000

    For payments declined by the network, an alphanumeric code indicating the reason the payment failed.

  • next_action
    Type: object

    Describes a recoverable action the client can take after receiving this error. The exact fields depend on the action type.

    • type
      Type: string
      max length:  
      5000
      required

      The type of action the client should perform.

    • metadata
      Type: object | null

      Additional action-specific metadata. Keys and values are strings so clients can safely forward them to SDK handlers or use them for follow-up requests.

    • use_sdk
      Type: object

      Instructs the client to continue the flow through a client-side SDK.

  • param
    Type: string
    max length:  
    5000

    If the error is parameter-specific, the parameter related to the error.

  • trace_id
    Type: string
    max length:  
    5000

    Trace ID of the request, which can be used to reference the failed request in support conversations.

  • violation_code
    Type: string
    max length:  
    5000

    For some validation errors, a short string indicating the specific rule violation.