Xsolla-logoXsolla Developers
ou
Conta de Distribuidor

PagamentoWebhook POST

Quando um usuário completa um pagamento, a Xsolla envia os dados do pagamento em um webhook com o tipo payment ao URL do webhook.

Se uma resposta com um código 5xx for recebida, a Xsolla reenvia um webhook com um intervalo de tempo maior até que seu ouvinte confirme o recebimento. O número máximo de tentativas é 12.

Ao salvar o URL do webhook na Conta de Distribuidor, você pode conceder permissões para receber informações detalhadas nos webhooks. Para fazer isso, defina as opções necessárias como ativas na Conta de Distribuidor na seção Project settings > Webhooks > Advanced settings.

Observação

Se você se registrou na Conta de Distribuidor no dia 22 de janeiro de 2025 ou antes, você encontrará as opções na seção Project settings > Webhooks > Testing > Payments > Advanced settings.

Opção Descrição
Exibir informações sobre a conta de pagamento salva As informações sobre a forma de pagamento salva são passadas no objeto personalizado payment_account.
Exibir informações sobre transações pelos métodos de pagamento salvos

As informações são passadas nos seguintes parâmetros personalizados do webhook:

  • saved_payment_method:
    • 0 — o método de pagamento guardado não foi utilizado
    • 1 — o método de pagamento foi salvo ao efetuar o pagamento atual
    • 2 — o método de pagamento previamente guardado é utilizado
  • payment_type:
    • 1 — pagamento único
    • 2 — pagamento recorrente
Adicionar objeto de ordem ao webhook As informações sobre o pedido são passadas no objeto order do webhook Pagamento.
Enviar apenas os parâmetros de usuário necessários sem dados confidenciais

Somente as seguintes informações sobre o usuário são passadas no webhook:

  • ID
  • país
Exibir BIN e sufixo do cartão

As seguintes informações sobre o número do cartão bancário são passadas no webhook:

  • os primeiros 6 dígitos no parâmetro card_bin
  • os últimos 4 dígitos no card_suffix
Exibir marca do cartão A bandeira do cartão utilizado para efetuar o pagamento. Por exemplo, Mastercard ou Visa.

Aviso

O conjunto de campos enviados em um webhook depende de:

  • as configurações avançadas definidas na Conta de Distribuidor
  • as configurações personalizadas definidas no lado da Xsolla

Se tiver alguma dúvida, entre em contato com seu Gerente de Sucesso do Cliente ou envie um e-mail para csm@xsolla.com.

Request
Request Body schema: application/json
notification_type
required
string

Tipo de notificação.

required
object

Detalhes da transação (objeto).

agreement
integer

ID do contrato.

dry_run
integer

Transação de teste. O parâmetro tem valor 1 se for uma transação de teste ou não for enviado se a transação for real.

external_id
string

ID de transação externo. Consulte o FAQs para saber mais.

id
integer

ID de transação.

payment_date
string

Data de pagamento.

payment_method
integer

ID de método de pagamento.

payment_method_name
string

Nome do método de pagamento.

payment_method_order_id
string

ID de pagamento no sistema de pagamento.

required
object

Detalhes de pagamento (objeto).

object

Imposto retido na fonte aplicado em países específicos devido a transações internacionais (objeto).

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

percent
number <float>

Taxa de retenção na fonte do país, %.

object

Imposto retido direto na fonte.

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

percent
number <float>

Alíquota de retenção direta na fonte.

object

Valor pago pelo usuário (objeto).

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

object

Taxa do sistema de pagamento.

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

object

Valor debitado do sistema de pagamento.

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

object

Dados de pagamento (objeto).

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

payout_currency_rate
string

Taxa de câmbio entre as moedas de pagamento e remuneração.

object

Objeto com dados sobre os custos de repatriamento, imposto à Xsolla por terceiros.

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

object

Imposto sobre vendas (objeto; apenas EUA e Canadá).

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

percent
number <float>

Alíquota de imposto sobre vendas.

object

Valor total das taxas de aquisição de usuários deduzidas para as compras feitas por meio de redes afiliadas e influenciadores (objeto).

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

percent
number <float>

Proporção de taxa de aquisição de usuários, %.

object

Dados do IVA (objeto; apenas na UE).

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

