# Payment

When a user completes a payment,  Xsolla sends payment details in a webhook with the payment type to the webhook URL.

The expected response codes are described in the Responses section, but you can use other response codes as well:


    
    
        Response code
        Description
    
    
    
    
        200, 201, 204
        A successful response.
    
    
        4xx
        An error occurred. For example, if the specified user was not found or an invalid signature was passed.
    
    
        5xx
        A temporary server error. When this response is received,  Xsolla will automatically retry sending the webhook, gradually increasing the interval between attempts until your listener confirms receiving. The maximum number of retries is 12 retry attempts over a 48-hour period.
    
    


When you save the webhook URL in Publisher Account, you can also set up receiving additional information in webhooks.


  Note
  If you registered in Publisher Account on or before January 22, 2025, you can find the toggles in your project in the Settings > Webhooks > Testing > Payments > Advanced settings section.



  
    
        Toggle
        Description
    
  
  
    
        Show info about the saved payment account
        Information about the saved payment method is passed in the payment_account custom object.
    
    
        Show info about transactions via saved payment methods
        Information is passed in the following custom parameters of the webhook:saved_payment_method:0 — the saved payment method was not used1 —  the payment method was saved when making the current payment2 — the previously saved payment method is usedpayment_type:1 — one-time payment2 — recurring payment
    
    
        Add order object to webhook
        Information about the order is passed in the order object of the Payment webhook.
    
    
        Send only necessary user parameters without sensitive data
        Only the following information about the user is passed in the webhook:IDcountry
    
    
        Show card BIN and suffix
        The following information about the bank card number is passed in the webhook:the first 6 digits in the card_bin parameterthe last 4 digits in the card_suffix
    
    
        Show card brand
        The brand of the card used for making the payment. For example, Mastercard or Visa.
    
  



  Notice
  The set of fields sent in a webhook depends on:the advanced settings configured in Publisher Accountthe custom settings configured on the Xsolla sideIf you have any questions, contact your Customer Success Manager or email to csm@xsolla.com.

Endpoint: POST payment
Version: 1.0

