Connecting Accounts

When a merchant requests to connect their Wix site to a Payment Service Provider (PSP), Wix sends a request to the PSP's Connect Account endpoint. The PSP must verify the request and respond to Wix with any extra credentials needed for the merchant's account. This article includes general information about implementing the Connect Account endpoint as well as some sample flows.

Implement the Connect Account endpoint

Every request sent by Wix to the Connect Account endpoint includes these fields:

• credentials: An object containing credentials provided by the merchant when they make the connection request. A PSP can configure the credentials fields that are requested in the Wix Developers Center.
• wixMerchantId: The merchant's Wix merchant ID. This is a unique identifier for the merchant.

Requests can also include these optional fields:

• country: The country where the merchant is located.
• currency: The currency used by the merchant.

After receiving a request, the PSP must take the following steps:

• Verify the credentials provided by the merchant.
• Ensure the merchant has an operational account with the PSP.
• If possible, ensure the site's country and currency are appropriate for further payments.

  Note: The site's country and currency can change after the merchant connects their account. The PSP must validate the currency on each payment request.

The Connect Account endpoint's response must include the following fields:

• accountId: A unique identifier for the merchant's account. This value must be the same if the merchant connects their account multiple times from the same site.
• accountName: The name of the merchant's PSP account. This value is displayed partially in the Wix dashboard.
  
• credentials: The credentials received in the request plus any other credentials the merchant needs to make payment and refund requests. This object is included by Wix in all Create Transaction and Refund Transaction requests. This object can only contain string values, so booleans, numbers, or dates must be represented as strings.

Wix uses reason codes to indicate the statuses of account connection requests. A PSP's Create Account endpoint should respond with the appropriate reason code for each status. For a list of reason codes, see Reason Codes.

Requests made to the Connect Account 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.

Sample flows

Here are some examples of how to implement the Connect Account endpoint. The examples are applicable for both live and sandbox modes.

Basic account connection

1. Wix calls Connect Account with the following request body:
   Copy

   1
   {
   2
     "credentials": {
   3
       "client_id": "john@example.com",
   4
       "client_secret": "asdjdj44-asdd-3445566fdss"
   5
     },
   6
     "country": "US",
   7
     "currency": "USD",
   8
     "mode": "live",
   9
     "wixMerchantId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1"
   10
   }

2. The PSP responds with an HTTP status code of 200 and this JSON object:
   Copy

   1
   {
   2
     "credentials": {
   3
       "client_id": "john@example.com",
   4
       "client_secret": "asdjdj44-asdd-3445566fdss"
   5
     },
   6
     "accountId": "e89b-12d3-a456-42665",
   7
     "accountName": "jane.brown@example.com"
   8
   }

Adding numeric and boolean credentials when connecting

1. Wix calls Connect Account with the following request body:

   Copy

   1
   {
   2
     "credentials": {
   3
       "client_id": "john@example.com",
   4
       "client_secret": "asdjdj44-asdd-3445566fdss"
   5
     },
   6
     "country": "US",
   7
     "currency": "USD",
   8
     "mode": "live",
   9
     "wixMerchantId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1"
   10
   }

2. The PSP responds with an HTTP status code of 200 and a JSON object that adds boolean and numeric values to the credentials object:

   Copy

   1
   {
   2
     "credentials": {
   3
       "client_id": "john@example.com",
   4
       "client_secret": "asdjdj44-asdd-3445566fdss"
   5
       "price_includes_tax": "true",
   6
       "tax_percentage": "20"
   7
     },
   8
     "accountId": "e89b-12d3-a456-42665",
   9
     "accountName": "jane.brown@example.com"
   10
   }

Failed account connection

1. Wix calls Connect Account with the following request body:
   Copy

   1
   {
   2
     "credentials": {
   3
       "client_id": "john@example.com",
   4
       "client_secret": "asdjdj44-asdd-3445566fdss"
   5
     },
   6
     "country": "US",
   7
     "currency": "USD",
   8
     "mode" : "live",
   9
     "wixMerchantId": "a15a3ee3-22d3-4a3f-920e-2186e13a19d1"
   10
   }

2. The PSP responds with a 200 HTTP status code and the following JSON object. The response contains a 2009 reason code, which indicates that the PSP doesn't support the site's currency. The values of the errorCode and errorMessage fields can be customized by the PSP. To find reason codes for other cases, see Reason Codes.
   Copy

   1
   {
   2
     "reasonCode": 2009,
   3
     "errorCode": "CURRENCY_NOT_SUPPORTED",
   4
     "errorMessage": "USD is not supported"
   5
   }