Result Codes and Errors

Result Codes

When you make a payment request, Plexy returns a resultCode that indicates the outcome. Understanding these codes is essential for providing a good customer experience and correctly handling payment states.

Quick Reference

Result Code	Meaning	Action Required
`Authorised`	Payment successful	Fulfill the order
`Refused`	Payment declined	Show decline message
`Pending`	Awaiting final result	Wait for webhook
`Received`	Payment initiated	Wait for webhook
`Error`	Technical error	Retry or investigate
`Cancelled`	Customer cancelled	Return to checkout
`RedirectShopper`	Redirect required	Redirect the customer
`IdentifyShopper`	3DS device fingerprint	Perform 3DS fingerprint
`ChallengeShopper`	3DS challenge required	Show 3DS challenge
`PresentToShopper`	Show voucher/QR	Display payment info

Successful Payment

Authorised

The payment was successfully authorized. The funds have been reserved on the customer's account (or captured, depending on your configuration).

What to do:

Mark the order as paid

Trigger order fulfillment (shipping, access, etc.)

Send confirmation email to customer

Info

If you have separate authorization and capture, the payment is only reserved. You'll need to capture it later to receive the funds.

Declined Payments

Refused

The payment was declined by the card issuer, payment provider, or Plexy's risk system.

What to do:

Display a customer-friendly message

Suggest trying a different payment method

Do not store the card details for retry

Common Refusal Reason Codes

Code	Reason	Customer Message
`2`	Refused	Try a different payment method
`3`	Referral	Contact bank for approval
`4`	Acquirer Error	Technical issue, retry later
`5`	Blocked Card	Card is blocked by issuer
`6`	Expired Card	Card has expired
`7`	Invalid Amount	Amount issue, contact support
`8`	Invalid Card Number	Check card number
`9`	Issuer Unavailable	Bank unavailable, retry later
`10`	Not Supported	Card type not accepted
`11`	3D Secure Failed	Authentication failed
`12`	Not Enough Balance	Insufficient funds
`14`	Fraud	Payment declined
`15`	Cancelled	Customer cancelled
`16`	Shopper Cancelled	Customer cancelled
`17`	Invalid Pin	Incorrect PIN
`20`	Fraud - Risk	Declined by risk system
`21`	Not Submitted	Processing error
`22`	Fraud - CVV	CVV check failed
`23`	Transaction Not Permitted	Not allowed for this card
`24`	CVC Declined	CVV check failed
`25`	Restricted Card	Card restricted
`26`	Revocation	Authorization revoked
`27`	Declined Non-Generic	Contact bank
`28`	Withdrawal Amount Exceeded	Over withdrawal limit
`29`	Withdrawal Count Exceeded	Too many withdrawals
`31`	Fraud - Raw	Fraud detected
`32`	AVS Declined	Address verification failed
`33`	Card requires online PIN	Online PIN required
`34`	No checking account	Account not found
`35`	No savings account	Account not found
`36`	Mobile PIN required	PIN required
`37`	Contactless fallback	Use chip instead
`38`	Authentication required	Additional auth needed

Cancelled

The customer cancelled the payment before completion. This typically happens when:

Customer clicks "back" or closes the payment page

Customer cancels on a redirect page (e.g., bank authentication)

Session times out

What to do:

Return customer to the cart/checkout page

Keep the order in "pending" state

Allow retry with same or different payment method

Error

A technical error occurred during payment processing. This could be due to:

Network issues

Service unavailability

Invalid request data

Configuration issues

What to do:

Log the error for investigation

Display a generic error message

Offer retry option

Alert your team if errors persist

Pending States

Pending

The payment result is not yet known. This is common for:

Bank transfers

Asynchronous payment methods

Manual review

What to do:

Mark the order as "awaiting payment"

Wait for webhook notification with final result

Show appropriate status to customer

Warning

Never fulfill orders with Pending status until you receive a webhook confirming the payment was successful.

Received

Similar to Pending, but specifically indicates that Plexy has received the payment request. The final result will come via webhook.

What to do:

Same as Pending

Common for payment methods like Boleto, iDEAL, or bank transfers

Action Required

These result codes indicate that additional steps are needed to complete the payment.

RedirectShopper

The customer must be redirected to an external page to complete authentication or authorization (e.g., bank login, payment app).

What to do:

Store relevant state (order ID) for when customer returns

Redirect to the URL in the action object

Handle the return URL callback

IdentifyShopper

3D Secure 2 device fingerprinting is required. This is the first step of 3DS2 authentication.

What to do:

Use the Plexy 3DS SDK to perform fingerprinting

Submit the result to /v2/payments/details

