# About webhooks

Learn about PXP webhooks and supported events.

## Overview

A **webhook** is a real-time notification triggered by a specific event. By subscribing to webhooks, you can automatically receive an update when something happens, rather than having to manually check anything.

### Webhook retries

Occasionally, a webhook notification might fail to deliver. This could be because of a connection timeout occurring or a response taking too long. When this happens, we'll automatically retry the notification up to another 10 times in the 10 seconds following the initial delivery attempt.

### Webhook validations

All webhooks coming from PXP include these HTTP headers:

* `X-Request-Id`
* `X-Signature-Timestamp`
* `X-Signature`


To validate that a webhook was sent by PXP:

1. Concatenate the headers and the request body: `signedDataString = requestIdHeader + signatureTimeStampHeader + requestBody`
2. Convert this string to bytes using UTF8 encoding: `signedData = utf8.getBytes(signedDataString)`
3. Calculate signature by using HMAC with your HMAC key: `calculatedSignature = HMAC(signedData, key)`
4. Validate whether the calculated signature matches the signature received in `"X-Signature"` as Base64:`asBase64(calculatedSignature) == signatureHeader`.


You can configure your HMAC key in the Unity Portal by going to **Merchant setups > Merchant group**, selecting a merchant group, and clicking the **Webhooks** tab.

## Structure

Each webhook event has the same overall structure:

```json
{
  "eventCategory": "string",
  "eventDate": "date-time",
  "eventData": {object},
  "eventOwner": { 
    "merchantGroup": "string",
    "merchant": "string",
    "site": "string"
  }
}
```

