About the Transactions API

Use Wix Payments server-to-server API integration to accept different payment methods and manage transactions. Wix Payments act as a standalone solution to independently process payments, deal with chargebacks and disputes via Wix infrastructure, and can be used by any third-party.

Wix Payments integration prerequisites

Before testing the Transactions API, you need to get a Wix Payments account ID. Wix also applies a Know Your Customer (KYC) and evaluation procedure. Contact Wix via transactions-api-support@wix.com and provide the following details to start the evaluation process:

  • Put "Wix Payments integration" in the subject of the email.
  • Provide your name and email.
  • Include the purpose of your integration with the Transactions API.

Transactions API supports the following flows:

  • Authorization (reserving funds)
  • Capture (transferring of reserved funds)
  • One-time transaction (Authorization and Capture)
  • Recurring transactions (MIT and CIT)
  • Refund/Void (canceling an authorized or captured transaction)
  • Dispute

Wix Payments supports the following payment methods:

  • Card
  • ACH
  • Apple Pay
  • Boleto
  • Giropay
  • iDEAL
  • PayPal
  • Pix
  • SEPA
  • SOFORT

Terminology

  • Merchant: A party selling goods or services to customers via an eCommerce website, a mobile app, on the point of sale, or across all three channels. Wix Payments enable a merchant to accept payments from customers made with cards or local payment methods and manage payouts.
  • Customer: Someone who buys goods or services from a merchant. In terms of Transactions API, a customer makes a cashless online payment by using either cards or local payment methods to pay.
  • Cardholder: Customer who uses a card issued by a bank to make cashless online payments to a merchant.
  • Transaction: Agreement between a merchant and a customer to exchange goods, services, or financial instruments. The transaction object contains the basic information required to securely process the payment, execute related actions (delivery, analytics, inventory management) and comply with financial regulations.
  • Merchant Initiated Transaction (MIT): Payment or a series of payments with fixed or variable amounts that the merchant performs without direct involvement of a customer, such as automatic account top-ups, and installments.
  • Cardholder Initiated Transaction (CIT): Payment initiated by the cardholder on their own after the initial successful transaction.
  • Authorization: Process of card issuer verifying payment details and reserving funds to capture them later. When the card is verified with the issuer, the funds are reserved for the transaction.
  • Transaction reference: Transaction ID of the first transaction for recurring transactions. It should be passed with each subsequent transaction.
  • Capture: Transfer of reserved funds from the customer to the merchant. A payment that was already authorized, must be captured to be completed.
  • Refund Transfer of funds from the merchant back to the customer - merchant-initated. When the merchant makes a refund, the funds are sent back to the card issuer. If an authorized payment hasn't been captured yet, a refund can't be made, but the merchant can void the payment instead.
  • Void: Voiding a transaction will tell the customer’s card issuing bank that the merchant does not intend to collect the transaction corresponding to the original six-digit approval code and, therefore, those held funds are made available to the customer again. Merchant can void a transaction until it is captured.
  • Dispute: Refers to the entire process from the moment the customer applies to their issuing bank. Dispute occurs when a cardholder questions the charge with their card issuer and initiates a chargeback. When this happens, the merchant is given the opportunity to respond to the dispute with evidence that shows that the charge is legitimate.
  • Request for Information (RFI): Optional first step in a dispute, initiated when the cardholder does not recognize or disagrees with a charge and requests more information from their bank.
  • Chargeback: Second and primary step in a dispute. It includes a reversal of a credit card payment that comes directly from the bank. Chargeback occurs when a cardholder questions a transaction and asks their card-issuing bank to reverse it.
  • Evidence: Documentation in response to the dispute (RFI or chargeback steps), appropriate to the reason for the dispute. For example, evidence responding to a dispute with the reason “product not received” can include shipping information and any screenshots of package tracking. Weblogs, email communications, shipment tracking numbers, delivery confirmation, proof of prior refunds, or replacement shipments can all be helpful.

Recurring transactions