Handle the next result code

ChallengeShopper

3D Secure 2 challenge is required. The customer needs to authenticate with their bank (e.g., enter OTP, approve in banking app).

What to do:

Display the 3DS challenge UI

Submit the challenge result to /v2/payments/details

PresentToShopper

Payment information needs to be shown to the customer (e.g., voucher, QR code, bank transfer details).

What to do:

Display the provided payment information

Wait for webhook notification of payment completion

Some methods have expiration times

Comprehensive Result Handler

Here's a complete example handling all result codes:

JavaScript

Python

Webhook Event Types

Each result code maps to webhook events you should handle:

Result Code	Webhook Event
`Authorised`	`payment.authorised`
`Refused`	`payment.refused`
`Cancelled`	`payment.cancelled`
`Error`	`payment.error`
`Pending` → Success	`payment.authorised`
`Pending` → Failure	`payment.refused` or `payment.expired`
`Received` → Success	`payment.authorised`
`Received` → Failure	`payment.refused` or `payment.expired`

Best Practices

Always verify via webhooks - Don't rely solely on the synchronous response. Webhooks provide the authoritative payment status.

Map to your order states - Create a clear mapping between Plexy result codes and your internal order states.

Log all results - Keep detailed logs of payment results for debugging and support.

Show appropriate messages - Use customer-friendly messages for declines. Avoid exposing raw error codes.

Handle edge cases - Plan for network failures, timeouts, and unexpected result codes.

Verify all scenarios - Simulate different result codes before going live.

Next Steps

Handle 3D Secure authentication flows

Set up webhooks for reliable notifications

Verify the full payment lifecycle before enabling customer traffic

HTTP Status Codes

The Plexy API uses standard HTTP status codes to indicate request outcomes.

Success codes

Code	Description
`200 OK`	Request succeeded
`201 Created`	Resource created successfully
`204 No Content`	Request succeeded, no response body

Client error codes

Code	Description	Action
`400 Bad Request`	Invalid request parameters	Check request body
`401 Unauthorized`	Invalid or missing API key	Verify API credentials
`403 Forbidden`	Insufficient permissions	Check API key permissions
`404 Not Found`	Resource doesn't exist	Verify resource ID
`405 Method Not Allowed`	Invalid HTTP method	Check endpoint documentation
`409 Conflict`	Idempotency conflict	Request already processed
`422 Unprocessable Entity`	Valid request but cannot process	Check business logic

Server error codes

Code	Description	Action
`500 Internal Server Error`	Unexpected server error	Retry with backoff
`502 Bad Gateway`	Upstream service error	Retry with backoff
`503 Service Unavailable`	Service temporarily down	Retry with backoff
`504 Gateway Timeout`	Request timed out	Retry with backoff

Handling responses

Check the HTTP status code of every response. Successful operations return 2xx; errors return 4xx or 5xx with an error object in the body:

Status range	Meaning	Action
`2xx`	Success	Process the response
`400`	Bad request	Fix request parameters
`401`	Unauthorized	Verify API key
`5xx`	Server error	Retry with exponential backoff

Retry strategy

For 500, 502, 503, and 504 responses, retry the request with exponential backoff and the same Idempotency-Key:

Error Codes

Understand and handle errors returned by the Plexy API.

Error structure

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: amount",
    "param": "amount",
    "request_id": "req_abc123"
  }
}

Field	Description
`type`	Error category
`code`	Specific error code
`message`	Human-readable description
`param`	Parameter that caused error (if applicable)
`request_id`	Unique request identifier

Error types

`api_error`

Server-side errors. Usually temporary - retry with backoff.

Code	Description
`api_error`	General API error

`invalid_request_error`

Client-side request errors. Fix the request and retry.

Code	Description
`parameter_missing`	Required parameter not provided
`parameter_invalid`	Parameter value is invalid
`parameter_unknown`	Unrecognized parameter
`resource_missing`	Referenced resource doesn't exist
`idempotency_error`	Idempotency key reused with different params

`authentication_error`

API key or authentication problems.

Code	Description
`api_key_invalid`	Invalid API key
`api_key_expired`	API key has expired
`api_key_revoked`	API key was revoked

`card_error`

Payment card issues. Display message to customer.

Code	Description
`card_declined`	Card was declined
`expired_card`	Card has expired
`incorrect_cvc`	CVC is incorrect
`incorrect_number`	Card number is incorrect
`insufficient_funds`	Card has insufficient funds
`processing_error`	Error processing card

Handling errors

The API always returns an error object in the response body for non-2xx responses. Check the HTTP status code first, then inspect error.type and error.code:

