Skip to main content
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

  1. Configure your notification URL when creating the payin charge using the notification_url parameter
  2. Receive notifications automatically when payin status changes
  3. Process the payload containing the complete payin details
  4. 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

​
id
integer
Payin IDExample: 49339
​
invoice
string
Payin invoiceExample: eb21ce52-2897-475b-85af-a5201f4035bf
​
end_to_end
string
Payin end-to-endExample: END-TO-END-ID
​
status
object
Object that contains the current status of your payin.
​
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.
​
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.

​
Example Payload

{
  "id": 49339,
  "invoice": "eb21ce52-2897-475b-85af-a5201f4035bf",
  "status": {
    "id": 7,
    "name": "Rejected"
  },
  "status_detail": {
    "code": "WE0001",
    "detail": "The payment was made from an unregistered account."
  },
  "updated_at": "2024-09-09T20:55:56.000000Z",
  "metadata": {
    "paid_amount": 9.9,
    "payer": {
      "bank_payer": {
        "bank_code": "001",
        "branch": "1234",
        "account": "12345678",
        "account_type": "checking",
        "holder_name": "Customer Name",
        "holder_document": "12345678900"
      }
    }
  }
}

​
Status Codes

Common payin status codes:
Status IDStatus NameDescription
1CreatedCharge has been created
2CanceledCharge canceled due to expiration
3RejectedCharge rejected due to compliance
4PaidCharge successfully paid
5CreditedAmount is paid and available for withdrawal
6Drop_requestedCancellation 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:
CodeDescription
reason_payer_divergenceCPF mismatch
reason_payer_restriction_deceased_holderCPF restriction: deceased holder
reason_payer_restriction_canceledCPF restriction: canceled document
reason_payer_restriction_suspendedCPF restriction: suspended document
reason_payer_pending_regularizationCPF restriction: pending regularization
reason_payer_restriction_unknownCPF restriction: unknown document
gl_cpf_payer_restriction_underageCPF restriction: underage (Brazilian law)
reason_payer_restriction_age_above_limitRestriction: age above limit (> 80 years)
pending_challengePending challenge
reason_payer_restriction_receitaCPF restriction (Tax Authority)
payer_restriction_high_riskCPF high risk
pending_review_manualPayment created; awaiting manual review
payer_restrictionRejected per compliance policy
reason_payer_restriction_pepPEP (Politically Exposed Person)
reason_payer_restriction_list_restrictCPF on restriction list
reason_payer_restriction_cpf_irregularIrregular CPF
reason_payer_restriction_judicial_blockJudicial block
reason_payer_restriction_partners_and_ownershipCertified restriction (partners/ownership)
reason_payer_restriction_ofacCPF on OFAC list
reason_payer_restriction_interpolCPF on INTERPOL list
reason_payer_restriction_onuCPF on UN list
reason_payer_restriction_euroCPF on European restriction list
WE0001The payment was made from an unregistered account
WE0002The payment was made from an unauthorized institution
reason_payer_restriction_pldKYC 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

​
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