Sample Payment Flows

This article shows how to handle payment flows when implementing a Create Transaction endpoint. For general information about this endpoint, see Processing Payments.

The Payment Provider Platform supports the following payment flows:

• Card payments
• Digital wallet payments
• Redirection-Based payments
• Recurring payments
• Mail order/telephone order (MOTO) payments

The following sections include examples of each payment flow. These examples are based on the Create Transaction request body and the Submit Event request body. The values in these examples are fake. Examples are applicable for both live and sandbox modes.

Card payments

Card payments are payments made using a credit or debit card. In the simplest case, card payments are processed without additional buyer input. These payments are either instantly approved or declined, or are in a pending state for a short time while fraud verification is completed. In some cases, card payments require additional buyer input in the form of 3D Secure verification. In these cases, the PSP must treat the card payment as a redirection-based payment. See 3D Secure Payments for more information.

Here are some examples of instant card payments flows:

Instant approval

1. Wix calls Create Transaction. The total amount for the payment and the credit card details are included in the request body as follows:

   Copy

2. The PSP approves the payment and responds with an HTTP status code of 200, and this JSON object:

   Copy

3. The PSP sends this webhook to Submit Event:

   Copy

4. Wix marks the payment as approved and responds with an HTTP status code of 200 and an empty JSON object.

Instant decline

1. Wix calls Create Transaction. The remaining card limit isn't enough to cover the payment. The PSP responds with an HTTP status code of 200, and the following JSON object:

   Copy

2. The PSP sends this webhook to Submit Event:

   Copy

3. Wix marks the payment as declined and responds with an HTTP status code of 200 and an empty JSON object.

Payment is pending and moves to the final state

1. Wix calls Create Transaction. The payment requires fraud verification. The PSP responds with an HTTP status code of 200 and this JSON object:

   Copy

2. The PSP sends this webhook to Submit Event:

   Copy

3. Wix marks the payment as pending and responds with an HTTP status code of 200, and an empty JSON object.

4. If the fraud verification passes, the PSP sends the following webhook to indicate a successful payment:

   Copy

5. Wix marks the payment as approved and responds with an HTTP status code of 200, and an empty JSON object.

6. If fraud verification fails, the PSP sends the following webhook:

   Copy

7. Wix marks the payment as declined and responds with an HTTP status code of 200 and an empty JSON object.

Digital wallet payments

The Payment Provider Platform supports payments from digital wallet services such as Google Pay. Digital wallet transaction requests are similar to credit card requests but include additional decrypted payment data. The platform will never send an encrypted digital wallet token such as a Google Pay token as part of a transaction request. Because of this, PSPs never need to contact merchants about these transactions. They should process these requests the same way they process credit card payments.

In some cases, digital wallet transactions require additional buyer input in the form of 3D Secure verification. In these cases, the PSP must treat the digital wallet payment as a redirection-based payment. See the examples below for more details.

Here are some examples of sample flows for the digital wallet services currently supported by the platform:

Google Pay

Google Pay transaction requests include the decrypted payment details from a Google Pay transaction as well other relevant data. These requests never include Card Verification Values (CVV) since these are not supported by Google Pay.

Google Pay instant approval

1. Wix calls Create Transaction. The total amount for the payment and the Google Pay payment details are included in the request body as follows:

   Copy

2. The PSP approves the payment and responds with an HTTP status code of 200, and this JSON object:

   Copy

3. The PSP sends this webhook to Submit Event:

   Copy

Google Pay instant decline

Instant decline Google Pay payments are handled the same way as instant decline credit card payments.

Google Pay with successful 3DS verification

1. Wix calls Create Transaction. The total amount for the payment and the Google Pay payment details are included in the request body as follows:

   Copy

2. The PSP responds with an HTTP status code of 200, and this JSON object.
   The object includes a redirectUrl field, whose value is the URL of the PSP's web page where the buyer can complete 3DS verification.

1. Wix opens the redirectUrl in an iframe or in a browser window for the buyer to complete verification.

2. If the verification succeeds, the PSP's page redirects the browser to the successUrl sent in the Create Transaction request. The PSP sends this webhook to Submit Event:

If the verification fails, is canceled, or is pending the PSP's page must redirect to other URLs and send different webhooks, depending on the case. See Redirection-based payments for more details.

Redirection-based payments

The Payment Provider Platform allows PSPs to support redirection-based payments. In these cases, buyers select a payment method, such as Paypal, during checkout. Wix then redirects the buyer to the PSP's web page to complete the payment. The PSP then redirects the buyer back to Wix. Wix supports a large number of payment methods. If the payment method you need isn't supported, you can implement a hosted-page payment flow. In this case, the buyer is redirected to a page hosted by the PSP where they can select a payment method.

Credit cards that require 3D Secure verification are also treated as redirection-based payments. See 3D Secure payments for more information.

Configure the redirection-based payment methods you support in your app's payment gateway extension in the Wix Developers Center.

Here is an example of a redirection-based payment flow:

1. Wix calls Create Transaction.
   If the payment method selected is supported by Wix, it's included as the value for the paymentMethod field in the request body. For hosted-page payments, a string representing the PSP's Wix app ID is included. The request body also includes an order.returnUrls field with the URLs of the pages to redirect the buyer to after handling the payment request. Here is a sample request body with the relevant fields highlighted:

   Copy

2. The PSP responds with an HTTP status code of 200, and this JSON object.
   The object includes a redirectUrl field, whose value is the URL of the PSP's web page where the buyer can complete the payment.

   Copy

