Accept Payments

Understand payment outcomes

After a payment attempt, your platform should inspect the Payment object to determine the result.

This is especially important when using hosted checkout, where the payment flow is managed by Paypercut.

Why payments fail

If a payment fails, you can determine the reason by inspecting the Payment object.

Paypercut always provides structured information explaining the failure.

To understand why a payment failed, inspect:

  • failure_code for the programmatic reason
  • failure_message for customer-facing messaging
  • outcome for detailed processing and network-level information

Key fields

The outcome of a payment is described by the following fields:

  • status
  • outcome
  • failure_code
  • failure_message

Where to look

Retrieve the payment:

GET /v2/payments/{id}

Payments API

Payment status

The status field describes the high-level state.

Typical values include:

  • succeeded
  • failed
  • requires_action
  • processing

Use this field for high-level flow control.

Outcome object

The outcome field provides structured information about the result of the payment.

It includes:

  • processing result classification
  • network-level response
  • additional diagnostic context

Use the outcome object for programmatic handling, analytics, and diagnostics.

outcome.type

Indicates the high-level result of the payment attempt.

Typical values include:

  • authorized
  • issuer_declined
  • blocked
  • processing_error

Use this field as the primary classification of the outcome.

outcome.network_status

Describes the result returned by the card network.

Example values:

  • approved
  • declined
  • unavailable

Use this field for diagnostics and reconciliation.

outcome.network_decline_code

The raw response code returned by the card network.

Example:

{
  "outcome": {
    "network_decline_code": "51"
  }
}

Use this field for detailed diagnostics.

See:

outcome.seller_message

A message intended for the platform or merchant.

This message may include more detailed context than the customer-facing message.

Do not display seller messages to end users.

authorization_code

The authorization code returned by the issuer for approved transactions.

Use this value for:

  • reconciliation
  • dispute handling
  • communication with acquirers or issuers

Failure code

The failure_code is a short, stable identifier describing why the payment failed.

Example:

{
  "failure_code": "card_declined"
}

Use this field to implement conditional logic in your integration.

Failure message

The failure_message is a human-readable description of the failure.

Example:

{
  "failure_message": "Your card has insufficient funds. Please try another card."
}

This message is safe to display to the end user.

Practical examples

Successful payment 

{
  "status": "succeeded",
  "outcome": {
    "type": "authorized",
    "network_status": "approved"
  }
}

Recommended handling:

  • Fulfill the order
  • Store authorization details for reconciliation

Soft decline 

{
  "status": "failed",
  "failure_code": "card_declined",
  "failure_message": "Your card was declined. Please try again later.",
  "outcome": {
    "type": "issuer_declined",
    "network_decline_code": "05"
  }
}

Recommended handling:

  • Allow retry
  • Offer alternative payment method

Hard decline 

{
  "status": "failed",
  "failure_code": "insufficient_funds",
  "failure_message": "Your card has insufficient funds.",
  "outcome": {
    "type": "issuer_declined",
    "network_decline_code": "51"
  }
}

Recommended handling:

  • Do not retry automatically
  • Ask for another payment method

Requires action 

{
  "status": "requires_action"
}
  • The customer must complete an additional step (for example, authentication)
  • Redirect or resume the payment flow

Mapping to declines

When a payment fails due to issuer or network conditions:

  • failure_code maps to a normalized decline reason
  • outcome contains additional details
  • failure_message is safe for display

See:

Customer vs merchant messaging

Use different fields depending on the audience:

Customer

  • failure_message

Merchant / platform

  • failure_code
  • outcome
  • outcome.seller_message
  • network-level details

Do not expose raw network codes or internal messages directly to end users.

Best practices

  • Always fetch the Payment object after checkout
  • Use status for high-level flow control
  • Use failure_code for logic
  • Use failure_message for UI
  • Use outcome for deeper diagnostics
  • Log network-level data for support and reconciliation

Related pages

Previous
Notifications (Webhooks)
Next
Declines