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:
Learn more about using the Payment Provider service plugin.
getConfig()
function in the -config.js file that is added to your site during step 1.connectAccount()
, createTransaction()
, and refundTransaction()
functions in the .js file that is added to your site during step 1.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:
If you can't find a corresponding reason code for your scenario, use 6000
and provide an appropriate errorCode
and errorMessage
with your response.
Reason Code | Name |
---|---|
2000 | Merchant account is not active |
2001 | Merchant account blocked or restricted |
2002 | Merchant account invalid |
2003 | Merchant account expired |
2004 | Merchant authorization failed |
2005 | Merchant contact provider |
2006 | Merchant limit exceeded |
2007 | Payment method is not activated |
2008 | Merchant account is in test mode |
2009 | Merchant account does not match currency |
Note
When state is set to Pending
, the transaction is likely to be approved in the future.
Reason Code | Name |
---|---|
5005 | Pending fraudulent transaction |
Reason Code | Name |
---|---|
3000 | General bank decline |
3001 | Invalid amount |
3002 | Transaction type is not supported |
3003 | Currency is not supported |
3004 | 3D secure failed |
3005 | 3D secure not enabled |
3006 | Country is not supported |
3007 | Conversion error |
3008 | Address verification failed |
3009 | Buyer to repeat purchase |
3010 | Return buyer to provider |
3011 | AVS CVC check failed |
3012 | Insufficient funds |
3013 | Card expired |
3014 | Invalid expiration date |
3015 | Invalid card number |
3016 | Invalid CVV CVC |
3017 | Card type not supported |
3018 | Too many requests |
3019 | Card limit exceeded |
3020 | Test card declined |
3021 | Tokenization issue |
3026 | Receiving limit |
3027 | Transaction already processed |
3028 | Insufficient funds wallet |
3029 | Expired payment source |
3030 | Buyer canceled |
3031 | Transaction action already committed |
3034 | Installments failed |
3035 | Transaction expired |
3036 | Invalid PIN |
3037 | Terminal not available |
3038 | Revocation of payment |
3039 | Payment account invalid |
3040 | Security violation |
3041 | Invalid account |
3042 | Do not try again |
3043 | Buyer revoked authorization |
3044 | Bank notification failed |
3045 | Mandate canceled |
3046 | Mandate not active |
4000 | Cart amount does not match order |
4001 | Billing address missing |
4002 | Shipping address missing |
4003 | ZIP code missing |
4004 | Phone number missing or invalid |
5000 | Lost or stolen card |
5001 | Risk management declined |
5002 | Restricted or blocked card |
5003 | Restricted or blocked buyer |
5004 | Buyer declined and contact provider |
5006 | Risk bank decline |
5007 | Pick up card |
5009 | Pending general |
6000 | General error |
Reason Code | Name |
---|---|
3022 | Refund not allowed |
3023 | Payment already refunded |
3024 | Partial refund not allowed |
3025 | Insufficient funds for refund |
3032 | Refund attempts exceeded |
3033 | Refund time limit exceeded |
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.
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.
function connectAccount(
options: ConnectAccountOptions,
context: Context,
): Promise<ConnectAccountResponse>;
Information to use when connecting a new payment provider account.
Metadata about the request.
// 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",
};
};
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
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.
function createTransaction(
options: CreateTransactionOptions,
context: Context,
): Promise<CreateTransactionResponse>;
Information to use when creating a new transaction.
Metadata about the request.
// 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",
};
};
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
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.
function getConfig(): Promise<PaymentProviderConfigResponse>;
// 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",
},
},
],
};
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
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.
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.
function refundTransaction(
options: RefundOptions,
context: Context,
): Promise<RefundResponse>;
Information to use when creating a refund request.
Metadata about the request.
// 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",
};
};
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.