POST

Create 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.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Managed Payments- All Permissions
Manage Transactions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/transaction-service/v3/transactions

Body Params
accountIdstringRequiredformat GUID

Wix Payments account ID.


paymentMethodTypestringdeprecated

Do not use this field.


paymentMethodTypeIdstring

Type ID of payment method to use. Supported values are creditCard, cardReader, ach, applePay, googlePay, boleto, giropay, iDeal, payPal, pix, sepa, sofort, razorpay. Pass specific data for each payment method type using a corresponding parameter. For example, pass the parameter card when passing creditCard for this field.


amountnumber

Payment amount in minor units, for example, cents.


currencystringRequiredformat CURRENCY

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


idempotencyKeystringminLength 1maxLength 36

Key to ensure idempotency.


externalTransactionIdstringminLength 1maxLength 36

Corresponding transaction ID within the external entity that initiated the transaction.


externalInvoiceIdstringminLength 1maxLength 36

Corresponding invoice ID within the external entity that made the request.


externalOrderIdstringminLength 1maxLength 36

Order ID provided by the external entity that initiated the request.


externalBuyerIdstringminLength 1maxLength 36

Customer ID provided by the external entity that initiated the request.


automaticCaptureAutomaticCapture

Whether to capture this transaction automatically. When not passed, the transaction can be manually captured later.


returnUrlstringmaxLength 1000

URL to return to after redirection to the payment approval page.


installmentCountintegerminimum 2maximum 1000format uint32

Number of installments (must be greater than 1 to trigger payment in installments).


itemsArray <Item>maxItems 1000

Order line items.


billingAddressBillingAddress

Billing address.


shippingAddressShippingAddress

Shipping address.


riskDataRiskData

Payment information for the transaction's risk evaluation score.


externalFeeintegerformat uint64

Additional application-specific fee in minor units, for example, cents.


metadataMap <string, string>maxItems 16format map

Metadata to store within the created transaction.


softDescriptorstringmaxLength 20

Complete description that appears on the customers' statements.


amountBreakdownAmountBreakdown

Amount breakdown.


forceScaboolean

Prefer Strong Customer Authentication


ONE OF:

oneTimePaymentOneTimePayment

One-time on-session payment.


setupCofOnSessionSetupCofOnSession

On-session payment followed by the storing of credentials to enable future transactions initiated by the cardholder. For example, one-click purchases.


setupCofRecurringSetupCofRecurring

On-session payment followed by the storing of credentials to enable future recurring transactions initiated by the merchant. For example, regular subscription charges.


setupCofUnscheduledSetupCofUnscheduled

On-session payment followed by the storing of credentials to enable future unscheduled transactions initiated by the merchant. For example, automatic top-ups.


cofOnSessionCofOnSession

On-session transaction initiated by the cardholder. For example, a one-click purchase.


cofRecurringCofRecurring

Off-session recurring transaction initiated by the merchant. For example, a regular subscription charge.


cofUnscheduledCofUnscheduled

Off-session unscheduled transaction initiated by the merchant. For example, an automatic top-up.


ONE OF:

cardCard

Credt/debit card information.


cardReaderCardReader

Point of sale with Wix Payments.


idealIdeal

iDEAL is an online payment method in Netherlands.


achAch

ACH network.


applePayApplePay

Mobile payment and digital wallet service provided by Apple Inc.


googlePayGooglePay

Mobile payment and digital wallet service provided by Google LLC.


boletoBoleto

Boleto Bancário, commonly known as Boleto, is a popular Brazilian cash-based payment method.


sepaSepa

The Single Euro Payments Area (SEPA) is a payment-integration initiative of the European Union for simplification of bank transfers denominated in euro.


pixPix

Pix is a popular Brazilian QR Code based payment method.


tokenizedTokenized

payment method tokenized by caller and it's token is passed instead

Response Object
transactionTransaction

Transaction information.

Create a transaction object and only authorize the funds

Request
cURL
curl -X POST \ https://www.wixapis.com/payments/v3/transactions \ -H 'Content-Type: application/json; charset=utf-8' \ -H 'Authorization: <AUTH>' \ -d '{ "items":[ { "id":"ItemID", "title":"ItemTitle", "unitPrice":"100", "quantity":1, "category":"DIGITAL" } ], "metadata":{ "metadataKey":"metadataValue" }, "accountId":"6f82b2ce-2a15-4bd7-84b5-392c74b3719c", "amount":"100", "currency":"USD", "externalInvoiceId":"4a3f71e5-9c20-4aca-b994-3b5bbd57a2bd", "externalOrderId":"4a3f71e5-9c20-4aca-b994-3b5bbd57a2bd", "returnUrl":"https://wix.com/3ds", "paymentMethodTypeId": "creditCard", "card":{ "numberToken":"675f55ed-adfe-4411-b4cf-aaa8e614a715", "expiryMonth":12, "expiryYear":2025, "holderName":"PAYMENTS TESTS", "securityCodeToken":"46cc9574-cf5f-4e47-bfc8-f833e1bfddb3" }, "externalBuyerId":"4a3f71e5-9c20-4aca-b994-3b5bbd57a2bd", "billingAddress":{ "address":{ "country":"US", "city":"New York", "postalCode":"10003", "streetAddress":{ "number":"20", "name":"Cooper Square" } }, "contactDetails":{ "firstName":"John", "lastName":"Doe", "phone":"12345675432", "company":"Company wix.com", "email":"john.doe@test.com", "vatId":{ "id":"134424234", "type":"UNSPECIFIED" } } }, "oneTimePayment":{ }, "idempotencyKey":"9d47c0f7-7e89-481a-ad2d-920d97188d71", "externalTransactionId":"d44150d8-1cbe-4ead-9f1d-c9a673698a7f" }'
Response
JSON
{ "transaction": { "id": "43075a59-6a23-4f5f-b4dd-2bb636770458", "currency": "USD", "capturableAmount": "100", "refundableAmount": "0", "externalTransactionId": "d44150d8-1cbe-4ead-9f1d-c9a673698a7f", "providerTransactionId": "pi_1H7db4AaXaGogcA7ZwUvuZ68", "metadata": { "metadataKey": "metadataValue" }, "authorization": { "amount": "100", "status": "SUCCEEDED", "networkReference": { "networkTransactionId": "WvTnyhZlYER07Ate" }, "authCode": "123456" }, "captures": [], "refunds": [], "disputes": [], "voids": [], "accountId": "6f82b2ce-2a15-4bd7-84b5-392c74b3719c", "paymentMethod": { "typeId": "creditCard" } } }
Errors
428Failed Precondition

There is 1 error with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?