> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# SubmitEvent

# Package: paymentServiceProviderServicePlugin

# Namespace: ProviderPlatformEventsService

# Method link: https://dev.wix.com/docs/api-reference/business-management/payments/payment-service-provider-service-plugin/callbacks/submit-event.md

## Introduction

This Wix API is used by a Payment Service Provider (PSP) to send webhooks about payment and refund states to Wix.

Calls to this endpoint must include a `User-Agent` header with the name of the PSP and the integration version in this format: `{PSP}/{version}`.
PSP's create their own version numbers.

> You cannot try out this endpoint because an `Authorization` header value has to be obtained
> with the OAuth 2.0 client credentials flow for a specific scope.
> So please ignore the **Authorization** section below as well as the **Try It Out** button.

---

## REST API

### Schema

```
 Method: submitEvent
 Description: This Wix API is used by a Payment Service Provider (PSP) to send webhooks about payment and refund states to Wix.  Calls to this endpoint must include a `User-Agent` header with the name of the PSP and the integration version in this format: `{PSP}/{version}`. PSP's create their own version numbers.  > You cannot try out this endpoint because an `Authorization` header value has to be obtained > with the OAuth 2.0 client credentials flow for a specific scope. > So please ignore the **Authorization** section below as well as the **Try It Out** button.
 URL: https://www.wixapis.com/payments/v1/provider-platform-events
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  event
 Method parameters: 
   param name: event | type: ProviderPlatformEvent | description: Provider platform event | required: true
    - ONE-OF: - required: true
     - name: refund | type: RefundEvent | description: Refund event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: pluginRefundId | type: string | description: PSP refund GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/api/rest/all-apis/provider-platform/reason-codes#all-apis_provider-platform_reason-codes_refund-declined) indicating a failed request. 
        - name: amount | type: string | description: Refunded amount. 
        - name: wixRefundId | type: string | description: Wix refund GUID. This field is only required when a merchant initiates a refund from the Wix dashboard. 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
     - name: transaction | type: TransactionEvent | description: Transaction event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: pluginTransactionId | type: string | description: PSP transaction GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/api/rest/all-apis/provider-platform/reason-codes) indicating a failed or pending request. 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
        - name: credentialsOnFile | type: CredentialsOnFile | description: Token data for stored payment method. 
           - ONE-OF: 
              - name: cardReference | type: CardReference | description: Network token data. 
                 - name: networkTransactionId | type: string | description: Network token. 
                 - name: dsTransactionId | type: string | description: Directory Server transaction GUID 
                 - name: transactionLinkId | type: string | description: Transaction Link Identifier assigned by Mastercard. 
              - name: paymentMethodReference | type: PaymentMethodReference | description: Provider generated token data. 
                 - name: token | type: string | description: Payment method token created by the PSP. 
        - name: cardDetails | type: CardDetails | description: Details of actual customer's card, obtained from a Funding PAN as opposed to a Device PAN. 
           - name: bin | type: string | description: Issuer (business) identification number. First 6 or 8 digits of the card's number. 
           - name: lastFour | type: string | description: Last 4 digits of the card's number. 
     - name: capture | type: CaptureEvent | description: Capture event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/reason-codes.md) indicating request's status. 
        - name: amount | type: string | description: Total amount captured in a currency’s minor units. Learn more about [currencies](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/currencies.md). 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
     - name: void | type: VoidEvent | description: Void event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/reason-codes.md) indicating request's status. 
        - name: amount | type: string | description: Total amount voided in a currency’s minor units. Learn more about [currencies](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/currencies.md). 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
        - name: siteId | type: string | description: Wix site GUID. 
 Return type: SubmitEventResponse
  EMPTY-OBJECT {}


```

### Examples

### Payment Authorized
```curl
curl -X POST 'https://www.wixapis.com/payments/v1/provider-platform-events' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-H 'User-Agent: banana-pay/1.0.0' \
-d '{
  "event": {
    "transaction": {
      "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
      "pluginTransactionId": "e89b-12d3-a456-42665"
      "reasonCode": 5010
    }
  }
}'
```

