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

# whatsapp.payment.updated

> Occurs when a WhatsApp payment transaction changes.

Use `whatsapp.payment.updated` to handle this event at your webhook endpoint.

## Triggers

Occurs when a WhatsApp payment transaction changes.

Subscribe to `whatsapp.payment.updated` when you [configure your webhook endpoint](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

## Syntax

YCloud sends an HTTP `POST` request to your configured webhook URL. The following shape shows one payload variant. Angle-bracket values are placeholders; their types are listed under **Parameters**. Optional fields and other variants are described below.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "<ID>",
  "type": "whatsapp.payment.updated",
  "apiVersion": "<API_VERSION>",
  "createTime": "<CREATE_TIME>",
  "whatsappPayment": {
    "wabaId": "<WABA_ID>",
    "referenceId": "<REFERENCE_ID>",
    "status": "<STATUS>",
    "transactions": [
      {
        "id": "<ID>",
        "type": "<TYPE>",
        "status": "<STATUS>",
        "createdTimestamp": "<CREATED_TIMESTAMP_VALUE>",
        "updatedTimestamp": "<UPDATED_TIMESTAMP_VALUE>",
        "amount": {
          "value": "<VALUE_VALUE>",
          "offset": "<OFFSET_VALUE>"
        },
        "currency": "<CURRENCY>",
        "methodType": "<METHOD_TYPE>",
        "error": {
          "code": "<CODE>",
          "reason": "<REASON>"
        }
      }
    ]
  }
}
```

## Parameters

Validate the `YCloud-Signature` HTTP header before you process the JSON body. See [signature validation](https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/configure-webhooks.md).

### Event envelope

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Unique ID for the event. Minimum length: `6`. Maximum length: `128`. |
| `type` | string | Yes | Always `whatsapp.payment.updated`. |
| `apiVersion` | string | Yes | The API version used to render this event. |
| `createTime` | string (date-time) | Yes | The time at which this event was created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`. |

### Event payload

| Parameter | Type | Required | Description |
| - | - | - | - |
| `whatsappPayment` | object | No | Event-specific `whatsappPayment` payload. |

The four common envelope fields are required. Payload fields depend on the event variant. In each object table, **Required** applies when its parent object is present. Optional fields can be omitted; a sample does not make a field required.

#### whatsappPayment

| Parameter | Type | Required | Description |
| - | - | - | - |
| `wabaId` | string | Yes | WhatsApp Business Account ID. |
| `referenceId` | string | Yes | Unique identifier for the payment provided by the business. It is case sensitive and cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 35 characters. |
| `status` | string | Yes | Status of this payment.<ul><li>`captured`: Indicates the payment is successfully completed.</li><li>`pending`: Indicates the user attempted but yet to receive success transactions signal.</li></ul> |
| `transactions` | object\[] | No | Contains the latest transaction attempt for this payment. |

> [accordion] whatsappPayment.transactions\[]
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `id` | string | Yes | Transaction ID. |
> | `type` | string | Yes | The payment type for this transactions. One of `billdesk`, `razorpay`, `payu`, or `zaakpay`. |
> | `status` | string | Yes | The status of the transaction. One of `pending`, `success` or `failed`. |
> | `createdTimestamp` | integer (int64) | Yes | Time when transaction was created in epoch milliseconds. |
> | `updatedTimestamp` | integer (int64) | Yes | Time when transaction was last updated in epoch milliseconds. |
> | `amount` | object | Yes | Total amount that user has paid. |
> | `currency` | string | Yes | The currency for this payment. Currently the only supported value is `INR`. |
> | `methodType` | string | No | Describes the type of payment method used by consumer to pay for the order. Can be one of `upi`, `card`, `wallet`, or `netbanking`. The payment method information might not be available for failed payments. |
> | `error` | object | No | The payment error details might not be available for all payments attempts. |

> [accordion] whatsappPayment.transactions\[].amount
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `offset` | integer (int32) | Yes | Must be `100` for `INR`. |
> | `value` | integer (int32) | Yes | Positive integer representing the amount value multiplied by offset. For example, ₹12.34 has value 1234. |
> | `description` | string | No | Use only for `tax`, `shipping`, or `discount`. Description of the amount. Max character limit is 60 characters.Maximum length: `60`. |
> | `discount_program_name` | string | No | Use only for `discount`. Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters.Maximum length: `60`. |

> [accordion] whatsappPayment.transactions\[].error
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `code` | string | Yes | Describes the payment failure reason that generated by payment gateway and Meta transmits this to partners. |
> | `reason` | string | Yes | Describes the payment failure reason in plain text that is generated by payment gateway and Meta transmits this to partners. |

## Example

The following JSON is the body delivered to your receiver. IDs, phone numbers, and other account values are illustrative.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.payment.updated",
  "apiVersion": "v2",
  "createTime": "2024-10-10T07:08:00.000Z",
  "whatsappPayment": {
    "wabaId": "WABA-ID",
    "referenceId": "<reference-id>",
    "status": "captured",
    "transactions": [
      {
        "id": "<transaction-id>",
        "type": "razorpay",
        "status": "success",
        "createdTimestamp": 1728544066000,
        "updatedTimestamp": 1728544066000,
        "amount": {
          "value": 21000,
          "offset": 100
        },
        "currency": "INR",
        "methodType": "upi | card | wallet | netbanking",
        "error": {
          "code": "error-code",
          "reason": "error-reason"
        }
      }
    ]
  }
}
```

After verifying the signature and durably accepting the event, return a `2xx` response. Process slow work asynchronously.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

For scenario walkthroughs, see [annotated examples](https://docs.ycloud.com/en/api-reference/guides/examples/webhook-examples/whatsapp-payment-updated-webhook-examples).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.