Skip to main content
POST
https://your.endpoint.to.notify
Callback Charge
curl --request POST \
  --url https://your.endpoint.to.notify/ \
  --header 'Authorization: Bearer <token>'
{
  "id": 123,
  "invoice": "<string>",
  "status": {
    "id": 123,
    "name": "<string>"
  },
  "status_detail": {
    "code": "<string>",
    "detail": "<string>"
  },
  "updated_at": "<string>",
  "metadata": {
    "paid_amount": 123,
    "payer": {
      "bank_payer": {}
    }
  }
}
Endpoint: POST https://your.endpoint.to.notifyThis is your endpoint where WEpayments will send notifications about payin status changes.

​
Response

You should respond with 200 OK to acknowledge receipt of the webhook.

​
Body

The webhook payload contains the following fields:
​
id
integer
Cash-in IDExample: 49339
​
invoice
string
Cash-in invoiceExample: eb21ce52-2897-475b-85af-a5201f4035bf
​
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.

​
Webhook Payload Example

{
  "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 Cash-in 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.

​
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.

Create Charge

Create PIX or Boleto charges

Status Flow

Understand payin status lifecycle

Rejection Reasons

Learn about rejection codes

Get Charge

Query charge details

Webhook Signature

Validate webhook signatures