Wix Payments API allows merchants to set up recurring payments. It adds flexibility and full control of the entire business flow. For subsequent transactions, only the card_number should be tokenized using the Create Card Token endpoint, and the appropriate token passed to the Create Transaction.

Note to achieve the best approve ratio, the correct MIT/CIT flag must be passed as well. To achieve the best approve ratio, pass all possible values received from the card schemes:

  • Network_transaction_id
  • ds_transaction_id (in case the initial transaction was performed by the 3DS2 regulations)

Create Transaction endpoint is fully compatible with the new PSD2 regulations and supports 3DS 2 mechanism.

Interaction types

Interaction TypeAdditional ParametersComments
ONE_TIMERegular one-time transaction
SETUP_COF_ONSESSIONInitial transaction with the subsequent CIT (setup one-click)
SETUP_COF_RECURRINGInitial transaction with the subsequent MIT transactions according to a defined schedule
SETUP_COF_UNSCHEDULEDInitial transaction with the subsequent MIT transactions without the defined schedule
COF_ONSESSIONtransaction_referenceSubsequent transaction initiated by the customer (perform one-click)
COF_RECURRINGtransaction_referenceRecurring transactions initiated by the merchant according to the defined schedule
COF_UNSCHEDULEDtransaction_referenceRecurring transactions initiated by the merchant without a schedule

Use cases

Create and manage transactions with the following flows:

  1. Create a one-time payment and simultaneously authorize and capture funds.
  2. Create a one-time payment. Authorize and Capture the funds separately.
  3. Create a first/initial recurring payment and subsequent one when the cardholder is not present - authorization and capture in one step.
  4. Create an initial “on session” (cardholder present) payment and notify Wix of credential storage to execute a subsequent one in the future when the cardholder is present.
  5. Charge a customer and refund funds afterwards.

1. Create a one-time payment and simultaneously authorize and capture funds.

Transaction info: $10 USD, one-time credit card transaction, using a card token. A new card_token must be generated for each transaction request.
(A card token must be passed to Create Transaction when a credit/debit card is the chosen payment method.)

To create a transaction, call Create Transaction.

Parameters to include:

Copy Code
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": "1000",
"currency": "USD",
"paymentMethodTypeId": "creditCard",
"card": {
"numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",
"expiryMonth": 11,
"expiryYear": 2027,
"holderName": "John Doe",
"securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"
},
"automaticCapture": {},
"oneTimePayment": {}
}

Note: Pass an empty object for the type of transaction oneTimePayment, but not null or missing.

2. Create a one-time payment. Authorize and Capture the funds separately.

Transaction info: $10 USD, one-time credit card transaction, using a card token. A new card_token must be generated for each transaction request.
(A card token must be passed to Create Transaction when a credit/debit card is the chosen payment method.)

  1. Call Create Transaction.

Parameters to include:

Copy Code
POST https://www.wixapis.com/payments/v3/transactions
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": "1000",
"currency": "USD",
"paymentMethodTypeId": "creditCard",
"card": {
"numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",
"expiryMonth": 11,
"expiryYear": 2027,
"holderName": "John Doe",
"securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"
},
"oneTimePayment": {}
}
  1. Call Capture Transaction. Retrieve the transactionId from the step 1.

Parameters to include:

Copy Code
POST https://www.wixapis.com/payments/v3/transactions/2ac75a2-91d5-4752-6h96-6aj74640f1ef/capture
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef"
}

3. Create a first/initial recurring payment and subsequent one when the cardholder is not present - authorization and capture in one step.

Transaction info: $10 USD, one-time credit card transaction, using a card token. A new card_token must be generated for each transaction request.
(A card token must be passed to Create Transaction when a credit/debit card is the chosen payment method.)
When creating a recurring transaction (MIT/CIT), you only need to tokenize the card_number and pass it in the Create Transaction request together with COF.

  1. Call Create Transaction.

Parameters to include:

Copy Code
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": "1000",
"currency": "USD",
"paymentMethodTypeId": "creditCard",
"card": {
"numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",
"expiryMonth": 11,
"expiryYear": 2027,
"holderName": "John Doe",
"securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"
},
"automaticCapture": {}
"setupCofRecurring": {}
}
  1. Retrieve the transactionId of the created transaction from the response from step 1. (In this example, transactionId = 01csa932-9bd5-38d2-91d6-6jf5c640f1ef). You’ll need to pass it as the transactionReference in all subsequent transactions.

  2. When a subsequent payment is due, call Create Transaction and pass the transactionId from step 1 as the transactionReference.

Parameters to include:

Copy Code
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": "1000",
"currency": "USD",
"paymentMethodTypeId": "creditCard",
"card": {
"numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",
"expiryMonth": 11,
"expiryYear": 2027,
"holderName": "John Doe"
},
"automaticCapture": {},
"cofRecurring": {
"transactionReference": {
"transactionId": "01csa932-9bd5-38d2-91d6-6jf5c640f1ef"
}
}
}

4. Create an initial “on session” (cardholder present) payment and notify Wix of credential storage to execute a subsequent one in the future when the cardholder is present.

Transaction info: $10 USD, one-time credit card transaction, using a card token. A new card_token must be generated for each transaction request.
(A card token must be passed to Create Transaction when a credit/debit card is the chosen payment method.)
When creating a recurring transaction (MIT/CIT), you only need to tokenize the card_number and pass it in the Create Transaction request together with COF.

  1. Call Create Transaction.

Parameters to include:

Copy Code
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": "1000",
"currency": "USD",
"paymentMethodTypeId": "creditCard",
"card": {
"numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",
"expiryMonth": 11,
"expiryYear": 2027,
"holderName": "John Doe",
"securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"
},
"automaticCapture": {},
"setupCofOnSession": {}
}
  1. Retrieve the transactionId (in this example, transactionId = 01csa932-9bd5-38d2-91d6-6jf5c640f1ef). You’ll need to pass it as the transactionReference in all subsequent transactions.

  2. Call Create Transaction. transactionReference is the ID of the transaction in the response from step 1.

Parameters to include:

Copy Code
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": "1000",
"currency": "USD",
"paymentMethodTypeId": "creditCard",
"card": {
"numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",
"expiryMonth": 11,
"expiryYear": 2027,
"holderName": "John Doe",
"securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"
},
"automaticCapture": {},
"cofOnSession": {
"transactionReference": {
"transactionId": "01csa932-9bd5-38d2-91d6-6jf5c640f1ef"
}
}
}

5. Charge a customer and refund funds afterward.

Transaction info: $50 USD, one-time credit card transaction, using a card token.

  1. Call Create Transaction.

Parameters to include:

Copy Code
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": "5000",
"currency": "USD",
"paymentMethodTypeId": "creditCard",
"card": {
"numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",
"expiryMonth": 11,
"expiryYear": 2027,
"holderName": "John Doe",
"securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"
},
"automaticCapture": {},
"oneTimePayment": {}
}
  1. Call VoidOrRefund Transaction.

a. For a full refund:

Copy Code
POST https://www.wixapis.com/payments/v3/transactions/71c7932-9bd5-48d2-9196-6df4c640f1ef/capture
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef"
}

b. For a partial refund of $25:

Copy Code
POST https://www.wixapis.com/payments/v3/transactions/71c7932-9bd5-48d2-9196-6df4c640f1ef/capture
{
"accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",
"amount": 2500
}
Was this helpful?
Yes
No

Disputes Overview

The dispute process involves the following parties:

  1. Cardholder: The owner of the card involved in a transaction.
  2. Merchant: The party who sold the goods or services that are under dispute.
  3. Card Issuer: The bank that issued the card to the cardholder.
  4. Acquirer: The bank tasked with acquiring payment on the merchant's behalf.
  5. Card Association: The card brands (Visa, Mastercard, and others) oversee the process.

Dispute lifecycle

RFI