3. Wix opens the redirectUrl in an iframe or in a browser window for the buyer to complete. There are 4 possible outcomes, depending on the buyer's actions. The PSP must respond to each outcome differently:

   1. Success: If the verification succeeds, the PSP's page redirects the browser to the successUrl sent in the Create Transaction request. The PSP sends this webhook to Submit Event:
      Copy

   2. Failure: If the verification fails, the PSP's page redirects the browser to the errorUrl sent in the Create Transaction request. The PSP sends a webhook indicating why the payment failed. For example:
      Copy

   3. Cancelation: If the buyer cancels the verification, the PSP's page redirects the browser to the cancelUrl sent in the Create Transaction request. The PSP sends this webhook:
      Copy

   4. Pending: If the verification is pending, the PSP's page redirects the browser to the pendingUrl sent in the Create Transaction request. The PSP sends this webhook with a 5005 reason code:
      Copy

4. In each case, Wix marks the payment appropriately and responds with an HTTP status code of 200 and an empty JSON object.

5. If the payment was pending, the PSP sends a webhook to update the payment as either approved or declined when it's finalized.

   Payment approved request:

   Copy

   Payment declined request:

   Copy

6. Wix marks the payment as approved or declined and responds with an HTTP status code of 200 and an empty JSON object.

3D secure payments

Cards that support 3D Secure (3DS) verification require buyers to complete an additional verification step when making a payment. This verification step is completed on a web page hosted by the PSP. The flow for handling 3DS payments is similar to the flow for other redirection-based payments. The difference is that the value of paymentMethod in the Create Transaction request body is creditCard. It's up to the PSP to determine if the card supports 3DS verification and send the appropriate redirect response.

Recurring payments

Recurring payments (also known as subscription payments, automatic payments, or recurring billing) occur when buyers authorize a merchant to charge them repeatedly for goods or services on a prearranged schedule such as monthly, weekly, or annually. In these cases, Wix sends a request to the PSP to set up the recurring payment. The PSP responds with a unique identifier for the recurring payment. Wix uses this identifier to charge the buyer based on an agreed schedule.

The Payment Provider Platform supports these unique identifiers for recurring payments:

• Network ID: An ID representing a payment created by credit card networks such as Visa and Mastercard. These IDs are used to represent the recurring payment in the card network. The PSP requests the ID from the credit card network and sends it to Wix.
• Token: A token representing a payment created by the PSP. Both the PSP and Wix store the token locally and use it to represent the recurring payment.

The payment processing flow for recurring payments includes these phases:

• Setting up an "off-session" payment. This is a payment where a buyer allows a merchant to charge them in certain cases even when the buyer isn't present to confirm the payment, such as a recurring payment.
• Processing the recurring payments.

Here are examples of each phase:

Off-session payment setup

1. Wix calls Create Transaction with a request to set up a recurring payment.
   This request looks the same as a credit card payment request, with one difference: it includes a setupCredentialsOnFile field whose value is an object with a field called offSession whose value is true. This flag indicates that Wix is requesting that the PSP set up a recurring payment, not process a one-time payment. Here is a sample request body with the relevant fields highlighted:
   Copy

2. If the card supports 3D Secure verification, the PSP must redirect the buyer to a 3DS verification page before proceeding. See 3D Secure payments for more information.
3. The PSP responds with an HTTP status code of 200, and a JSON object that includes a credentialsOnFile field. The value of this field depends on the type of recurring payment identifier the PSP supports.
   For network IDs, the response looks like this:
   Copy

   Note: If 3DS verification occurs, the PSP must include the dsTransactionId field in the cardReference object. This field's value is the ID of the 3DS verification transaction. For tokens, the response looks like this:

   Copy

4. The PSP sends a webhook to Submit Event to confirm the recurring payment setup request.
   For network IDs, the webhook looks like this:
   Copy

   For tokens, the webhook looks like this:
   Copy

5. Wix responds with an HTTP status code of 200, and an empty JSON object.

Processing recurring payments

1. Wix calls Create Transaction with a request to charge a recurring payment.
   This request's paymentMethod field has a value of creditCard. The request also includes a field called offSession whose value is true. This flag indicates that Wix is requesting that the PSP charge a recurring payment. The request's paymentMethodData field includes different data depending on the type of recurring payment identifier the PSP sent to Wix when the recurring payment was set up.

   For network ID payments:

   Copy

   For token payments:

   Copy

2. The PSP processes the payment and responds with an HTTP status code of 200, and this JSON object:

   Copy

3. The PSP sends this webhook to Submit Event:

   Copy

Mail Order/Telephone Order payments

A mail order/telephone order (MOTO) payment is a card-not-present transaction where a buyer provides a merchant with their order and payment details by regular mail, fax, or telephone. Once the order details are recorded in the Wix dashboard, Wix sends a request to the PSP to process the payment. This request is the same a standard credit card request, except it includes a field called moto whose value is true. The flow for processing this request is the same as for regular card payments.

POS card reader payments

1. Wix calls Create Transaction. The total amount for the payment and the Card reader payment details are included in the request body as follows:

   Copy

2. The PSP makes the card reader identified by terminalId to wait for a card and responds with an HTTP status code of 200 and this JSON object. The redirectUrl points to a page with payment instructions reflecting the current state of the payment.

   Copy

3. Once transaction is done, PSP sends webhook to Submit Event:

   Copy