> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit Card Webhook

> Receive real-time notifications about credit card transaction status changes

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](/api-reference/credit-card/create-charge):

```json theme={null}
{
  "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

<ResponseField name="id" type="string">
  Unique charge identifier
</ResponseField>

<ResponseField name="key" type="string">
  Unique key for payment page access
</ResponseField>

<ResponseField name="clientId" type="integer">
  Your client ID in the WEpayments system
</ResponseField>

<ResponseField name="clientName" type="string">
  Your registered company name
</ResponseField>

<ResponseField name="buyerName" type="string">
  Name of the customer making the purchase
</ResponseField>

<ResponseField name="buyerDocument" type="string">
  Customer's document number (CPF/CNPJ)
</ResponseField>

<ResponseField name="buyerEmail" type="string">
  Customer's email address
</ResponseField>

<ResponseField name="customNumber" type="string">
  Your custom reference number for this transaction
</ResponseField>

<ResponseField name="ourNumber" type="integer">
  WEpayments internal transaction number
</ResponseField>

<ResponseField name="status" type="object">
  Current transaction status

  <Expandable title="status properties">
    <ResponseField name="status.id" type="integer">
      Status ID
    </ResponseField>

    <ResponseField name="status.name" type="string">
      Status name (e.g., "Created", "Paid", "Rejected")
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="typePayin" type="string">
  Payment method type - will be `"credit-card"` for credit card transactions
</ResponseField>

<ResponseField name="amountCents" type="integer">
  Transaction amount in cents
</ResponseField>

<ResponseField name="paidAmountCents" type="integer">
  Amount actually paid in cents (null if not yet paid)
</ResponseField>

<ResponseField name="paidAt" type="string">
  Timestamp when payment was confirmed (ISO 8601 format)
</ResponseField>

<ResponseField name="expiresAt" type="string">
  Transaction expiration timestamp (ISO 8601 format)
</ResponseField>

<ResponseField name="createdAt" type="string">
  Transaction creation timestamp (ISO 8601 format)
</ResponseField>

<ResponseField name="statusHistory" type="array">
  Array of status changes with timestamps
</ResponseField>

<ResponseField name="refundMode" type="string">
  Refund configuration mode
</ResponseField>

<ResponseField name="refundAmountCents" type="integer">
  Total amount refunded in cents
</ResponseField>

<ResponseField name="payinRefunds" type="array">
  Array of refund records if any refunds were processed
</ResponseField>

<ResponseField name="payin_substatus" type="string">
  Additional status information if applicable
</ResponseField>

## Example Payload

```json theme={null}
{
  "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](/credit-card/rejection-status) for details)
* **Refunded** → Payment refunded to customer
* **Canceled** → Transaction canceled

## Related Resources

<CardGroup cols={2}>
  <Card title="Create Charge" icon="credit-card" href="/api-reference/credit-card/create-charge">
    Create a new credit card charge
  </Card>

  <Card title="Rejection Status" icon="circle-xmark" href="/credit-card/rejection-status">
    Understanding rejection reasons
  </Card>

  <Card title="Test Cards" icon="vial" href="/credit-card/test-cards">
    Test cards for development
  </Card>
</CardGroup>