A dispute can be created upon receiving an RFI (Request For Information), which is a preliminary step before a chargeback (no movement of funds).

It starts with Open status - RFI_OPEN. In response, the merchant can either refund the payment or upload evidence with clarifications about the purchase.

If the merchant refunds the payment, the status will be updated to Refunded, and the dispute will not be escalated into a chargeback.

If the merchant provided evidence, the status will be updated to RFI_UNDER_REVIEW.

If the evidence provided proves sufficient, depending on the Card Scheme rules, the status will be updated to RFI_CLOSED, which means the RFI has timed out and did not escalate into a chargeback.

Chargeback

In some cases, a chargeback will follow an RFI if it wasn’t resolved at the RFI stage. However, in most cases the dispute is created as a Chargeback right away with the status CHARGEBACK_OPEN, and skips the optional RFI stage. At this point, the funds are deducted from the merchant’s account, and the merchant can’t refund the money on their own.

Merchants have a timeframe of 14-40 days (the time frame is being detected by the card scheme) to submit evidence against the chargeback. If no actions are taken within this timeframe, the chargeback status is updated to LOST.

Uploading evidence changes the dispute status to CHARGEBACK_UNDER_REVIEW. The evidence will be reviewed by the card schemes. The timeframe varies depending on the card scheme, up to 80 days in some cases.

Once the review is complete, the chargeback status will be updated to WON or LOST, as decided by the card issuer.

Dispute statuses:

  • RFI_OPEN - expecting evidence from the client
  • RFI_UNDER_REVIEW
  • RFI_CLOSED - final status
  • CHARGEBACK_OPEN - expecting evidence from the client
  • CHARGEBACK_UNDER_REVIEW
  • WON - final status
  • LOST - final status

Responding to disputes using the API

Step 1: Find out when a dispute is opened

Register the Transaction Updated Webhook to receive a transaction object with all the disputes statuses. All the transaction's disputes and their current status will be returned under updatedEvent > currentEntity > disputes.

Step 2: Decide how to deal with the dispute (accept or submit evidence).

To accept the dispute, skip to step 4. To submit evidence, go to step 3.

Step 3: Respond to the dispute with evidence

To respond to the RFI/chargeback, you should upload evidence, associate it with the correct dispute and submit the evidence to the issuing bank.

To upload evidence:

  1. Call Generate Evidence Upload Url.
  2. Retrieve the upload_url and upload_token.
  3. Call the retrieved upload_url as an HTTP POST, and pass the upload_token as a path parameter.

For example:

Copy Code
curl --location --request POST 'https://wixmp-90ef227251107558e3a6a71f.appspot.com/_ah/upload/test_upload_token_url/' \
--form 'upload_token="test_upload_token"' \
--form '=@"/example.pdf"'

Evidence Upload

  1. Retrieve the payload.id from the JSON response.
    For example:
Copy Code
{
"message": "OK",
"code": 0,
"payload": {
"mimeType": "image/jpeg",
"hash": "5d61d4349e8380b3eaa97e767391dfd9",
"dateCreated": "2020-09-04T13:54:12Z",
"id": "2411686768ca469dabd7cc64e52c502e",
"path": "/tenants/a001a0c3-0ffa-4b76-8a13-aa0df0d7913c/accounts/0f226e8a-3b1f-44de-8f3f-9a4abdab5db3/transactions/a036c
"lifecycle": null,
"size": 3733,
"urn": "urn:file:2411686768ca469dabd7cc64e52c502e",
"bucket": null,
"acl": "private",
"dateUpdated": "2020-09-04T13:54:12Z",
"type": "-"
}
}

payload.id should be passed as evidence.fileId below. (in this example, payload.id = "2411686768ca469dabd7cc64e52c502e")

Important: The evidence still needs to be associated with the relevant dispute after upload.

  1. Call Add Evidence to associate the evidence you uploaded with the relevant dispute. Pass the disputeId, transactionId, and accountId retrieved in step 1, and map the payload.id retrieved above to evidence.fileId.
  2. When all the evidence has been uploaded and associated with the dispute, call Submit Evidence to trigger the submission of the evidence to the issuing bank.