### Payment Voided
```curl
curl -X POST 'https://www.wixapis.com/payments/v1/provider-platform-events' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-H 'User-Agent: banana-pay/1.0.0' \
-d '{
  "event": {
    "void": {
      "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
      "reasonCode": 0,
      "amount": "1540"
    }
  }
}'
```

### Refund succeeded (initiated by PSP)
```curl
curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
 -H 'Content-Type: application/json' \
 -H 'Authorization: <AUTH>' \
 -H 'User-Agent: banana-pay/1.0.0' \
 -d '{
       "event": {
         "refund": {
           "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
           "pluginRefundId": "ce590272-87bf-428f-943a-0ff594059712",
           "amount": "1000"
         }
       }
     }'
```

### Payment approved
```curl
curl -X POST 'https://www.wixapis.com/payments/v1/provider-platform-events' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: <AUTH>' \
 -H 'User-Agent: banana-pay/1.0.0' \
 -d '{
       "event": {
         "transaction": {
           "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
           "pluginTransactionId": "e89b-12d3-a456-42665"
         }
       }
     }'
```

### Payment declined
```curl
curl -X POST 'https://www.wixapis.com/payments/v1/provider-platform-events' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: <AUTH>' \
 -H 'User-Agent: banana-pay/1.0.0' \
 -d '{
       "event": {
         "transaction": {
           "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
           "pluginTransactionId": "e89b-12d3-a456-42665",
           "reasonCode": 3012,
           "errorCode": "INSUFFICIENT_FUNDS",
           "errorMessage": "Insufficient funds"
         }
       }
     }'
```

### Payment Captured
```curl
curl -X POST 'https://www.wixapis.com/payments/v1/provider-platform-events' \
-H 'Content-Type: application/json' \
-H 'Authorization: <AUTH>' \
-H 'User-Agent: banana-pay/1.0.0' \
-d '{
  "event": {
    "capture": {
      "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
      "reasonCode": 0,
      "amount": "1540"
    }
  }
}'
```

### Payment pending
```curl
curl -X POST 'https://www.wixapis.com/payments/v1/provider-platform-events' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: <AUTH>' \
 -H 'User-Agent: banana-pay/1.0.0' \
 -d '{
       "event": {
         "transaction": {
           "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
           "pluginTransactionId": "e89b-12d3-a456-42665",
           "reasonCode": 5005
         }
       }
     }'
```

### Refund failed (initiated by Wix)
```curl
curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
 -H 'Content-Type: application/json' \
 -H 'Authorization: <AUTH>' \
 -H 'User-Agent: banana-pay/1.0.0' \
 -d '{
       "event": {
         "refund": {
           "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
           "pluginRefundId": "ce590272-87bf-428f-943a-0ff594059712",
           "amount": "1000",
           "wixRefundId": "fcd2655f-e261-4c5b-8129-72a241461a27",
           "reasonCode": "3025",
           "errorCode": "INSUFFICIENT_FUNDS_FOR_REFUND",
           "errorMessage": "Insufficient funds for refund."
         }
       }
     }'
```

### Payment canceled
```curl
curl -X POST 'https://www.wixapis.com/payments/v1/provider-platform-events' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: <AUTH>' \
 -H 'User-Agent: banana-pay/1.0.0' \
 -d '{
       "event": {
         "transaction": {
           "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
           "pluginTransactionId": "e89b-12d3-a456-42665",
           "reasonCode": 3030,
           "errorCode": "BUYER_CANCELED",
           "errorMessage": "Buyer canceled"
         }
       } 
     }'
```

