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

​
How It Works

  1. Configure your callback URL when creating the credit card charge using the callbackUrl parameter
  2. Receive notifications automatically when transaction status changes
  3. Process the payload containing the complete transaction details
  4. Return a 200 OK response to acknowledge receipt

​
Setting Up Webhooks

To receive webhook notifications for credit card transactions, include the callbackUrl parameter when creating a charge: 
{
  "callbackUrl": "https://your-domain.com/webhooks/credit-card",
  "customNumber": "ORDER-12345",
  "title": {
    "expireDate": "2024-12-31T23:59:59",
    "amountInCents": 10000,
    "instructions": "Payment for order #12345"
  },
  "buyer": { ... },
  "sender": { ... }
}
Each charge can have its own callback URL, allowing you to route notifications to different endpoints based on your needs.

​
Webhook Payload

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

​
Response Fields

​
id
string
Unique charge identifier
​
key
string
Unique key for payment page access
​
clientId
integer
Your client ID in the WEpayments system
​
clientName
string
Your registered company name
​
buyerName
string
Name of the customer making the purchase
​
buyerDocument
string
Customer’s document number (CPF/CNPJ)
​
buyerEmail
string
Customer’s email address
​
customNumber
string
Your custom reference number for this transaction
​
ourNumber
integer
WEpayments internal transaction number
​
status
object
Current transaction status
​
typePayin
string
Payment method type - will be "credit-card" for credit card transactions
​
amountCents
integer
Transaction amount in cents
​
paidAmountCents
integer
Amount actually paid in cents (null if not yet paid)
​
paidAt
string
Timestamp when payment was confirmed (ISO 8601 format)
​
expiresAt
string
Transaction expiration timestamp (ISO 8601 format)
​
createdAt
string
Transaction creation timestamp (ISO 8601 format)
​
statusHistory
array
Array of status changes with timestamps
​
refundMode
string
Refund configuration mode
​
refundAmountCents
integer
Total amount refunded in cents
​
payinRefunds
array
Array of refund records if any refunds were processed
​
payin_substatus
string
Additional status information if applicable

​
Example Payload

{
  "id": "28018",
  "key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8",
  "clientId": 1,
  "clientName": "Your Company",
  "buyerName": "Maria da Silva",
  "buyerDocument": "34960826312",
  "buyerEmail": "buyer-email@wepayments.com.br",
  "customNumber": "YOUR-CODE1234",
  "ourNumber": 17530,
  "status": {
    "id": 2,
    "name": "Paid"
  },
  "typePayin": "credit-card",
  "amountCents": 8652,
  "paidAmountCents": 8652,
  "paidAt": "2024-02-21T19:20:00.000000Z",
  "expiresAt": "2024-12-31T23:59:59",
  "createdAt": "2024-02-21T19:15:00.000000Z",
  "statusHistory": [
    {
      "status": {
        "id": 1,
        "name": "Created"
      },
      "updatedAt": "2024-02-21T19:15:04.000000Z"
    },
    {
      "status": {
        "id": 2,
        "name": "Paid"
      },
      "updatedAt": "2024-02-21T19:20:15.000000Z"
    }
  ],
  "refundMode": "FULL_REFUND_CLIENT",
  "refundAmountCents": 0,
  "payinRefunds": [],
  "payin_substatus": null
}

​
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

​
Common Status Updates

You’ll receive webhook notifications for these status changes:
  • Created → Transaction initiated
  • Paid → Payment successfully processed
  • Rejected → Payment declined (see Rejection Status for details)
  • Refunded → Payment refunded to customer
  • Canceled → Transaction canceled

Create Charge

Create a new credit card charge

Rejection Status

Understanding rejection reasons

Test Cards

Test cards for development