Step 4: Responding to a chargeback by accepting the dispute.

Accept the dispute by calling Accept Dispute - relevant only when the dispute status is CHARGEBACK_OPEN. This action moves the dispute status to LOST.

Was this helpful?
Yes
No

Transaction Object

Attributes
idstringformat GUID
Wix Payments transaction ID.

currencystringformat CURRENCY
Payment currency according to ISO 4217. For example: USD, EUR, GBP.

capturableAmountnumber
Amount that can be captured or voided in minor units. Usually matches authorization amount when the transaction has been authorized but not captured.

refundableAmountnumber
Amount that can be refunded in minor units. Usually matches capture amount when the transaction has been captured but not refunded or charged back.

externalInvoiceIdstringminLength 1maxLength 36
Invoice ID provided by the external entity that initiated the transaction.

externalOrderIdstringminLength 1maxLength 36
Order ID provided by the external entity that initiated the transaction.

externalTransactionIdstringminLength 1maxLength 36
Transaction ID provided by external entity.

providerTransactionIdstringminLength 1maxLength 1000
Transaction ID provided by the payment provider.

metadataobjectmaxItems 16format map
Metadata stored when the transaction is created.

authorizationobject
Transaction authorization information.

capturesArray <Capture>maxItems 1000
Captures issued for the transaction.

refundsArray <Refund>maxItems 1000
Refunds issued for the transaction.

disputesArray <Dispute>maxItems 1000
Disputes initiated for the transaction.

voidsArray <Void>maxItems 1000
Voids issued for the transaction.

accountIdstringformat GUID
Wix Payments account ID.

accountProfileIdstringformat GUID
Wix Payments account profile ID.

paymentMethodobject
Payment method used for payment.
Was this helpful?
Yes
No

PostCreate Transaction

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates initial request for a transaction to authorize and optionally capture funds. Capture can be executed separately with an additional API call. Use this endpoint to execute one-time and recurring payments.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Transactions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/payments/v3/transactions

Was this helpful?
Yes
No

GetGet Transaction

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves transaction info by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Disputes
Manage Refunds
Manage Transactions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

GET
https://www.wixapis.com/payments/v3/transactions/{transactionId}

Was this helpful?
Yes
No

PostCapture Transaction

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Manually captures an authorized transaction by ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Transactions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/payments/v3/transactions/{transactionId}/capture

Was this helpful?
Yes
No

PostVoid Or Refund Transaction

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Voids or refunds the transaction by ID. Voids if the transaction was only authorized. Refunds if the transaction was already captured.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Refunds
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/payments/v3/transactions/{transactionId}/refund

Was this helpful?
Yes
No

PostAccept Dispute

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Accepts a dispute.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Disputes
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/payments/v3/transactions/{transactionId}/disputes/{disputeId}/accept

Was this helpful?
Yes
No

PostGenerate Evidence Upload Url

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Generates URL to upload evidence for a dispute.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Disputes
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/payments/v3/transactions/{transactionId}/disputes/{disputeId}/generate-evidence-upload-url

Was this helpful?
Yes
No

PostAdd Evidence

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Adds evidence to a dispute.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Disputes
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/payments/v3/transactions/{transactionId}/disputes/{disputeId}/add-evidence

Was this helpful?
Yes
No

PostSubmit Evidence

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Submits evidence and triggers the review process.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Disputes
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/payments/v3/transactions/{transactionId}/disputes/{disputeId}/submit-evidence

Was this helpful?
Yes
No

Transaction Created

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Permissions

PAYMENTS.TRANSACTIONS_READ
Learn more about permissions.

Event Body

Event Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.payments.transactions.v3.transaction.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

Transaction Updated

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Permissions

PAYMENTS.TRANSACTIONS_READ
Learn more about permissions.

Event Body

Event Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.payments.transactions.v3.transaction.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No