Introduction

The Payment Provider service plugin (formerly SPI) provides functionality for integrating your site with payment providers not currently supported by Wix.

With this service plugin, you can:

  • Control the way your site connects to a payment provider.
  • Handle transactions processed by a payment provider.
  • Handle refunds processed by a payment provider.

Learn more about using the Payment Provider service plugin.

To add a service plugin

  1. Add the plugin to your site.
  2. Update the getConfig() function in the -config.js file that is added to your site during step 1.
  3. Update the connectAccount(), createTransaction(), and refundTransaction() functions in the .js file that is added to your site during step 1.
Did this help?

Reason Codes

Wix uses codes to represent detailed information about the statuses of different payment related processes. These codes are used to display information about these processes on your site's dashboard.

Reason codes can be divided into 4 groups:

  1. Account connection failures
  2. Pending transactions
  3. Declined transactions
  4. Declined refunds

If you can't find a corresponding reason code for your scenario, use 6000 and provide an appropriate errorCode and errorMessage with your response.

Account connection failure codes

Reason CodeName
2000Merchant account is not active
2001Merchant account blocked or restricted
2002Merchant account invalid
2003Merchant account expired
2004Merchant authorization failed
2005Merchant contact provider
2006Merchant limit exceeded
2007Payment method is not activated
2008Merchant account is in test mode
2009Merchant account does not match currency

Pending transaction codes

Note When state is set to Pending, the transaction is likely to be approved in the future.

Reason CodeName
5005Pending fraudulent transaction

Declined transaction codes

Reason CodeName
3000General bank decline
3001Invalid amount
3002Transaction type is not supported
3003Currency is not supported
30043D secure failed
30053D secure not enabled
3006Country is not supported
3007Conversion error
3008Address verification failed
3009Buyer to repeat purchase
3010Return buyer to provider
3011AVS CVC check failed
3012Insufficient funds
3013Card expired
3014Invalid expiration date
3015Invalid card number
3016Invalid CVV CVC
3017Card type not supported
3018Too many requests
3019Card limit exceeded
3020Test card declined
3021Tokenization issue
3026Receiving limit
3027Transaction already processed
3028Insufficient funds wallet
3029Expired payment source
3030Buyer canceled
3031Transaction action already committed
3034Installments failed
3035Transaction expired
3036Invalid PIN
3037Terminal not available
3038Revocation of payment
3039Payment account invalid
3040Security violation
3041Invalid account
3042Do not try again
3043Buyer revoked authorization
3044Bank notification failed
3045Mandate canceled
3046Mandate not active
4000Cart amount does not match order
4001Billing address missing
4002Shipping address missing
4003ZIP code missing
4004Phone number missing or invalid
5000Lost or stolen card
5001Risk management declined
5002Restricted or blocked card
5003Restricted or blocked buyer
5004Buyer declined and contact provider
5006Risk bank decline
5007Pick up card
5009Pending general
6000General error

Declined refund codes

Reason CodeName
3022Refund not allowed
3023Payment already refunded
3024Partial refund not allowed
3025Insufficient funds for refund
3032Refund attempts exceeded
3033Refund time limit exceeded
Did this help?

connectAccount( )


Retrieves information for connecting a new payment provider account.

This function is called by Wix Payments when you try to connect a custom payment provider from your site's dashboard. When neccessary, the code implemented in this function creates a new account on the payment provider's side. The function returns the payment provider account information, or error information if account creation fails. Wix uses the return values from this function when connecting the payment provider to the site.

Note: This function has a second parameter called context. This parameter is for internal Wix use only. You don't need to use it in your code.

Where to find connectAccount()

When you add the Payment Provider service plugin, a folder is automatically added to your site. Use the .js file in the folder to write the custom code for your payment provider.

For more information on customizing your payment provider, see Tutorial: Payment Provider Service Plugin.

Method Declaration
Copy
function connectAccount(
  options: ConnectAccountOptions,
  context: Context,
): Promise<ConnectAccountResponse>;
Method Parameters
optionsConnectAccountOptionsRequired

Information to use when connecting a new payment provider account.


contextContextRequired

Metadata about the request.

Returns
Return Type:Promise<ConnectAccountResponse>
JavaScript
// Place this code in the <my-plugin-name>.js file // in the 'payment-provider' folder of the // Service Plugins section on your site. export const connectAccount = async (options) => { //Logic for creating a new payment provider account, if needed. return { credentials: { client_id: "1k2k55k3k2llsssl23l45k6", client_secret: "19x92ujd0-183ec-asddfasdfasd44ger-234", }, accountId: "9123467-a3e5-d4556-ff466742-234dd32dfq3456", accountName: "jane.brown@example.com", }; };
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