## Request fields (application/json):

  - `notification_type` (string, required)
    Notification type.

  - `settings` (object)
    Custom project settings (object).

  - `settings.project_id` (integer)
    Project ID. You can find this parameter in your [Publisher Account](https://publisher.xsolla.com/) next to the name of the project.

  - `settings.merchant_id` (integer)
    Merchant ID.

  - `user` (object)
    User details (object).

  - `user.ip` (string)
    User IP.

  - `user.phone` (string)
    User phone.

  - `user.email` (string)
    User email.

  - `user.id` (string, required)
    User ID.

  - `user.name` (string)
    Username.

  - `user.country` (string)
    User’s country. Two-letter uppercase [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.

  - `user.zip` (string)
    User’s ZIP or postal code.

  - `purchase` (object)
    Purchase details (object).

  - `purchase.checkout` (object)
    Checkout details (object).

  - `purchase.checkout.currency` (string)
    Currency. Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).

  - `purchase.checkout.amount` (number)
    Purchase amount.

  - `purchase.subscription` (object)
    Subscription details (object).

  - `purchase.subscription.plan_id` (string)
    Plan ID (external if the plan was created via API).

  - `purchase.subscription.subscription_id` (integer)
    Subscription ID in Xsolla database.

  - `purchase.subscription.product_id` (string)
    Product ID (if sent in the access token).

  - `purchase.subscription.tags` (array)
    Plan tags.

  - `purchase.subscription.date_create` (string)
    Subscription creation date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `purchase.subscription.date_next_charge` (string)
    Next billing date. Date and time per [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

  - `purchase.subscription.amount` (number)
    Price in real currency.

  - `purchase.gift` (object)
    Gift details (object).

  - `purchase.gift.giver_id` (string)
    Giver ID.

  - `purchase.gift.receiver_id` (string)
    Gift recipient ID.

  - `purchase.gift.receiver_email` (string)
    Gift recipient email.

  - `purchase.gift.message` (string)
    Message from the giver.

  - `purchase.gift.hide_giver_from_receiver` (string)
    Whether to hide the giver identity from the recipient.

  - `purchase.total` (object, required)
    Total price of purchase (object).

  - `purchase.total.amount` (number)
    Total payment amount.

  - `purchase.promotions` (array)
    Promotions applied to this transaction.

  - `purchase.promotions.technical_name` (string)
    Technical name of the promotion.

  - `purchase.promotions.id` (integer)
    Promotion ID.

  - `purchase.coupon` (object)
    Coupon details (object; if a coupon was used when creating the subscription).

  - `purchase.coupon.coupon_code` (string)
    Coupon code.

  - `purchase.coupon.campaign_code` (string)
    Campaign code.

  - `purchase.order` (object)
    Object that contains information about an order. To receive this information, set the Add order object to webhook toggle to On in [Publisher Account](https://publisher.xsolla.com/) in the Project settings > Webhooks > Advanced settings section.

  - `purchase.order.id` (integer)
    Order ID.

  - `purchase.order.lineitems` (array)
    Array of parameters that contain information about the items.

  - `purchase.order.lineitems.sku` (string)
    Item SKU.

  - `purchase.order.lineitems.quantity` (integer)
    Item quantity.

  - `purchase.order.lineitems.price` (object)
    Object that contains information about an item price.

  - `purchase.order.lineitems.price.currency` (string)
    Currency of the item price.

  - `purchase.order.lineitems.price.amount` (number)
    Total price of the item in the selected currency.

  - `transaction` (object, required)
    Transaction details (object).

  - `transaction.id` (integer)
    Transaction ID.

  - `transaction.external_id` (string)
    Transaction external ID. Refer to the [FAQs](/doc/pay-station/references/faq/#faq_payments_q_new_transaction_external_id) for detailed information.

  - `transaction.payment_date` (string)
    Date of payment.

  - `transaction.payment_method` (integer)
    Payment method ID.

  - `transaction.payment_method_name` (string)
    Payment method name.

  - `transaction.payment_method_order_id` (string)
    Payment ID in the payment system.

  - `transaction.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.

  - `transaction.agreement` (integer)
    Agreement ID.

  - `payment_details` (object, required)
    Payment details (object).

  - `payment_details.payment` (object)
    Amount paid by the user (object).

  - `payment_details.payment.amount` (number)
    Amount.

  - `payment_details.payment_method_sum` (object)
    Amount debited from the payment system.

  - `payment_details.xsolla_balance_sum` (object)
    Amount debited from Xsolla balance.

  - `payment_details.payout` (object)
    Payout details (object).

  - `payment_details.vat` (object)
    VAT details (object; EU only).

  - `payment_details.vat.percent` (number)
    VAT rate.

  - `payment_details.payout_currency_rate` (string)
    Exchange rate between payment and payout currencies.

  - `payment_details.country_wht` (object)
    Withholding tax applied in specific countries due to cross-border transactions (object).

  - `payment_details.country_wht.percent` (number)
    Country withholding tax rate, %.

  - `payment_details.user_acquisition_fee` (object)
    Total amount of user acquisition fees deducted for the purchases made via affiliate networks and influencers (object).

  - `payment_details.user_acquisition_fee.percent` (number)
    User acquisition fee rate, %.

  - `payment_details.xsolla_fee` (object)
    Xsolla fee (object).

  - `payment_details.payment_method_fee` (object)
    Payment system fee.

  - `payment_details.sales_tax` (object)
    Sales tax (object; USA and Canada only).

  - `payment_details.sales_tax.percent` (number)
    Sales tax rate.

  - `payment_details.direct_wht` (object)
    Direct withholding tax.

  - `payment_details.direct_wht.percent` (number)
    Direct withholding tax rate.

  - `payment_details.repatriation_commission` (object)
    Object with data on repatriation costs, imposed on Xsolla by third parties.

  - `custom_parameters` (object)
    Your custom parameters.

## Response 400 fields (application/json):

  - `error` (object)

  - `error.code` (string)

  - `error.message` (string)


## Response 204 fields

## Response 500 fields