Example error response:

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "request_id": "req_abc123"
  }
}

HTTP status	`error.type`	Action
`402`	`card_error`	Show `error.message` to the customer
`400`	`invalid_request_error`	Fix the request parameters
`401`	`authentication_error`	Check your API key configuration
`500–503`	`api_error`	Retry with exponential backoff

Customer-facing messages

Map error codes to user-friendly messages:

Code	Customer Message
`card_declined`	"Your card was declined. Please try a different card."
`expired_card`	"Your card has expired. Please use a valid card."
`incorrect_cvc`	"The security code is incorrect. Please check and try again."
`insufficient_funds`	"Your card has insufficient funds. Please try a different card."
`processing_error`	"An error occurred processing your card. Please try again."

Refusal Reasons

When a payment is declined, the response includes a decline code indicating the reason.

Common decline codes

Code	Description	Recoverable
`generic_decline`	Card declined for unspecified reason	Maybe
`insufficient_funds`	Not enough funds available	Yes
`lost_card`	Card reported lost	No
`stolen_card`	Card reported stolen	No
`expired_card`	Card has expired	No
`incorrect_cvc`	CVC verification failed	Yes
`incorrect_number`	Card number is incorrect	Yes
`processing_error`	Processing error occurred	Yes
`do_not_honor`	Issuer declined without reason	Maybe
`pickup_card`	Card should be retained	No

Decline response

{
  "id": "pay_abc123",
  "status": "failed",
  "failure_code": "insufficient_funds",
  "failure_message": "The card has insufficient funds.",
  "outcome": {
    "type": "issuer_declined",
    "reason": "insufficient_funds",
    "ripr_level": "normal",
    "seller_message": "The card has insufficient funds to complete the purchase."
  }
}

Handling declines

Recoverable declines

For recoverable errors, prompt the customer to:

Use a different payment method

Enter correct card details

Contact their bank

Non-recoverable declines

For permanent declines, advise the customer to use a different payment method:

Customer messaging

Decline Code	Recommended Message
`generic_decline`	"Your payment was declined. Please try a different card or contact your bank."
`insufficient_funds`	"Your card has insufficient funds. Please try a different card."
`lost_card`	"This card cannot be used. Please use a different payment method."
`expired_card`	"Your card has expired. Please update your card details."
`incorrect_cvc`	"The security code is incorrect. Please check and try again."
`incorrect_number`	"The card number is incorrect. Please check and try again."
`do_not_honor`	"Your bank declined the payment. Please contact your bank or try a different card."

Retry recommendations

Category	Action
Card details wrong	Let customer retry with correct details
Insufficient funds	Suggest different card
Fraud-related	Don't retry, suggest different method
Bank declined	Suggest contacting bank

Reduce declines

Collect complete billing address - Improves AVS matching

Request CVC - Reduces fraud declines

Use 3D Secure - Shifts liability, improves approval

Update stored cards - Use Account Updater for subscriptions

Result Codes and Errors

Result Codes#

Quick Reference#

Successful Payment#

Authorised#

Declined Payments#

Refused#

Common Refusal Reason Codes#

Cancelled#

Error#

Pending States#

Pending#

Received#

Action Required#

RedirectShopper#

IdentifyShopper#

ChallengeShopper#

PresentToShopper#

Comprehensive Result Handler#

Webhook Event Types#

Best Practices#

Next Steps#

HTTP Status Codes#

Success codes#

Client error codes#

Server error codes#

Handling responses#

Retry strategy#

See also#

Error Codes#

Error structure#

Error types#

api_error#

invalid_request_error#

authentication_error#

card_error#

Handling errors#

Customer-facing messages#

See also#

Refusal Reasons#

Common decline codes#

Decline response#

Handling declines#

Recoverable declines#

Non-recoverable declines#

Customer messaging#

Retry recommendations#

Reduce declines#

See also#

Result Codes

Quick Reference

Successful Payment

Authorised

Declined Payments

Refused

Common Refusal Reason Codes

Cancelled

Error

Pending States

Pending

Received

Action Required

RedirectShopper

IdentifyShopper

ChallengeShopper

PresentToShopper

Comprehensive Result Handler

Webhook Event Types

Best Practices

Next Steps

HTTP Status Codes

Success codes

Client error codes

Server error codes

Handling responses

Retry strategy

See also

Error Codes

Error structure

Error types

`api_error`

`invalid_request_error`

`authentication_error`

`card_error`

Handling errors

Customer-facing messages

See also

Refusal Reasons

Common decline codes

Decline response

Handling declines

Recoverable declines

Non-recoverable declines

Customer messaging

Retry recommendations

Reduce declines

See also