Declined payment

Xsolla Developers

Declined paymentWebhook POST

If a transaction is declined by a payment system, Xsolla sends the transaction details in a webhook of the ps_declined type to your configured webhook URL. The webhook is sent during the authorization or payment processing stage. In this case, the payment\ order_paid webhook is not sent.

Typical reasons for payment system declines:

Card authorization failed (for example, the payment system could not complete the authorization process due to a technical error or no response from the bank) or was declined (for example, the bank responded but refused the transaction due to insufficient funds or invalid card details).
3-D Secure verification failed, was not completed, or the user confirmation timed out.
The processor or acquiring bank is temporarily unavailable or returns a hard decline due to an irreversible error, such as a closed account or an invalid card number. Retrying without addressing the underlying issue will not result in a successful transaction.

Should not be confused with:

Anti-fraud rejections, which are reported via the afs_reject webhook.
Refunds and partial refunds after a successful payment, which are reported via the refund and partial_refund webhooks.

Note

To receive the ps_declined webhook, contact your Customer Success Manager or email csm@xsolla.com.

Request

Request Body schema: application/json

notification_type

required

string

Notification type.

required

object

Transaction details (object).

id	integer Transaction ID.
external_id	string Transaction external ID.
dry_run	integer Test transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
payment_method	integer Payment method ID.

object

Custom project settings (object).

project_id	integer Project ID. You can find this parameter in your Publisher Account next to the name of the project.
merchant_id	integer Merchant ID.

object

User details (object).

id required	string User ID.
ip	string User IP.
email	string User email.
name	string Username.
country	string User’s country. Two-letter uppercase ISO 3166-1 alpha-2 country code.

object

Refund details (object).

code

integer

Code ID.

reason

string

Refund reason.

author

string

Refund initiator. The field value is passed according to the table:

Refund initiator	Field value
Game (via API).	API
Publisher Account user (automatic refund).	User email
Publisher Account user (with assistance from Xsolla customer support).	support@xsolla.com
Xsolla (with assistance from Xsolla customer support).	support@xsolla.com

Responses

204

Return to indicate successful processing.

400

Return in case of an error in the provided information (e.g., a required parameter missing, failed authorization, etc.). In this case, the user’s money is debited, but the purchase fails. To make a refund, contact Xsolla customer support at support@xsolla.com.

500

Return to indicate temporary errors with your servers.

Request samples

CURL
PHP
HTTP

curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 80543ba63e1e50cf05f15150fe75e7245da9a898' \
-d '{
  "notification_type": "ps_declined",
  "settings": {
    "project_id": "18404",
    "merchant_id": "2340"
  },
  "user": {
    "ip": "127.0.0.1",
    "email": "email@example.com",
    "id": "1234567",
    "country": "US"
  },
  "transaction": {
    "id": "1",
    "dry_run": "1",
    "payment_method": "1"
  },
  "refund_details": {
    "author": "support@xsolla.com",
    "code": "8",
    "reason": "Cancellation by the PS request",
    "reason_detail": "Insufficient funds"
  }
}'

Response samples

application/json

{"error": {"code": "INVALID_USER",
"message": "Invalid user"
}
}