### Refund succeeded (initiated by Wix)
```curl
curl -X POST https://www.wixapis.com/payments/v1/provider-platform-events \
 -H 'Content-Type: application/json' \
 -H 'Authorization: <AUTH>' \
 -H 'User-Agent: banana-pay/1.0.0' \
 -d '{
       "event": {
         "refund": {
           "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
           "pluginRefundId": "ce590272-87bf-428f-943a-0ff594059712",
           "amount": "1000",
           "wixRefundId": "fcd2655f-e261-4c5b-8129-72a241461a27"
         }
       }
     }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.paymentServiceProviderServicePlugin.ProviderPlatformEventsService.submitEvent(event)
 Description: This Wix API is used by a Payment Service Provider (PSP) to send webhooks about payment and refund states to Wix.  Calls to this endpoint must include a `User-Agent` header with the name of the PSP and the integration version in this format: `{PSP}/{version}`. PSP's create their own version numbers.  > You cannot try out this endpoint because an `Authorization` header value has to be obtained > with the OAuth 2.0 client credentials flow for a specific scope. > So please ignore the **Authorization** section below as well as the **Try It Out** button.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  event
 Method parameters: 
   param name: event | type: ProviderPlatformEvent | description: Provider platform event | required: true
    - ONE-OF: - required: true
     - name: refund | type: RefundEvent | description: Refund event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: pluginRefundId | type: string | description: PSP refund GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/api/rest/all-apis/provider-platform/reason-codes#all-apis_provider-platform_reason-codes_refund-declined) indicating a failed request. 
        - name: amount | type: string | description: Refunded amount. 
        - name: wixRefundId | type: string | description: Wix refund GUID. This field is only required when a merchant initiates a refund from the Wix dashboard. 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
     - name: transaction | type: TransactionEvent | description: Transaction event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: pluginTransactionId | type: string | description: PSP transaction GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/api/rest/all-apis/provider-platform/reason-codes) indicating a failed or pending request. 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
        - name: credentialsOnFile | type: CredentialsOnFile | description: Token data for stored payment method. 
           - ONE-OF: 
              - name: cardReference | type: CardReference | description: Network token data. 
                 - name: networkTransactionId | type: string | description: Network token. 
                 - name: dsTransactionId | type: string | description: Directory Server transaction GUID 
                 - name: transactionLinkId | type: string | description: Transaction Link Identifier assigned by Mastercard. 
              - name: paymentMethodReference | type: PaymentMethodReference | description: Provider generated token data. 
                 - name: token | type: string | description: Payment method token created by the PSP. 
        - name: cardDetails | type: CardDetails | description: Details of actual customer's card, obtained from a Funding PAN as opposed to a Device PAN. 
           - name: bin | type: string | description: Issuer (business) identification number. First 6 or 8 digits of the card's number. 
           - name: lastFour | type: string | description: Last 4 digits of the card's number. 
     - name: capture | type: CaptureEvent | description: Capture event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/reason-codes.md) indicating request's status. 
        - name: amount | type: string | description: Total amount captured in a currency’s minor units. Learn more about [currencies](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/currencies.md). 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
     - name: void | type: VoidEvent | description: Void event data. 
        - name: wixTransactionId | type: string | description: Wix transaction GUID. 
        - name: reasonCode | type: integer | description: Wix [reason code](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/reason-codes.md) indicating request's status. 
        - name: amount | type: string | description: Total amount voided in a currency’s minor units. Learn more about [currencies](https://dev.wix.com/docs/rest/business-management/payments/service-plugins/payment-service-provider-service-plugin/currencies.md). 
        - name: errorCode | type: string | description: PSP-specific error code. 
        - name: errorMessage | type: string | description: PSP-specific error message. 
        - name: siteId | type: string | description: Wix site GUID. 
 Return type: PROMISE<SubmitEventResponse>
  EMPTY-OBJECT {}


```

### Examples

### submitEvent
```javascript
import { pspCallbacks } from '@wix/payments';

async function submitEvent(event) {
  const response = await pspCallbacks.submitEvent(event);
};
```

### submitEvent (with elevated permissions)
```javascript
import { pspCallbacks } from '@wix/payments';
import { auth } from '@wix/essentials';

async function mySubmitEventMethod(event) {
  const elevatedSubmitEvent = auth.elevate(pspCallbacks.submitEvent);
  const response = await elevatedSubmitEvent(event);
}
```

### submitEvent (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { pspCallbacks } from '@wix/payments';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { pspCallbacks },
  // Include the auth strategy and host as relevant
});


async function submitEvent(event) {
  const response = await myWixClient.pspCallbacks.submitEvent(event);
};
```

---