percent
number <float>

Taxa de IVA.

object

Valor debitado do saldo Xsolla.

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

object

Taxa Xsolla (objeto).

amount
number <float>

Quantia.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

custom_parameters
object

Seus parâmetros personalizados.

object

Dados da compra (objeto).

required
object

Preço total de compra (objeto).

amount
number <float>

Valor total do pagamento.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

object

Dados do checkout (objeto).

amount
number <float>

Valor da compra.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

object

Dados do cupom (objeto; se um cupom foi usado ao criar a assinatura).

campaign_code
string

Código da campanha.

coupon_code
string

Código de cupom.

object

Detalhes do presente (objeto).

giver_id
string

ID do doador.

hide_giver_from_receiver
string

Se a identidade do doador deve ou não ser ocultada do recipiente.

message
string

Mensagem do doador.

receiver_email
string

E-mail do recipiente do presente.

receiver_id
string

ID do recipiente do presente.

object

Objeto que contém informações sobre um pedido. Para receber essas informações, defina a opção Adicionar objeto do pedido ao webhook como On na Conta de Distribuidor na seção Project settings > Webhooks > Advanced settings.

id
integer

ID do pedido.

object

Objeto que contém informações sobre um item.

object

Objeto que contém informações sobre um preço de item.

amount
number <float>

Preço total do item na moeda selecionada.

currency
string

Moeda do preço do item.

quantity
integer

Quantidade do item.

sku
string

SKU do item.

Array of objects

Promoções aplicadas a esta transação.

Array
id
integer

ID da promoção.

technical_name
string

Nome técnico da promoção.

object

Dados da assinatura (objeto).

amount
number <float>

Preço em moeda real.

currency
string

Moeda. Código da moeda de três letras de acordo com o ISO 4217.

date_create
string

Data de criação da assinatura. Data e hora de acordo com o ISO 8601.

date_next_charge
string

Data da próxima cobrança. Data e hora de acordo com o ISO 8601.

plan_id
string

ID do plano (externo se o plano foi criado via API).

product_id
string

ID do produto (se enviado no token de acesso).

subscription_id
integer

ID de assinatura no banco de dados Xsolla.

tags
Array of strings

Rótulos do plano.

object

Configurações personalizadas do projeto (objeto).

merchant_id
integer

ID de comerciante.

project_id
integer

ID do projeto. Você pode encontrar esse parâmetro em sua Conta de Distribuidor ao lado do nome do projeto.

object

Dados do usuário (objeto).

id
required
string

ID de usuário.

country
string

País do usuário. Código de país de duas letras maiúsculas, de acordo com o ISO 3166-1 alpha-2.

email
string

E-mail do usuário.

ip
string

IP do usuário.

name
string

Nome de usuário.

phone
string

Telefone do usuário.

zip
string

CEP ou código postal do usuário.

Responses
204

Retorne para indicar o processamento bem-sucedido.

400

Retorne em caso de erro nas informações fornecidas (por exemplo, um parâmetro obrigatório ausente, falha na autorização, etc.). Nesse caso, o dinheiro do usuário é debitado, mas a compra falha. Para fazer um reembolso, entre em contato com o suporte ao cliente Xsolla via support@xsolla.com.

500

Retorne para indicar erros temporários com seus servidores.

Request samples 
curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type": "payment",
    "settings": {
      "project_id": 18404,
      "merchant_id": 2340
    },
    "purchase": {
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": 853
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        },
        "order": {
          "id": 1234
          "lineitems": [
          {
            "sku": "com.xsolla.item_1",
            "quantity": 1,
            "price": {
              "currency": "EUR",
              "amount": 6.5
              }
          }
          ]
          }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "US"
    },
    "transaction": {
        "id": 1,
        "external_id": 1,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_name": "PayPal",
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0,
            "percent": 20
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "payout_currency_rate": "1",
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "country_wht": {
            "currency": "USD",
            "amount": 2,
            "percent": 10
        },
        "user_acquisition_fee": {
            "currency": "USD",
            "amount": 2,
            "percent": 1
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": 10
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}'
Response samples
application/json
{
  • "error": {
    }
}
System statusAll services operational

Privacy Settings

Privacy PolicyEnd User License Agreement© 2006–2025 Xsolla Inc.