Payin Webhook - WEpayments API

Webhooks allow you to receive automatic notifications about payin events in real-time. When a payin status changes, WEpayments will send a POST request to your registered webhook URL with the updated transaction data.

How It Works

Configure your notification URL when creating the payin charge using the notification_url parameter
Receive notifications automatically when payin status changes
Process the payload containing the complete payin details
Return a 200 OK response to acknowledge receipt

Webhooks are sent only for final statuses: Credited, Canceled, Rejected

Setting Up Webhooks

To receive webhook notifications for payin transactions, include the notification_url parameter when creating a charge:

{
  "invoice": "ORDER-12345",
  "notification_url": "https://your-domain.com/webhooks/payin",
  "payment_method": "pix",
  "amount": 10000,
  "currency": "BRL",
  "country": "BR",
  "buyer": { ... }
}

The notification URL is defined in the notification_url field in the request body when creating a charge. Each charge can have its own notification URL, allowing you to route notifications to different endpoints based on your needs.

Webhook Payload

When a payin status changes, you’ll receive a POST request with the following data:

Response Fields

integer

Payin IDExample: 113589233

hash

string

Unique hash identifier for the payin transactionExample: 54a3cbc66f4ec54a10826edc62ff3f8f8f706c5c54a9db22e1f57fcfff4516d8

invoice

string

Payin invoiceExample: eb21ce52-2897-475b-85af-a5201f4035bf

end_to_end

string

Payin end-to-end identifierExample: E12345678202603191234567890AB1

status

object

Object that contains the current status of your payin.

Show Status Object

integer

Current status ID of your payinExample: 4

name

string

Name of the current status of your payinExample: Credited

status_detail

object

This object will only be returned if the payin is rejected and the merchant is using the “Account Mismatch” functionality. It provides more details on the reason for the rejection.

Show Status Detail Object

code

string

Code that represents the reason for the rejectionExample: WE0001See Status Detail Codes table below for all possible values.

detail

string

Explanation of the reason for the rejectionExample: The payment was made from an unregistered account.

updated_at

string

Last update of your payin.Format: <date-time>Example: 2024-09-09T20:55:56.000000Z

metadata

object

Additional metadata about the payment.

Show Metadata Object

paid_amount

number

Amount paid by the end user.

Since the paid_amount parameter contains sensitive financial information, we recommend considering this data only if you are verifying the webhook signature.

Example: 97

payer

object

Information about the payer of the payin.

Show Payer Object

document

string

Payer’s document (CPF/CNPJ)

bank_payer

object

Information about the end user’s bank account used to pay the QR Code.

Show Bank Payer Object

name

string

Bank nameExample: 033 - BCO SANTANDER (BRASIL) S.A.

bank_ispb

string

Bank ISPB code

bank_account

string

Bank account number

bank_branch

string

Bank branch (agência)

bank_account_type

string

Account type (e.g. CACC for checking account)

Example Payload

{
  "id": 123456789,
  "hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "invoice": "ORDER-12345",
  "end_to_end": "E12345678202603191234567890AB1",
  "status": {
    "id": 4,
    "name": "Credited"
  },
  "metadata": {
    "paid_amount": 97,
    "payer": {
      "document": "12345678900"
    },
    "bank_payer": {
      "name": "033 - BCO SANTANDER (BRASIL) S.A.",
      "bank_ispb": "60746948",
      "bank_account": "12345678",
      "bank_branch": "1234",
      "bank_account_type": "CACC"
    }
  },
  "updated_at": "2026-03-19T15:13:18.000000Z"
}

Status Codes

Common payin status codes:

Status ID	Status Name	Description
1	Created	Charge has been created
2	Canceled	Charge canceled due to expiration
3	Rejected	Charge rejected due to compliance
4	Paid	Charge successfully paid
5	Credited	Amount is paid and available for withdrawal
6	Drop_requested	Cancellation requested

See Payin Status Flow for detailed status information.

Status Detail Codes

When a PIX transaction is rejected, the status_detail.code field provides specific information about the rejection reason:

Code	Description
`reason_payer_divergence`	CPF mismatch
`reason_payer_restriction_deceased_holder`	CPF restriction: deceased holder
`reason_payer_restriction_canceled`	CPF restriction: canceled document
`reason_payer_restriction_suspended`	CPF restriction: suspended document
`reason_payer_pending_regularization`	CPF restriction: pending regularization
`reason_payer_restriction_unknown`	CPF restriction: unknown document
`gl_cpf_payer_restriction_underage`	CPF restriction: underage (Brazilian law)
`reason_payer_restriction_age_above_limit`	Restriction: age above limit (> 80 years)
`pending_challenge`	Pending challenge
`reason_payer_restriction_receita`	CPF restriction (Tax Authority)
`payer_restriction_high_risk`	CPF high risk
`pending_review_manual`	Payment created; awaiting manual review
`payer_restriction`	Rejected per compliance policy
`reason_payer_restriction_pep`	PEP (Politically Exposed Person)
`reason_payer_restriction_list_restrict`	CPF on restriction list
`reason_payer_restriction_cpf_irregular`	Irregular CPF
`reason_payer_restriction_judicial_block`	Judicial block
`reason_payer_restriction_partners_and_ownership`	Certified restriction (partners/ownership)
`reason_payer_restriction_ofac`	CPF on OFAC list
`reason_payer_restriction_interpol`	CPF on INTERPOL list
`reason_payer_restriction_onu`	CPF on UN list
`reason_payer_restriction_euro`	CPF on European restriction list
`WE0001`	The payment was made from an unregistered account
`WE0002`	The payment was made from an unauthorized institution
`reason_payer_restriction_pld`	KYC restriction

These codes are only returned when the payin status is Rejected and the merchant has the “Account Mismatch” functionality enabled.

Webhook Endpoint Requirements

Your webhook endpoint must:

Accept POST requests - All webhook notifications are sent via POST
Use HTTPS - Only secure HTTPS URLs are accepted
Return 200 OK - Respond with a 200 status code within 5 seconds
Be publicly accessible - The endpoint must be reachable from the internet

Retry Policy

If your endpoint responds with a failure (status code different from 200), 15 retry attempts will be made to deliver the webhook notification.

Best Practices

Always Respond 200 OK: Your endpoint must respond with HTTP 200 to acknowledge receipt.

Validate Webhook Signature: Always validate the webhook signature to ensure it’s from WEpayments. See Webhook Signature Documentation for details.

Verify paid_amount: The paid_amount field represents the actual amount paid by the customer and is important to consider for reconciliation.

Status Flow

Understand payin status lifecycle

​How It Works

​Setting Up Webhooks

​Webhook Payload

​Response Fields

​Example Payload

​Status Codes

​Status Detail Codes

​Webhook Endpoint Requirements

​Retry Policy

​Best Practices

​Related Resources

Status Flow

How It Works

Setting Up Webhooks

Webhook Payload

Response Fields

Example Payload

Status Codes

Status Detail Codes

Webhook Endpoint Requirements

Retry Policy

Best Practices

Related Resources