| Parameter | Description |
|  --- | --- |
| `eventCategory` | The specific area of payment operations that the event belongs to.Possible values:`authentication``token``transaction``reporting` |
| `eventDate` | The date and time when the event happened, in ISO 8601 format. |
| `eventData` | Details about the event. The structure of this object varies depending on the event. See the [Example event data](#example-event-data) section below for more information. |
| `eventOwner` | Details about the merchant group, merchant, and site that the event is associated with. |


## Supported events

| Event name | Description | Event category |
|  --- | --- | --- |
| [Challenge completed](#challenge-completed)`challenge-completed` | A 3D Secure challenge was completed. | `Authentication` |
| [Transaction authorised](#transaction-authorised)`transaction-authorised` | A card, PayPal, Pay Later, Venmo, or Aeropay transaction was authorised. | `Transaction` |
| [Transaction cancelled](#transaction-cancelled)`transaction-cancelled` | A card, PayPal, Pay Later, Venmo, or Aeropay transaction was cancelled. | `Transaction` |
| [Transaction captured](#transaction-captured)`transaction-captured` | A card, PayPal, Pay Later, Venmo, or Aeropay transaction was captured. | `Transaction` |
| [Transaction created](#transaction-created) `transaction-created` | A PayPal, Pay Later, or Venmo transaction was created. | `Transaction` |
| [Transaction executed](#transaction-executed) `transaction-executed` | A PayPal, Pay Later, or Venmo transaction was approved and executed. | `Transaction` |
| [Transaction refunded](#transaction-refunded) `transaction-refunded` | A card, PayPal, Pay Later, Venmo, or Aeropay transaction was refunded. | `Transaction` |
| [SPEI transaction executed](#spei-transaction-executed)`spei-transaction-order-executed` | A SPEI purchase or payout reached a successful terminal state (`Authorised`). | `Transaction` |
| [SPEI transaction declined](#spei-transaction-declined)`spei-transaction-order-declined` | A SPEI purchase or payout was declined. Purchase maps to `Aborted`; payout maps to `Refused`. | `Transaction` |
| [SPEI transaction expired](#spei-transaction-expired)`spei-transaction-order-expired` | A SPEI purchase or payout expired. | `Transaction` |
| [SPEI transaction failed](#spei-transaction-failed)`spei-transaction-order-failed` | A SPEI purchase or payout failed (`Refused`). | `Transaction` |
| [SPEI transaction refunded](#spei-transaction-refunded)`spei-transaction-order-refunded` | A SPEI refund was confirmed. | `Transaction` |
| [SPEI transaction rejected](#spei-transaction-rejected)`spei-transaction-order-rejected` | A SPEI payout was rejected. | `Transaction` |
| [CVU transaction executed](#cvu-transaction-executed)`cvu-transaction-order-executed` | A CVU deposit or payout reached a successful terminal state (`Authorised`). For deposits, this is the first notice of the transaction. | `Transaction` |
| [CVU transaction declined](#cvu-transaction-declined)`cvu-transaction-order-declined` | A CVU payout was declined (`Refused`). | `Transaction` |
| [CVU transaction expired](#cvu-transaction-expired)`cvu-transaction-order-expired` | A CVU payout expired. | `Transaction` |
| [CVU transaction failed](#cvu-transaction-failed)`cvu-transaction-order-failed` | A CVU payout failed (`Refused`). | `Transaction` |
| [CVU transaction refunded](#cvu-transaction-refunded)`cvu-transaction-order-refunded` | A CVU refund was confirmed. | `Transaction` |
| [CVU transaction rejected](#cvu-transaction-rejected)`cvu-transaction-order-rejected` | A CVU payout was rejected. | `Transaction` |
| [Bre-B transaction executed](#bre-b-transaction-executed)`breb-transaction-order-executed` | A Bre-B deposit or payout reached a successful terminal state (`Authorised`). For deposits, this is the first notice of the transaction. | `Transaction` |
| [Bre-B transaction declined](#bre-b-transaction-declined)`breb-transaction-order-declined` | A Bre-B payout was declined (`Refused`). | `Transaction` |
| [Bre-B transaction expired](#bre-b-transaction-expired)`breb-transaction-order-expired` | A Bre-B payout expired. | `Transaction` |
| [Bre-B transaction failed](#bre-b-transaction-failed)`breb-transaction-order-failed` | A Bre-B payout failed (`Refused`). | `Transaction` |
| [Bre-B transaction refunded](#bre-b-transaction-refunded)`breb-transaction-order-refunded` | A Bre-B refund was confirmed. | `Transaction` |
| [Bre-B transaction rejected](#bre-b-transaction-rejected)`breb-transaction-order-rejected` | A Bre-B payout was rejected. | `Transaction` |
| [Bre-B transaction cross-entry](#bre-b-transaction-cross-entry)`breb-transaction-order-cross-entry` | A Bre-B payout was refused because of a cross-entry outcome (`Refused`). | `Transaction` |
| [FlashFlow transaction executed](#flashflow-transaction-executed)`flashflow-transaction-executed` | A FlashFlow purchase or payout completed successfully (`Authorised`). | `Transaction` |
| [FlashFlow transaction expired](#flashflow-transaction-expired)`flashflow-transaction-expired` | A FlashFlow pay-in expired (`Expired`). | `Transaction` |
| [FlashFlow transaction refused](#flashflow-transaction-refused)`flashflow-transaction-refused` | A FlashFlow payout was refused (`Refused`). | `Transaction` |
| [Payout authorised](#payout-authorised) `payout-authorised` | A payout was authorised. | `Transaction` |
| [User info created](#user-info-created) `user-info-created` | Customer information was created and verified. | `Transaction` |
| [User suspended](#user-suspended)`user-suspended` | An Aeropay user was suspended. | `Transaction` |
| [User activated](#user-activated)`user-activated` | An Aeropay user was activated. | `Transaction` |
| [Scheduled report generated](#scheduled-report-generated)`scheduled-report-generated` | A previously scheduled report was successfully generated and is ready to be downloaded. | `Reporting` |
| [Scheme token created](#scheme-token-created)`scheme-token-created` | A scheme token was successfully created. | `Token` |
| [Scheme token creation error](#scheme-token-creation-error)`scheme-token-creation-error` | An error occurred during the creation of a scheme token. | `Token` |
| [Scheme token card updated](#scheme-token-card-updated)`scheme-token-card-updated` | A scheme token was updated because a card was replaced or renewed. | `Token` |
| [Scheme token disabled](#scheme-token-disabled)`scheme-token-disabled` | A scheme token was disabled. | `Token` |


## Example event data

### Challenge completed

```json
{
  "authenticationId": "5a13aae9-a0b1-4e3d-bcfb-1dbc90b5611f",
  "authenticationState": "AuthenticationSuccessful",
  "transactionStatus": "A",
  "transactionStatusReason": null,
  "directoryServerTransactionId": "5a4d019d-6c96-44c8-a625-636bc35ca0ac",
  "threeDSecureVersion": "2.2.0",
  "electronicCommerceIndicator": "05",
  "authenticationFlow": "Challenge",
  "challengeCancel": null,
  "challengeErrorReporting": null
}
```

### Transaction authorised

```json Card
{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "amounts": {
    "transaction": 30,
    "gratuity": 0,
    "currencyCode": "GBP"
  },
  "merchant": "Unity",
  "site": "UnityPTPOS",
  "transactionMethod": {
    "intent": "Authorisation",
    "fundingType": "Card",
    "entryType": "Instore"
  },
  "approvalCode": "138550",
  "merchantTransactionDate": "2025-04-01T11:41:02.826445+00:00",
  "merchantTransactionId": "310325_m15t9",
  "systemTransactionId": "97f664b6-f0fb-49c9-9404-dd782c0131fc",
  "providerTransactionId": null,
  "fundingData": {
    "card": {
      "cardScheme": "MasterCard",
      "gatewayTokenId": "1b59a988-ae81-45af-911a-b2ca1f199f34",
      "providerResponse": {
        "provider": "pxpfinancial",
        "code": "00",
        "merchantId": "7171910017",
        "electronicCommerceIndicatorAdjustment": "07",
        "merchantAdvice": {}
      }
    }
  }
}
```

```json PayPal
{
  "state": "Authorised",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Authorisation",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_confirm_id_0001",
  "systemTransactionId": "38e1cc67-b1c9-4b46-abda-03ec5caeae8d",
  "providerTransactionId": "95488117F3090464T",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "Paypal"
    }
  }
}
```

```json Pay Later
{
  "state": "Authorised",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Authorisation",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_confirm_paylater_id_0005",
  "systemTransactionId": "4d91b167-fa3d-4d5a-aa6b-ecd5a97a5cae",
  "providerTransactionId": "1B135095DL3382301",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "PayLater"
    }
  }
}
```

```json Venmo
{
  "state": "Authorised",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Authorisation",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_confirm_id_0003",
  "systemTransactionId": "60e41343-6ef2-490f-a679-ae7738b603cf",
  "providerTransactionId": "84V813517U892664E",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "Venmo"
    }
  }
}
```

```json Aeropay
{
  "eventCode": "TXNAP_AUTH",
  "state": "Authorised",
  "merchant": "merchant-1",
  "site": "site-1",
  "merchantTransactionId": "merch-txn-001",
  "merchantTransactionDate": "2026-07-10T08:00:00Z",
  "systemTransactionId": "6b0320d8-b24e-404c-9048-136d83e033f7",
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "USD"
  },
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Aeropay",
      "achStatus": "Approved",
      "isRtp": false,
      "authorisationExpiryDate": "2026-07-17T08:00:00+00:00",
      "user": {
        "id": "761a3e91-4062-4fc2-80a4-dc12c8601522",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "bank": {
        "accountId": 1895546,
        "name": "Chase Bank",
        "accountLastFour": "1234",
        "accountType": "Checking"
      }
    }
  },
  "providerResponse": {
    "providerTransactionId": "67b68945-aab8-4404-a474-4270a588491b",
    "providerTransactionStatus": "live"
  }
}
```

### Transaction cancelled

```json Card
{
  "state": "Cancelled",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Void",
    "fundingType": "Card",
    "entryType": "Ecom"
  },
  "amounts": {
    "transactionValue": 50.05,
    "currencyCode": "EUR"
  },
  "merchantOrderId": "This_is_my_merchant_order_id",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "fundingData": {
    "cardScheme": "Visa",
    "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "schemeTokenNumber": "4837261112345678",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "paymentAccountReference": "PAR12345678901234567890",
      "schemeTransactionId": "TX1234567890123456"
    }
  }
}
```

```json PayPal
{
  "state": "Cancelled",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Void",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_void_id_0003",
  "systemTransactionId": "43326543-6956-469d-a1a0-64e6d9bb54c7",
  "fundingData": {
    "paypal": {
      "paymentSource": "Paypal"
    }
  }
}
```

```json Pay Later
{
  "state": "Cancelled",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Void",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_void_paylater_id_0006",
  "systemTransactionId": "72aed261-41e0-4696-b46a-e272c127e6c9",
  "fundingData": {
    "paypal": {
      "paymentSource": "PayLater"
    }
  }
}
```

```json Venmo
{
  "state": "Cancelled",
  "amounts": {
    "transaction": 16,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Void",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_void_venmo_id_0004",
  "systemTransactionId": "8bebd5a3-2b49-4461-8599-f0a7b913473a",
  "fundingData": {
    "paypal": {
      "paymentSource": "Venmo"
    }
  }
}
```

```json Aeropay
{
  "eventCode": "TXNAP_CNC",
  "state": "Cancelled",
  "merchant": "merchant-1",
  "site": "site-1",
  "merchantTransactionId": "merch-txn-001-void",
  "merchantTransactionDate": "2026-07-10T09:30:00Z",
  "systemTransactionId": "a0132571-d4fc-46c5-9375-8bc354324fbb",
  "originalSystemTransactionId": "6b0320d8-b24e-404c-9048-136d83e033f7",
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "USD"
  },
  "transactionMethod": {
    "intent": "Void",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Aeropay",
      "user": {
        "id": "761a3e91-4062-4fc2-80a4-dc12c8601522",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "bank": {
        "accountId": 1895546,
        "name": "Chase Bank",
        "accountLastFour": "1234",
        "accountType": "Checking"
      }
    }
  }
}
```

### Transaction captured

```json Card
{
  "state": "Captured",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Capture",
    "fundingType": "Card",
    "entryType": "Ecom"
  },
  "amounts": {
    "transactionValue": 50.05,
    "currencyCode": "EUR"
  },
  "merchantOrderId": "merchant_order_id",
  "merchantTransactionId": "merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27 08:51:02.826445+00:00",
  "fundingData": {
    "cardScheme": "Visa",
    "tokenId": "1ed768bb-e88a-4636-91ae-67927ccbb03a",
    "schemeTokenNumber": "4837261112345678",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "paymentAccountReference": "PAR12345678901234567890",
      "schemeTransactionId": "TX1234567890123456",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}
```

```json PayPal
{
  "state": "Captured",
  "amounts": {
    "transaction": 10.00,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Capture",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "shippingAddress": {
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "postalCode": "12345",
    "countryCode": "US",
    "city": "New York",
    "county": "Manhattan"
  },
  "merchantTransactionDate": "2025-06-20T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_confirm_id_007",
  "systemTransactionId": "e155b186-c6ea-4cb9-9a6c-590ef6daeeed",
  "providerTransactionId": "52K24494FC626730T",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "payee@mail.com",
      "paymentSource": "Paypal",
      "experienceContext": {
        "paymentDescription": "Purchase from test site",
        "userAction": "pay_now",
        "orderType": "goods",
        "shippingPreference": "set_provided_address"
      },
      "shippingSelected": {
        "id": "shipping_id",
        "label": "shipping_label",
        "selected": true,
        "amounts": {
          "shipping": 1.00,
          "currencyCode": "USD"
        },
        "type": "shipping"
      }
    }
  }
}
```

```json Pay Later
{
	"state": "Captured",
  "amounts": {
		"transaction": 1,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Capture",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T03:13:22.93Z",
  "merchantTransactionId": "merchant Capture TransactionId paylater 0004",
  "systemTransactionId": "3470aaa0-5136-409a-9e3e-fc58ef4c6fa5",
  "providerTransactionId": "1X609527EV445235N",
  "fundingData": {
    "paypal": {
      "paymentSource": "PayLater"
    }
  }
}
```

```json Venmo
{
  "state": "Captured",
  "amounts": {
    "transaction": 1,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Capture",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T03:13:22.93Z",
  "merchantTransactionId": "merchant Capture TransactionId Venmo 0003",
  "systemTransactionId": "af200906-3cf3-4693-a2f7-d8a5a14b6657",
  "providerTransactionId": "62965733U4680700F",
  "fundingData": {
    "paypal": {
      "paymentSource": "Venmo"
    }
  }
}
```

```json Aeropay
{
  "eventCode": "TXNAP_CPT",
  "state": "Captured",
  "merchant": "merchant-1",
  "site": "site-1",
  "merchantTransactionId": "merch-txn-001-cap",
  "merchantTransactionDate": "2026-07-10T09:00:00Z",
  "systemTransactionId": "6b0320d8-b24e-404c-9048-136d83e033f7",
  "originalSystemTransactionId": "4f2f8f79-1fa6-4c88-9dee-3de55925498c",
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "USD"
  },
  "transactionMethod": {
    "intent": "Capture",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Aeropay",
      "apFee": "222",
      "isRtp": false,
      "user": {
        "id": "761a3e91-4062-4fc2-80a4-dc12c8601522",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "bank": {
        "accountId": 1895546,
        "name": "Chase Bank",
        "accountLastFour": "1234",
        "accountType": "Checking"
      }
    }
  },
  "providerResponse": {
    "providerTransactionId": "67b68945-aab8-4404-a474-4270a588491b",
    "providerTransactionStatus": "live"
  }
}
```

### Transaction created

```json PayPal
{
  "state": "Pending",
  "amounts": {
    "transaction": 100,
    "currencyCode": "USD"	
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445+00:00",
  "merchantTransactionId": "Create test 2",
  "systemTransactionId": "cb6c3fb9-fb0f-4924-b301-798d4606a3a8",
  "providerTransactionId": "8TV523960U3224341",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",	
      "paymentSource": "Paypal",
      "experienceContext": {
        "paymentDescription": "Louis Vuitton bag QC Test",
        "userAction": "PAY_NOW",
        "orderType": "Authorisation",
        "shippingPreference": "GET_FROM_FILE"
      }
    }
  }
}
```

```json Pay Later
{
  "state": "Pending",
  "amounts": {
    "transaction": 100,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445+00:00",
  "merchantTransactionId": "Create test paylater 6",
  "systemTransactionId": "671ebf55-22a9-4717-a1b9-0d592e3d6ede",
  "providerTransactionId":"79095268FF6175738",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "PayLater",
      "experienceContext": {
      	"paymentDescription": "Louis Vuitton bag QC Test",
      	"userAction": "PAY_NOW",
	"orderType": "Authorisation",
      	"shippingPreference": "GET_FROM_FILE"
      }
    }
  }
}
```

```json Venmo
{
  "state": "Pending",
  "amounts": {
    "transaction": 100,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445+00:00",
  "merchantTransactionId": "Create test 4",
  "systemTransactionId": "b3436453-f347-4444-9871-5a3beabf4acc",
  "providerTransactionId": "5E781953VF346004S",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "Venmo",
      "experienceContext": {
        "paymentDescription": "Louis Vuitton bag QC Test",
        "userAction": "PAY_NOW",
        "orderType": "Authorisation",
        "shippingPreference": "GET_FROM_FILE"
      }
    }
  }
}
```

### Transaction executed

```json PayPal
{
  "state": "Executed",
  "amounts": {
    "transaction": 16.00,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445",
  "merchantTransactionId": "Create test 2",
  "systemTransactionId": "cb6c3fb9-fb0f-4924-b301-798d4606a3a8",
  "providerTransactionId": "8TV523960U3224341",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "Paypal"
    }
  }
}
```

```json Pay Later
{
  "state": "Executed",
  "amounts": {
    "transaction": 16.00,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445",
  "merchantTransactionId": "Create test paylater 6",
  "systemTransactionId": "671ebf55-22a9-4717-a1b9-0d592e3d6ede",
  "providerTransactionId": "79095268FF6175738",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "PayLater"
    }
  }
}
```

```json Venmo
{
  "state": "Executed",
  "amounts": {
    "transaction": 16.00,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Create",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-20T00:00:00.826445",
  "merchantTransactionId": "Create test 4",
  "systemTransactionId": "b3436453-f347-4444-9871-5a3beabf4acc",
  "providerTransactionId": "5E781953VF346004S",
  "fundingData": {
    "paypal": {
      "payeeEmailAddress": "john.doe@pxp.io",
      "paymentSource": "Venmo"
    }
  }
}
```

### Transaction refunded

```json PayPal
{
  "state": "Refunded",
  "amounts": {
    "transaction": 0.1,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Refund",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_refund_id_0001",
  "systemTransactionId": "875f36e7-dbd9-44a1-be71-46bd97bc5efc",
  "providerTransactionId": "8UE54115C2538705D",
  "fundingData": {
    "paypal": {
      "paymentSource": "Paypal"
    }
  }
}
```

```json Pay Later
{
  "state": "Refunded",
  "amounts": {
    "transaction": 0.1,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Refund",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_refund_paylater_id_0002",
  "systemTransactionId": "810c2d26-b606-4c0d-8e25-89997ede486d",
  "providerTransactionId": "80B21926CC5840333",
  "fundingData": {
    "paypal": {
      "paymentSource": "PayLater"
    }
  }
}
```

```json Venmo
{
  "state": "Refunded",
  "amounts": {
    "transaction": 0.1,
    "currencyCode": "USD"
  },
  "merchant": "merchant-1",
  "site": "site-1",
  "transactionMethod": {
    "intent": "Refund",
    "fundingType": "Paypal",
    "entryType": "Ecom"
  },
  "merchantTransactionDate": "2025-06-27T03:13:22.93Z",
  "merchantTransactionId": "merchant_transaction_refund_venmo_id_0001",
  "systemTransactionId": "b065e353-1e5c-4436-85dc-03bc3f6531cc",
  "providerTransactionId": "01A49403R4069073P",
  "fundingData": {
    "paypal": {
      "paymentSource": "Venmo"
    }
  }
}
```

```json Aeropay
{
  "eventCode": "TXNAP_RFD",
  "state": "Refunded",
  "merchant": "merchant-1",
  "site": "site-1",
  "merchantTransactionId": "merch-txn-001-rfd",
  "merchantTransactionDate": "2026-07-13T15:30:00Z",
  "systemTransactionId": "a0132571-d4fc-46c5-9375-8bc354324fbb",
  "originalSystemTransactionId": "bf015bd2-80c3-49e9-8f37-3e1db108d2bb",
  "amounts": {
    "transaction": 3.0,
    "currencyCode": "USD"
  },
  "transactionMethod": {
    "intent": "Refund",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Aeropay",
      "user": {
        "id": "ffbe50f7-ac6f-4cf6-8629-4e0e6b072f47",
        "name": "John Hien",
        "email": "hien.test003@gmail.com"
      },
      "bank": {
        "accountId": 2054460,
        "name": "Aerosync Bank (oAuth)",
        "accountLastFour": "4561",
        "accountType": "Aerosync Checking"
      }
    }
  },
  "providerResponse": {
    "providerTransactionId": "aero-refund-partial-1",
    "providerTransactionStatus": "pending",
    "providerResponseMessage": "Refund transaction created"
  }
}
```

### SPEI transaction executed

Treat SPEI webhooks as the authoritative outcome for purchase and payout. Use `transactionMethod.intent` to tell purchase and payout apart when they share the same event code.

```json Purchase
{
  "eventCode": "spei-transaction-order-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM001",
    "message": "Payment executed"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Authorised",
    "providerResponseCode": "EXECUTED",
    "providerResponseMessage": "Payment executed"
  },
  "merchantTransactionId": "SPEI-TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

```json Payout
{
  "eventCode": "spei-transaction-order-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM001",
    "message": "Payment executed"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Authorised",
    "providerResponseCode": "EXECUTED",
    "providerResponseMessage": "Payment executed"
  },
  "merchantTransactionId": "SPEI-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### SPEI transaction declined

```json Purchase
{
  "eventCode": "spei-transaction-order-declined",
  "state": "Aborted",
  "stateData": {
    "code": "APM004",
    "message": "Payment declined"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Aborted",
    "providerResponseCode": "DECLINED",
    "providerResponseMessage": "Payment declined"
  },
  "merchantTransactionId": "SPEI-TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

```json Payout
{
  "eventCode": "spei-transaction-order-declined",
  "state": "Refused",
  "stateData": {
    "code": "APM004",
    "message": "Payment declined"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Refused",
    "providerResponseCode": "DECLINED",
    "providerResponseMessage": "Payment declined"
  },
  "merchantTransactionId": "SPEI-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### SPEI transaction expired

```json
{
  "eventCode": "spei-transaction-order-expired",
  "state": "Expired",
  "stateData": {
    "code": "APM011",
    "message": "Payment expired"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Expired",
    "providerResponseCode": "EXPIRED",
    "providerResponseMessage": "Payment expired"
  },
  "merchantTransactionId": "SPEI-TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### SPEI transaction failed

```json
{
  "eventCode": "spei-transaction-order-failed",
  "state": "Refused",
  "stateData": {
    "code": "APM012",
    "message": "Payment failed"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Refused",
    "providerResponseCode": "FAILED",
    "providerResponseMessage": "Payment failed"
  },
  "merchantTransactionId": "SPEI-TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### SPEI transaction refunded

```json
{
  "eventCode": "spei-transaction-order-refunded",
  "state": "Refunded",
  "stateData": {
    "code": "APM007",
    "message": "Payment refunded"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Refunded",
    "providerResponseCode": "REFUNDED",
    "providerResponseMessage": "Payment refunded"
  },
  "merchantTransactionId": "SPEI-REFUND-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### SPEI transaction rejected

This event applies to SPEI payouts only.

```json
{
  "eventCode": "spei-transaction-order-rejected",
  "state": "Rejected",
  "stateData": {
    "code": "APM013",
    "message": "Payment rejected"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "MXN"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Spei"
    }
  },
  "providerResponse": {
    "provider": "Spei",
    "providerTransactionStatus": "Rejected",
    "providerResponseCode": "REJECTED",
    "providerResponseMessage": "Payment rejected"
  },
  "merchantTransactionId": "SPEI-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### CVU transaction executed

Treat CVU webhooks as the authoritative outcome for deposits and payouts. Use `transactionMethod.intent` to tell deposit (`Purchase`) and payout apart when they share the same event code.

For a CVU deposit, this webhook is the first notice of the transaction (there is no create call), so `merchantTransactionId` may be null. Correlate deposits by `systemTransactionId` and the shopper's CVU context.

```json Deposit
{
  "eventCode": "cvu-transaction-order-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM001",
    "message": "Payment executed"
  },
  "amounts": {
    "transaction": 1400.0,
    "currencyCode": "ARS"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu"
    }
  },
  "providerResponse": {
    "provider": "Cvu",
    "providerTransactionStatus": "Authorised",
    "providerResponseCode": "EXECUTED",
    "providerResponseMessage": "Payment executed"
  },
  "merchantTransactionId": null,
  "systemTransactionId": "3af98add-0aac-6858-b3c0-89b49eede24d"
}
```

```json Payout
{
  "eventCode": "cvu-transaction-order-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM001",
    "message": "Payment executed"
  },
  "amounts": {
    "transaction": 1400.0,
    "currencyCode": "ARS"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu"
    }
  },
  "providerResponse": {
    "provider": "Cvu",
    "providerTransactionStatus": "Authorised",
    "providerResponseCode": "EXECUTED",
    "providerResponseMessage": "Payment executed"
  },
  "merchantTransactionId": "CVU-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### CVU transaction declined

This event applies to CVU payouts only.

```json
{
  "eventCode": "cvu-transaction-order-declined",
  "state": "Refused",
  "stateData": {
    "code": "APM004",
    "message": "Payment declined"
  },
  "amounts": {
    "transaction": 1400.0,
    "currencyCode": "ARS"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu"
    }
  },
  "providerResponse": {
    "provider": "Cvu",
    "providerTransactionStatus": "Refused",
    "providerResponseCode": "DECLINED",
    "providerResponseMessage": "Payment declined"
  },
  "merchantTransactionId": "CVU-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### CVU transaction expired

This event applies to CVU payouts only.

```json
{
  "eventCode": "cvu-transaction-order-expired",
  "state": "Expired",
  "stateData": {
    "code": "APM011",
    "message": "Payment expired"
  },
  "amounts": {
    "transaction": 1400.0,
    "currencyCode": "ARS"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu"
    }
  },
  "providerResponse": {
    "provider": "Cvu",
    "providerTransactionStatus": "Expired",
    "providerResponseCode": "EXPIRED",
    "providerResponseMessage": "Payment expired"
  },
  "merchantTransactionId": "CVU-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### CVU transaction failed

This event applies to CVU payouts only.

```json
{
  "eventCode": "cvu-transaction-order-failed",
  "state": "Refused",
  "stateData": {
    "code": "APM012",
    "message": "Payment failed"
  },
  "amounts": {
    "transaction": 1400.0,
    "currencyCode": "ARS"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu"
    }
  },
  "providerResponse": {
    "provider": "Cvu",
    "providerTransactionStatus": "Refused",
    "providerResponseCode": "FAILED",
    "providerResponseMessage": "Payment failed"
  },
  "merchantTransactionId": "CVU-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### CVU transaction refunded

```json
{
  "eventCode": "cvu-transaction-order-refunded",
  "state": "Refunded",
  "stateData": {
    "code": "APM007",
    "message": "Payment refunded"
  },
  "amounts": {
    "transaction": 1400.0,
    "currencyCode": "ARS"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu"
    }
  },
  "providerResponse": {
    "provider": "Cvu",
    "providerTransactionStatus": "Refunded",
    "providerResponseCode": "REFUNDED",
    "providerResponseMessage": "Payment refunded"
  },
  "merchantTransactionId": "CVU-RFD-001",
  "systemTransactionId": "3af98add-0aac-6858-b3c0-89b49eede24d"
}
```

### CVU transaction rejected

This event applies to CVU payouts only.

```json
{
  "eventCode": "cvu-transaction-order-rejected",
  "state": "Rejected",
  "stateData": {
    "code": "APM013",
    "message": "Payment rejected"
  },
  "amounts": {
    "transaction": 1400.0,
    "currencyCode": "ARS"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Cvu"
    }
  },
  "providerResponse": {
    "provider": "Cvu",
    "providerTransactionStatus": "Rejected",
    "providerResponseCode": "REJECTED",
    "providerResponseMessage": "Payment rejected"
  },
  "merchantTransactionId": "CVU-PAYOUT-001",
  "systemTransactionId": "2fe879cc-f99b-5747-a2bf-78a38ddcc13c"
}
```

### Bre-B transaction executed

Treat Bre-B webhooks as the authoritative outcome for deposits and payouts. Use `transactionMethod.intent` to tell deposit (`Purchase`) and payout apart when they share the same event code.

For a Bre-B deposit, this webhook is the first notice of the transaction (there is no create call), so `merchantTransactionId` may be null. Correlate deposits by `systemTransactionId` and the shopper's Bre-B context.

```json Deposit
{
  "eventCode": "breb-transaction-order-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM003",
    "message": "Payment authorised"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb",
      "bankOwnershipDetails": {
        "accountHolderFullName": "Juan Perez",
        "accountNumber": "1234567890",
        "bankName": "Banco de Bogota",
        "beneficiaryAccountNumber": "0987654321"
      }
    },
    "alias": "@pxpshopper01"
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Authorised",
    "providerResponseCode": "EXECUTED",
    "providerResponseMessage": "Payment authorised"
  },
  "merchantTransactionId": null,
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

```json Payout
{
  "eventCode": "breb-transaction-order-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM003",
    "message": "Payment authorised"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb"
    }
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Authorised",
    "providerResponseCode": "EXECUTED",
    "providerResponseMessage": "Payment authorised"
  },
  "merchantTransactionId": "BREB-PAYOUT-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### Bre-B transaction declined

This event applies to Bre-B payouts only.

```json
{
  "eventCode": "breb-transaction-order-declined",
  "state": "Refused",
  "stateData": {
    "code": "APM004",
    "message": "Payment declined"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb"
    }
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Refused",
    "providerResponseCode": "DECLINED",
    "providerResponseMessage": "Payment declined"
  },
  "merchantTransactionId": "BREB-PAYOUT-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### Bre-B transaction expired

This event applies to Bre-B payouts only.

```json
{
  "eventCode": "breb-transaction-order-expired",
  "state": "Expired",
  "stateData": {
    "code": "APM011",
    "message": "Payment expired"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb"
    }
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Expired",
    "providerResponseCode": "EXPIRED",
    "providerResponseMessage": "Payment expired"
  },
  "merchantTransactionId": "BREB-PAYOUT-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### Bre-B transaction failed

This event applies to Bre-B payouts only.

```json
{
  "eventCode": "breb-transaction-order-failed",
  "state": "Refused",
  "stateData": {
    "code": "APM012",
    "message": "Payment failed"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb"
    }
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Refused",
    "providerResponseCode": "FAILED",
    "providerResponseMessage": "Payment failed"
  },
  "merchantTransactionId": "BREB-PAYOUT-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### Bre-B transaction refunded

```json
{
  "eventCode": "breb-transaction-order-refunded",
  "state": "Refunded",
  "stateData": {
    "code": "APM007",
    "message": "Payment refunded"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Refund",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb"
    }
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Refunded",
    "providerResponseCode": "REFUNDED",
    "providerResponseMessage": "Payment refunded"
  },
  "merchantTransactionId": "BREB-RFD-001",
  "systemTransactionId": "3ab45678-cdef-9012-3456-789abcdef012"
}
```

### Bre-B transaction rejected

This event applies to Bre-B payouts only.

```json
{
  "eventCode": "breb-transaction-order-rejected",
  "state": "Rejected",
  "stateData": {
    "code": "APM013",
    "message": "Payment rejected"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb"
    }
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Rejected",
    "providerResponseCode": "REJECTED",
    "providerResponseMessage": "Payment rejected"
  },
  "merchantTransactionId": "BREB-PAYOUT-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### Bre-B transaction cross-entry

This event applies to Bre-B payouts only.

```json
{
  "eventCode": "breb-transaction-order-cross-entry",
  "state": "Refused",
  "stateData": {
    "code": "APM004",
    "message": "Payment declined"
  },
  "amounts": {
    "transaction": 100.0,
    "currencyCode": "COP"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBank"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Breb"
    }
  },
  "providerResponse": {
    "provider": "Breb",
    "providerTransactionStatus": "Refused",
    "providerResponseCode": "CROSS_ENTRY",
    "providerResponseMessage": "Payment declined"
  },
  "merchantTransactionId": "BREB-PAYOUT-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### FlashFlow transaction executed

Treat FlashFlow webhooks as the authoritative outcome for pay-ins and payouts. You don't receive raw FlashFlow callback bodies. Use `transactionMethod.intent` to tell purchase and payout apart when they share the same event code.

`shopperReference`, `gatewayTokenId`, and `transactionUpdateDatetime` are omitted when not stored on the transaction. Bank account numbers and holder names are never included.

```json Purchase
{
  "eventCode": "flashflow-transaction-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM001",
    "message": "Payment executed"
  },
  "amounts": {
    "transaction": 99.50,
    "currencyCode": "THB"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "shopperReference": "Shopper_TH_01",
  "gatewayTokenId": "b6e2f1a4-c3d8-4f7a-b1e9-d2c3f4a5b6c7",
  "transactionUpdateDatetime": "2026-09-21T10:30:00Z",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBanks"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Flashflow"
    }
  },
  "providerResponse": {
    "provider": "Flashflow",
    "providerTransactionId": "flashflow-ref-001",
    "providerTransactionStatus": "completed",
    "providerResponseCode": "completed",
    "providerResponseMessage": "Payment executed"
  },
  "merchantTransactionId": "FLASHFLOW-TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

```json Payout
{
  "eventCode": "flashflow-transaction-executed",
  "state": "Authorised",
  "stateData": {
    "code": "APM001",
    "message": "Payment executed"
  },
  "amounts": {
    "transaction": 100.00,
    "currencyCode": "THB"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "gatewayTokenId": "b6e2f1a4-c3d8-4f7a-b1e9-d2c3f4a5b6c7",
  "transactionUpdateDatetime": "2026-09-21T11:00:00Z",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBanks"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Flashflow"
    }
  },
  "providerResponse": {
    "provider": "Flashflow",
    "providerTransactionId": "flashflow-ref-002",
    "providerTransactionStatus": "completed",
    "providerResponseCode": "completed",
    "providerResponseMessage": "Payment executed"
  },
  "merchantTransactionId": "FLASHFLOW-PAYOUT-001",
  "systemTransactionId": "2fd879cc-f99b-4747-92bf-78038ddcc03c"
}
```

### FlashFlow transaction expired

This event applies to FlashFlow pay-ins only.

```json
{
  "eventCode": "flashflow-transaction-expired",
  "state": "Expired",
  "stateData": {
    "code": "APM011",
    "message": "Payment expired"
  },
  "amounts": {
    "transaction": 100.00,
    "currencyCode": "THB"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "shopperReference": "Shopper_TH_01",
  "transactionUpdateDatetime": "2026-09-21T10:40:00Z",
  "transactionMethod": {
    "intent": "Purchase",
    "entryType": "Ecom",
    "fundingType": "PayByBanks"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Flashflow"
    }
  },
  "providerResponse": {
    "provider": "Flashflow",
    "providerTransactionId": "flashflow-ref-001",
    "providerTransactionStatus": "expired",
    "providerResponseCode": "expired",
    "providerResponseMessage": "Payment expired"
  },
  "merchantTransactionId": "FLASHFLOW-TXN-001",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b"
}
```

### FlashFlow transaction refused

This event applies to FlashFlow payouts.

```json
{
  "eventCode": "flashflow-transaction-refused",
  "state": "Refused",
  "stateData": {
    "code": "APM004",
    "message": "Payment refused"
  },
  "amounts": {
    "transaction": 100.00,
    "currencyCode": "THB"
  },
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "gatewayTokenId": "b6e2f1a4-c3d8-4f7a-b1e9-d2c3f4a5b6c7",
  "transactionUpdateDatetime": "2026-09-21T11:05:00Z",
  "transactionMethod": {
    "intent": "Payout",
    "entryType": "Ecom",
    "fundingType": "PayByBanks"
  },
  "fundingData": {
    "payByBank": {
      "apmProvider": "Flashflow"
    }
  },
  "providerResponse": {
    "provider": "Flashflow",
    "providerTransactionId": "flashflow-ref-002",
    "providerTransactionStatus": "rejected",
    "providerResponseCode": "rejected",
    "providerResponseMessage": "Payment refused"
  },
  "merchantTransactionId": "FLASHFLOW-PAYOUT-001",
  "systemTransactionId": "2fd879cc-f99b-4747-92bf-78038ddcc03c"
}
```

### Payout authorised

```json
{
  "state": "Authorised",
  "amount": {
    "transaction": 100.0,
    "currencyCode": "USD"
  },
  "transactionMethod": "Payout",
  "merchant": "merchant-1",
  "site": "site-1",
  "merchantTransactionDate": "2025-12-16T07:37:11.1613200Z",
  "merchantTransactionId": "PAYOUT_001",
  "systemTransactionId": "787ebfee-c0ce-497a-82c3-265d1bf19b0c",
  "providerTransactionId": "PAYPAL_PAYOUT_ITEM_ID",
  "fundingData": {
    "paypal": {
      "paymentSource": "Paypal"
    }
  }
}
```

### User info created

```json
{
  "merchant": "merchant-1",
  "site": "site-1",
  "customerInformation": {
    "id": "a7cd91cd-1bb8-4f82-af24-350d6d0b8680",
    "name": "John Doe",
    "email": "sb-oejwh44573747@business.example.com",
    "verified": true,
    "payerId": "BLLXSEJZ9B7ZA",
    "address": {
      "streetAddress": "1 Main St",
      "locality": "San Jose",
      "region": "CA",
      "postalCode": "95131",
      "countryCode": "US"
    },
    "verifiedAccount": true,
    "emailVerified": true
  },
  "eventCode": "TXNPP_UIC"
}
```

### User suspended

```json
{
  "eventCode": "TXNAP_USP",
  "userId": "761a3e91-4062-4fc2-80a4-dc12c8601522"
}
```

### User activated

```json
{
  "eventCode": "TXNAP_UAC",
  "userId": "761a3e91-4062-4fc2-80a4-dc12c8601522"
}
```

### Scheduled report generated

```json
{
  "url": "https://api-gateway-transactions.qa.kube.qa/api/v1/reporting/scheduled-report-executions/d1adbc0d-d931-4775-8613-c44853c5464f/content-download-url"
}
```

### Scheme token created

```json
{
  "schemeTokenId": "68412215-aae5-4380-be63-c52e7868eab5",
  "schemeTokenProvider": "Visa",
  "state": "Completed",
  "externalSchemeTokenId": "7a60cfe4-df64-4e5d-b3d3-0b70713dd70b",
  "paymentAccountReference": "V0010013024080362079202015296",
  "expiryMonth": 4,
  "expiryYear": 2030,
  "maskedPrimaryAccountNumber": "47158511****6438"
}
```

### Scheme token creation error

```json
{
  "schemeTokenId": "fc8aa727-ec3c-4cf1-9c2b-26e4f78ce7b7",
  "schemeTokenProvider": "Visa",
  "state": "Error",
  "externalSchemeTokenId": null,
  "paymentAccountReference": null,
  "expiryMonth": 3,
  "expiryYear": 2033,
  "maskedPrimaryAccountNumber": "41000000******0001"
}
```

### Scheme token card updated

```json
{
  "schemeTokenId": "bf53d5d5-6481-4c6b-9a99-deb4a319fb06",
  "schemeTokenProvider": "Mastercard",
  "state": "Completed",
  "externalSchemeTokenId": "1c871554-d90d-4676-89a6-e11a1bed3999",
  "paymentAccountReference": "50010P4G3SYR1Q9RJVY18EDBHWQZT",
  "expiryMonth": 12,
  "expiryYear": 2030,
  "maskedPrimaryAccountNumber": "52660010****0025"
}
```

### Scheme token disabled

```json
{
  "schemeTokenId": "bd420b08-00bc-4cfe-9b6b-84e52176c5b7",
  "schemeTokenProvider": "Mastercard",
  "state": "Completed",
  "externalSchemeTokenId": "a43d958e-e7a9-47b0-9a37-2f923744f59e",
  "paymentAccountReference": "50010P4G3SYR1Q9RJVY18EDBHWQZT",
  "expiryMonth": 4,
  "expiryYear": 2027,
  "maskedPrimaryAccountNumber": "52660010****0026"
}
```