Processing Payments

When a buyer submits a payment for a Payment Service Provider (PSP) on a Wix site, Wix sends a request to the PSP's Create Transaction endpoint. The PSP must then process the payment and send a response to Wix. This article includes general information about implementing the Create Transaction endpoint. To learn more about specific payment flows, see Sample Payment Flows.

About the Create Transaction endpoint

In general, an implementation of the Create Transaction endpoint must do 2 things:

1. Accept requests in the format indicated in the SPI reference, process payments accordingly, and respond with the appropriate HTTP status code and response body.
2. Send webhooks to Wix to confirm payment events and to notify Wix about any changes to a payment status. Webhooks are sent using the Submit Event API.

Here are some important things to keep in mind when implementing the Create Transaction endpoint:

• Wix uses reason codes to indicate the statuses of payments. Your Create Transaction endpoint should respond with the appropriate reason code for each payment status. For a list of reason codes, see Reason Codes.
• When processing credit and debit card payments, Wix collects card details and sends them as part of the SPI request. Card data is sent in the card property of the paymentMethodData field. Because requests include sensitive card data, the PSP must be compliant with PCI DSS.
• Requests made to the Create Transaction endpoint include a Digest header whose value is a JSON Web Token. The PSP should use this value to validate all requests to the endpoint. Learn more about JWT validation.
• Most fields in the request body are optional. Your endpoint should not rely on these fields being present. You can configure certain fields as required so that they are included with every request. This configuration is done in your app's payment gateway component in the Wix Developers Center.

Idempotency

When Wix sends a request to the Create Transaction endpoint, it includes a wixTransactionId field. This field is a unique identifier for the payment. When the PSP receives this request, it must create an internal ID for the payment and include it in the response in the pluginTransactionId field. Each wixTransactionId must be idempotent. This means that if the PSP receives a request with a wixTransactionId that it has already processed, it must not initiate a new payment. Instead, it must respond with the latest payment status. If the status hasn't changed, the PSP should send the previous response for that wixTransactionId.

Send webhooks

In addition to responding to requests to the Create Transaction endpoint, the PSP must send webhooks to Wix to confirm payment events and to notify Wix about any changes to a payment status. Webhooks are sent using the Submit Event API.

Webhook requests must use 0Auth 2.0 authentication. To learn more, see Webhooks.

Confirm a final payment event

When confirming a payment event, such as an instantly approved card payment, the webhook request body is the same as the response body for the Create Transaction endpoint with the wixTransactionId added. This webhook is sent immediately after the PSP responds to the Create Transaction request.

For example, the response body for a declined card payment looks like this:

1
{
2
  "pluginTransactionId": "0dd8c114-b70e-493f-90b7-bf106b445ccd",
3
  "reasonCode": 3019,
4
  "errorCode": "CARD_LIMIT_EXCEEDED",
5
  "errorMessage": "Not enough funds left in the card limit for this transaction."
6
}

The webhook request body for the same payment looks like this:

1
{
2
  "event": {
3
    "transaction": {
4
      "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
5
      "pluginTransactionId": "0dd8c114-b70e-493f-90b7-bf106b445ccd",
6
      "reasonCode": 3019,
7
      "errorCode": "CARD_LIMIT_EXCEEDED",
8
      "errorMessage": "Not enough funds left in the card limit for this transaction."
9
    }
10
  }
11
}

Update payment status

When a payment request is not finalized immediately, such as when a payment requires fraud verification or 3D Secure verification, the PSP must send multiple webhooks to Wix. The first request is sent immediately after the PSP responds to the Create Transaction request. This request indicates that the payment is in a pending state. The PSP must include a reasonCode field with a value of 5005 to indicate that the payment is pending.

For example, the webhook request body for a pending payment looks like this:

1
{
2
  "event": {
3
    "transaction": {
4
      "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
5
      "pluginTransactionId": "0dd8c114-b70e-493f-90b7-bf106b445ccd",
6
      "reasonCode": 5005
7
    }
8
  }
9
}

When the payment is finalized, the PSP must send another webhook to Wix. This webhook indicates the final payment status. If the payment is rejected, the PSP must include a reasonCode field with the appropriate value. If the payment is approved, the PSP must not include a reasonCode field.

For example, the webhook request body for an approved payment looks like this:

1
{
2
  "event": {
3
    "transaction": {
4
      "wixTransactionId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1",
5
      "pluginTransactionId": "0dd8c114-b70e-493f-90b7-bf106b445ccd"
6
    }
7
  }
8
}

A PSP must not send contradictory webhooks. For example, you must not send a webhook indicating that a payment is approved after you have sent a webhook indicating that the payment is declined. You should also not send a webhook indicating that a payment is pending after you have sent a webhook indicating that the payment is approved or declined.