createTransaction( )


Retrieves information about a newly created payment provider transaction.

This function is called by Wix Payments when a site visitor places an order on your site. The code implemented in this function creates a new transaction with a payment provider. The function returns the transaction information, or error information if transaction creation fails. Wix uses the return values from this function to add the new transaction to your site.

Note: This function has a second parameter called context. This parameter is for internal Wix use only. You don't need to use it in your code.

Where to find createTransaction()

When you add the Payment Provider service plugin, a folder is automatically added to your site. Use the .js file in the folder to write the custom code for your payment provider.

For more information on customizing your payment provider, see Tutorial: Payment Provider Service Plugin.

Method Declaration
Copy
function createTransaction(
  options: CreateTransactionOptions,
  context: Context,
): Promise<CreateTransactionResponse>;
Method Parameters
optionsCreateTransactionOptionsRequired

Information to use when creating a new transaction.


contextContextRequired

Metadata about the request.

Returns
Return Type:Promise<CreateTransactionResponse>
JavaScript
// Place this code in the <my-plugin-name>.js file // in the 'payment-provider' folder of the // Service Plugins section on your site. export const createTransaction = async (options) => { //Logic for creating a new transaction with the payment provider. return { pluginTransactionId: "1832456-3561234", }; };
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getConfig( )


Retrieves the configuration of your payment provider plugin.

Set your payment provider configuration in the return of the getConfig() function. Wix calls this function when you publish your site. Changes to the configuration don't take effect until you publish your site.

The object returned by getConfig() includes the information about your plugin that displays in your site's Connect, Accept Payments, and Checkout pages.

Where to find getConfig()

When you add the Payment Provider service plugin, a folder is automatically added to your site. Use the -config.js file in the folder to set the default configuration for your implementation of the custom plugin.

For more information on setting your configuration, see Tutorial: Payment Provider Service Plugin.

Method Declaration
Copy
function getConfig(): Promise<PaymentProviderConfigResponse>;
Request
This method does not take any parameters
Returns
Return Type:Promise<PaymentProviderConfigResponse>
Example of a configuration file
JavaScript
// Place this code in the <my-plugin-name>-config.js file // in the 'payment-provider' folder of the // Service Plugins section on your site. export function getConfig() { return { title: "Banana Payments", paymentMethods: [ { hostedPage: { title: "Banana Payments", billingAddressMandatoryFields: ["CITY"], logos: { white: { svg: "https://static.wixstatic.com/shapes/94b5e2_403ceb582027431cb92f38fd18d1843c.svg", png: "https://freesvg.org/img/15930333081593032446pitr_Bananas_icon.png", }, colored: { svg: "https://static.wixstatic.com/shapes/94b5e2_403ceb582027431cb92f38fd18d1843c.svg", png: "https://freesvg.org/img/15930333081593032446pitr_Bananas_icon.png", }, }, }, }, ], credentialsFields: [ { simpleField: { name: "clientId", label: "API id", }, }, { simpleField: { name: "clientSecret", label: "API secret", }, }, ], }; }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

refundTransaction( )


Retrieves payment provider information about a newly created refund.

This function is called by Wix Payments when you create a refund from your site's dashboard. The code implemented in this function sends a request to the payment provider's API to create a refund. The function returns refund information from the payment provider, or error information if refund creation fails. Wix uses the information returned by this function to add the refund to your site.

Note: This function has a second parameter called context. This parameter is for internal Wix use only. You don't need to use it in your code.

Where to find refundTransaction()

When you add the Payment Provider service plugin, a folder is automatically added to your site. Use the .js file in the folder to write the custom code for your payment provider.

For more information on customizing your payment provider, see Tutorial: Payment Provider Service Plugin.

Method Declaration
Copy
function refundTransaction(
  options: RefundOptions,
  context: Context,
): Promise<RefundResponse>;
Method Parameters
optionsRefundOptionsRequired

Information to use when creating a refund request.


contextContextRequired

Metadata about the request.

Returns
Return Type:Promise<RefundResponse>
JavaScript
// Place this code in the <my-plugin-name>.js file // in the 'payment-provider' folder of the // Service Plugins section on your site. export const refundTransaction = async (options, context) => { //Logic for refunding a transaction with the payment provider. return { pluginRefundId: "16423-234234", }; };
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?