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 Type | Additional Parameters | Comments |
---|---|---|
ONE_TIME | Regular one-time transaction | |
SETUP_COF_ONSESSION | Initial transaction with the subsequent CIT (setup one-click) | |
SETUP_COF_RECURRING | Initial transaction with the subsequent MIT transactions according to a defined schedule | |
SETUP_COF_UNSCHEDULED | Initial transaction with the subsequent MIT transactions without the defined schedule | |
COF_ONSESSION | transaction_reference | Subsequent transaction initiated by the customer (perform one-click) |
COF_RECURRING | transaction_reference | Recurring transactions initiated by the merchant according to the defined schedule |
COF_UNSCHEDULED | transaction_reference | Recurring transactions initiated by the merchant without a schedule |
Use cases
Create and manage transactions with the following flows:
- Create a one-time payment and simultaneously authorize and capture funds.
- Create a one-time payment. Authorize and Capture the funds separately.
- Create a first/initial recurring payment and subsequent one when the cardholder is not present - authorization and capture in one step.
- 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.
- 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:
1{2 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",3 "amount": "1000",4 "currency": "USD",5 "paymentMethodTypeId": "creditCard",6 "card": {7 "numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",8 "expiryMonth": 11,9 "expiryYear": 2027,10 "holderName": "John Doe",11 "securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"12 },13 "automaticCapture": {},14 "oneTimePayment": {}15}
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.)
- Call Create Transaction.
Parameters to include:
1POST https://www.wixapis.com/payments/v3/transactions2
3{4 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",5 "amount": "1000",6 "currency": "USD",7 "paymentMethodTypeId": "creditCard",8 "card": {9 "numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",10 "expiryMonth": 11,11 "expiryYear": 2027,12 "holderName": "John Doe",13 "securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"14 },15 "oneTimePayment": {}16}
- Call Capture Transaction. Retrieve the transactionId from the step 1.
Parameters to include:
1POST https://www.wixapis.com/payments/v3/transactions/2ac75a2-91d5-4752-6h96-6aj74640f1ef/capture2
3{4 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef"5}
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.
- Call Create Transaction.
Parameters to include:
1{2 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",3 "amount": "1000",4 "currency": "USD",5 "paymentMethodTypeId": "creditCard",6 "card": {7 "numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",8 "expiryMonth": 11,9 "expiryYear": 2027,10 "holderName": "John Doe",11 "securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"12 },13 "automaticCapture": {}14 "setupCofRecurring": {}15}
-
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 thetransactionReference
in all subsequent transactions. -
When a subsequent payment is due, call Create Transaction and pass the
transactionId
from step 1 as thetransactionReference
.
Parameters to include:
1{2 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",3 "amount": "1000",4 "currency": "USD",5 "paymentMethodTypeId": "creditCard",6 "card": {7 "numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",8 "expiryMonth": 11,9 "expiryYear": 2027,10 "holderName": "John Doe"11 },12 "automaticCapture": {},13 "cofRecurring": {14 "transactionReference": {15 "transactionId": "01csa932-9bd5-38d2-91d6-6jf5c640f1ef"16 } 17 }18}
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.
- Call Create Transaction.
Parameters to include:
1{2 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",3 "amount": "1000",4 "currency": "USD",5 "paymentMethodTypeId": "creditCard",6 "card": {7 "numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",8 "expiryMonth": 11,9 "expiryYear": 2027,10 "holderName": "John Doe",11 "securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"12 },13 "automaticCapture": {},14 "setupCofOnSession": {}15}
-
Retrieve the transactionId (in this example,
transactionId
= 01csa932-9bd5-38d2-91d6-6jf5c640f1ef). You’ll need to pass it as thetransactionReference
in all subsequent transactions. -
Call Create Transaction.
transactionReference
is the ID of the transaction in the response from step 1.
Parameters to include:
1{2 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",3 "amount": "1000",4 "currency": "USD",5 "paymentMethodTypeId": "creditCard",6 "card": {7 "numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",8 "expiryMonth": 11,9 "expiryYear": 2027,10 "holderName": "John Doe",11 "securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"12 },13 "automaticCapture": {},14 "cofOnSession": {15 "transactionReference": {16 "transactionId": "01csa932-9bd5-38d2-91d6-6jf5c640f1ef"17 } 18 }19}
5. Charge a customer and refund funds afterward.
Transaction info: $50 USD, one-time credit card transaction, using a card token.
- Call Create Transaction.
Parameters to include:
1{2 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",3 "amount": "5000",4 "currency": "USD",5 "paymentMethodTypeId": "creditCard",6 "card": {7 "numberToken": "41c29a2-9bd5-4552-1296-6a24c6g0f1ef",8 "expiryMonth": 11,9 "expiryYear": 2027,10 "holderName": "John Doe",11 "securityCodeToken": "71c7932-9bd5-48d2-9196-6df4c640f1ef"12 },13 "automaticCapture": {},14 "oneTimePayment": {}15}
- Call VoidOrRefund Transaction.
a. For a full refund:
1POST https://www.wixapis.com/payments/v3/transactions/71c7932-9bd5-48d2-9196-6df4c640f1ef/capture2
3{4 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef"5}
b. For a partial refund of $25:
1POST https://www.wixapis.com/payments/v3/transactions/71c7932-9bd5-48d2-9196-6df4c640f1ef/capture2
3{4 "accountId": "81c79a2-9bd5-4852-9296-6a24c640f1ef",5 "amount": 25006}
Disputes Overview
The dispute process involves the following parties:
- Cardholder: The owner of the card involved in a transaction.
- Merchant: The party who sold the goods or services that are under dispute.
- Card Issuer: The bank that issued the card to the cardholder.
- Acquirer: The bank tasked with acquiring payment on the merchant's behalf.
- Card Association: The card brands (Visa, Mastercard, and others) oversee the process.
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:
- Call Generate Evidence Upload Url.
- Retrieve the
upload_url
andupload_token
. - Call the retrieved
upload_url
as an HTTP POST, and pass theupload_token
as a path parameter.
For example:
1curl --location --request POST 'https://wixmp-90ef227251107558e3a6a71f.appspot.com/_ah/upload/test_upload_token_url/' \2--form 'upload_token="test_upload_token"' \3--form '=@"/example.pdf"'
- Retrieve the
payload.id
from the JSON response.
For example:
1{2 "message": "OK",3 "code": 0,4 "payload": {5 "mimeType": "image/jpeg",6 "hash": "5d61d4349e8380b3eaa97e767391dfd9",7 "dateCreated": "2020-09-04T13:54:12Z",8 "id": "2411686768ca469dabd7cc64e52c502e",9 "path": "/tenants/a001a0c3-0ffa-4b76-8a13-aa0df0d7913c/accounts/0f226e8a-3b1f-44de-8f3f-9a4abdab5db3/transactions/a036c10 "lifecycle": null,11 "size": 3733,12 "urn": "urn:file:2411686768ca469dabd7cc64e52c502e",13 "bucket": null,14 "acl": "private",15 "dateUpdated": "2020-09-04T13:54:12Z",16 "type": "-"17 }18}
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.
- Call Add Evidence to associate the evidence you uploaded with the relevant dispute. Pass the
disputeId
,transactionId
, andaccountId
retrieved in step 1, and map thepayload.id
retrieved above toevidence.fileId
. - 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.
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: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: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: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: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: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: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: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:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.