Create Payment

Creates a new payment and/or initiates the payment flow.

For credit/debit card payments, or any sync payments, you're expected to execute the authorization.

For bank issued invoice, redirect, or any async payments, you're expected to return the required information to the customer.

The same request, for the same paymentId, can be executed several times, so you must handle it in a way to avoid recreating the payment, but returning the most updated status instead.


Request Body


Name Type Mandatory Description
reference string Yes Merchant's order reference provided by VTEX Checkout.
orderId string Yes Merchant's order identifier provided by VTEX Checkout (also called order group).
shopperInteraction string Yes Indicates which system the buyer interacted with (examples: e-commerce, instore, subscription).
transactionId string Yes VTEX transaction ID related to this payment.
paymentId string Yes VTEX payment ID that can be used as unique identifier.
paymentMethod string Yes The payment method chosen for this payment. It must be one of the available payment methods offered by the provider, which can be obtained from the List Payment Methods endpoint or List Payment Provider Manifest endpoint.
paymentMethodCustomCode string Configurable for Cobranded and Privatelabels payment methods.
verificationOnly boolean Indicates whether this payment is just to validate the buyer's payment method information (for instance, validate the credit card information).
merchantName string Yes VTEX merchant name that will receive the payment.
value decimal Yes Value amount of the payment.
currency string Yes Currency code (ISO 4217 alpha-3).
installments integer Number of installments.
installmentsValue number The value of each installment.
installmentsInterestRate number The interest rate.
deviceFingerprint string Yes A hash that represents the device used to initiate the payment.
ipAddress string The IP Address of the buyer.
card object Card used in the payment. This parameter is required only with card payment methods (credit, debit or co-branded).
holder string Yes Card holder name (this field is null in case the provider uses the Secure Proxy).
number string Yes Card number (this field is null in case the provider uses the Secure Proxy).
csc string Yes Card security code (this field is null in case the provider uses the Secure Proxy).
holderToken string A token representing the card holder (this field is absent in case the provider does not use the Secure Proxy).
bin string First 6 digits of the card number (this field is absent in case the provider does not use the Secure Proxy).
numberToken string A token representing the card security code (this field is absent in case the provider does not use the Secure Proxy).
numberLength number The number of digits in the card's number (this field is absent in case the provider does not use the Secure Proxy).
cscToken string The number of digits in the card's number (this field is absent in case the provider does not use the Secure Proxy).
cscLength number The number of characters in the Card Security Code (this field is absent in case the provider does not use the Secure Proxy).
expiration object Yes An object representing the card's expiration information.
     ↳ month string Yes Card expiration month (2-digits).
     ↳ year string Yes Card expiration year (4-digits).
document string Yes Card holder's document.
miniCart object Yes Object containing information about the shopper's cart and its products.
buyer object Yes Object containing information about the buyer.
     ↳ id string Yes A unique key to this Payment's buyer.
     ↳ firstName string Yes Buyer's first name.
     ↳ lastName string Yes Buyer's last name.
     ↳ document string Yes Buyer's document number.
     ↳ documentType string Yes Buyer's document type.
     ↳ corporateName string Buyer's corporate name. This field is required if isCorporate is true.
     ↳ tradeName string Buyer's trade name. This field is required if isCorporate is true.
     ↳ corporateDocument string Buyer's corporate document number. This field is required if isCorporate is true.
     ↳ isCorporate boolean Yes Indicates whether or not the buyer is corporate. If true, the fields corporateName, tradeName and corporateDocument are required.
     ↳ email string Buyer's email.
     ↳ phone string Yes Buyer's phone number.
     ↳ createdDate string Yes Buyer's create datetime in format "yyyy-MM-ddTHH:mm:ss".
shippingAddress object Yes Object containing information about the shipping address.
     ↳ country string Yes Shipping address: country code (ISO 3166 alpha-3).
     ↳ street string Yes Shipping address: street.
     ↳ number string Yes Shipping address: number.
     ↳ complement string Shipping address: complement.
     ↳ neighborhood string Yes Shipping address: neighborhood.
     ↳ postalCode string Yes Shipping address: postal code.
     ↳ city string Yes Shipping address: city.
     ↳ state string Yes Shipping address: state/province.
billingAddress object Yes Object containing information about the billing address.
     ↳ country string Yes Billing address: country code (ISO 3166 alpha-3).
     ↳ street string Yes Billing address: street.
     ↳ number string Yes Billing address: number.
     ↳ complement string Billing address: complement.
     ↳ neighborhood string Yes Billing address: neighborhood.
     ↳ postalCode string Yes Billing address: postal code.
     ↳ city string Yes Billing address: city.
     ↳ state string Yes Billing address: state/province.
items array Yes A list of the items in the buyer's cart.
     ↳ id string Item identifier.
     ↳ name string Yes Item name.
     ↳ price decimal Yes Item price per unity.
     ↳ quantity number Yes Item quantity.
     ↳ discount number Yes Discount received for the item.
     ↳ deliveryType string Yes Item delivery type selected by the buyer.
     ↳ categoryId string The item category Id.
     ↳ sellerId string In case of a marketplace transaction, this is the Id of the seller for this specific item. Otherwise, this is filled with a "1".
     ↳ taxRate decimal Value of the sum of all Taxes applied to each item. Rates are in percentage, so 5% is represented as 0.05.
     ↳ taxValue decimal Total Tax value of the item (taxRate times value).
shippingValue decimal Total shipping value.
taxValue decimal Total tax value.
recipients array Array containing the information for the recipients of this payment in case the Payment Provider is configured to allow the split of payments.
id string Yes Recipient identifier.
name string Yes Recipient name.
documentType string Yes Recipient document type.
document string Yes Recipient document number.
role string Yes Indicates if the recipient is the seller or the marketplace.
chargeProcessingFee boolean Indicates whether or not this recipient is charged for processing fees.
chargebackLiable boolean Indicates whether or not this recipient is liable to chargebacks.
amount boolean Yes Amount due to this recipient.
merchantSettings array Custom fields (for the given Provider) which the Merchant must fill. Each element of this array is a key-value pair.
name string Yes The custom field name.
value string Yes The custom field value.
url string Yes The order URL from merchant's backoffice.
callbackUrl string Yes The URL you need to call to send the callbacks (notification or retry) of payment status changes
returnUrl string Yes The URL you need to redirect the end user back to merchant's store when using the redirect flow
inboundRequestsUrl string BETA The URL you can use to forward external requests to your payment provider endpoint.
secureProxyUrl string The URL for the Secure Proxy to authorize the Payment (this field is absent in case the provider does not use the Secure Proxy).
sandboxMode boolean Indicates whether or not this request is being sent from a sandbox environment.
totalCartValue decimal Total amount of the shopping cart that this payment is part of. It can be used together with the value to calculate the percentage that this payment represents of the total.

Response body


Name Type Mandatory Description
paymentId string Yes VTEX identifier for this payment. The same sent in the request.
status string Yes The Provider's status for this payment. Must be one of three values: • approveddeniedundefined
authorizationId string Yes Provider's unique identifier for the authorization. Should be sent when the payment is authorized. In other statuses, it should be absent or null.
bankIssueInvoiceId string This field is deprecated, please use paymentUrl instead. The bank invoice URL to be presented to the end user.
paymentUrl string When the payment is via bank invoice, this should be the invoice URL to be presented to the user. If the payment requires the redirection of the user, this should be the URL to redirect the user. If neither is the case, then this should be absent.
paymentAppData object
appName string Yes Indicates the VTEX IO app which will handle the payment flow at Checkout.
payload string Yes The payload that will be sent to your app, like a serialized JSON, for example
identificationNumber string The bank invoice unformatted identification number. Should only be present when the payment is made via bank invoice.
identificationNumberFormatted string The bank invoice formatted identification number that will be presented to the end user.
barCodeImageType string The bank invoice barcode image type. For instance, "i25" for Brazilian Boleto Bancário. Should only be present when the payment is made via bank invoice.
barCodeImageNumber string The bank invoice number to generate a barcode (must follow any regulations/specifications for targeted countries). Should only be present when the payment is made via bank invoice.
tid string Yes Provider's unique identifier for the transaction.
nsu string Yes Provider's unique sequential number for the transaction.
acquirer string Yes Acquirer name (mostly used for card payments).
redirectUrl string This field is deprecated, please use paymentUrl instead. The URL the end user needs to be redirected to (external authentication, 3DS, etc).
code string Yes Provider's operation/error code to be logged.
message string Yes Provider's operation/error message to be logged.
delayToAutoSettle number Yes Total time (in seconds) before we make and automatic call to /settlements no mather if the payment was approved by merchant's antifraud or not. The maximum time allowed to wait for an auto capture is 604800 seconds.
delayToAutoSettleAfterAntifraud number Yes Total time (in seconds) before we make and automatic call to /settlements after merchant's antifraud approval.
delayToCancel number Yes Total time (in seconds) to wait for an authorization and make and automatic call to /cancellations to cancel the payment. The minimum value is 600 (10 minutes).
maxValue number The maximum value for this payment.

Pix response body


Pix Sucess Aprroved request example in the end of the page
Name Type Mandatory Description
paymentId string Yes VTEX identifier for this payment. The same sent in the request.
status string Yes The Provider's status for this payment. Must be one of three values: • approveddeniedundefined
tid string Yes Provider's unique identifier for the transaction.
authorizationId string Yes Provider's unique identifier for the authorization. Should be sent when the payment is authorized. In other statuses, it should be absent or null.
nsu string Yes Provider's unique sequential number for the transaction.
code string Yes Provider's operation/error code to be logged.
paymentAppData object Yes Object containing information about the payment app.
payload string Yes All the information needed to expose the QR Code in the SmartCheckout. Both code and qrCodeBase64Image are mandatory and should always be sent by the provider. Check the serialized JSON String on the request example in the end of the documentation. By default, the QRCode should have five minutes (300 seconds) expiration time. Also, the partner must respect the callback time (20 seconds).
message string Yes Provider's operation/error message to be logged.
delayToAutoSettle number Yes Total time (in seconds) before we make and automatic call to /settlements no mather if the payment was approved by merchant's antifraud or not. The maximum time allowed to wait for an auto capture is 604800 seconds.
delayToAutoSettleAfterAntifraud number Yes Total time (in seconds) before we make and automatic call to /settlements after merchant's antifraud approval.
delayToCancel number Yes Total time (in seconds) to wait for an authorization and make and automatic call to /cancellations to cancel the payment. The minimum value is 600 (10 minutes).

Callbacks


🚧

There are two possible uses for callbacks with the Create Payment endpoint. For integrations that do not use VTEX IO, use the Notification callback. For integrations developed using VTEX IO infrastructure, use the Retry callback.

Notification: If a payment returns with undefined status, you are expected to send us a callback/notification to update it later, sending a POST with an updated version of your response (same structure as above) to the callbackUrl we have provided.

Retry: If a payment returns with undefined status, you are expected to call the retry endpoint provided by the callbackUrl when the processing of the payment is completed, so we make another Create Payment request to update the status with the new value (authorized or denied).

This request should be authenticated using a Key and Token you can generate from your VTEX partner account License Manager. To do so, POST your request passing the X-VTEX-API-AppKey and X-VTEX-API-AppToken headers with your credentials. Note: do not mix up these credentials with the ones we send on behalf of the merchant when sending our requests.


Beta features


You can reach out to our team by openning a ticket to know more about any BETA features.

paymentAppData

As an option to the redirect flow, we're offering a new way to allow payment providers to open a modal at the Checkout page to finish the payment process.

inboundRequestsUrl

Allows to forward external requests back to your payment provider implementation, including the configured credentials (X-VTEX-API-* headers), and settings.

Request examples and their responses

curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "618272",
    "orderId": "1072430428324",
    "shopperInteraction": "ecommerce",
    "transactionId": "2F023FD5A72A49D48A8633252B7CCBD6",
    "paymentId": "01693EB95BE443AC85874E395CD91565",
    "paymentMethod": "Diners",
    "merchantName": "mystore",
    "card": {
        "holder": "John Doe",
        "number": "364901****2661",
        "csc": "***",
        "expiration": {
            "month": "12",
            "year": "2020"
        },
        "document": "39295416023",
        "token": null
    },
    "value": 31.90,
    "currency": "BRL",
    "installments": 1,
    "installmentsInterestRate": 0.00,
    "installmentsValue": 31.90,
    "deviceFingerprint": "75076388",
    "ipAddress": "187.105.111.65",
    "miniCart": {
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "cpf",
            "corporateName": null,
            "tradeName": null,
            "corporateDocument": null,
            "isCorporate": false,
            "email": "[email protected]",
            "phone": "+5521999999999",
            "createdDate": "2020-02-18T18:17:45"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "8",
                "name": "Tenis Preto I",
                "price": 30.9,
                "quantity": 1,
                "discount": 0.0,
                "deliveryType": "Normal",
                "categoryId": "5",
                "sellerId": "1"
            }
        ],
        "shippingValue": 1.0,
        "taxValue": 0.0
    },
    "url": "https://admin.mystore.example.com/orders?q=1072430428324",
    "callbackUrl": "https://api.mystore.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/1072430428324",
    "inboundRequestsUrl": "https://api.mystore.example.com/checkout/order/1072430428324/inbound-request/:action",
    "recipients": [
        {
            "id": "mymarketplace",
            "name": "My Marketplace QA",
            "documentType": "CNPJ",
            "document": "99999999999999",
            "role": "marketplace",
            "chargeProcessingFee": true,
            "chargebackLiable": true,
            "amount": 31.90
        }
    ],
    "merchantSettings": [
        {
            "name": "field1",
            "value": "value1"
        },
        {
            "name": "field2",
            "value": "value2"
        }
    ]
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "Pix",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "BRL",
    "installments": 31,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": null,
        "number": null,
        "csc": null,
        "expiration": {
            "month": null,
            "year": null
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "Visa",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "BRL",
    "installments": 3,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": "John Doe",
        "number": "4682185088924788",
        "csc": "021",
        "expiration": {
            "month": "06",
            "year": "2029"
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "BankInvoice",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "BRL",
    "installments": 1,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": null,
        "number": null,
        "csc": null,
        "expiration": {
            "month": null,
            "year": null
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "FakePay",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "BRL",
    "installments": 1,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": null,
        "number": null,
        "csc": null,
        "expiration": {
            "month": null,
            "year": null
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "Visa",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "BRL",
    "installments": 3,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": "John Doe",
        "number": "4682185088924788",
        "csc": "021",
        "expiration": {
            "month": "06",
            "year": "2029"
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "Visa",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "BRL",
    "installments": 3,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": "John Doe",
        "number": "4682185088924788",
        "csc": "021",
        "expiration": {
            "month": "06",
            "year": "2029"
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "Visa",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "ABC",
    "installments": 3,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": "John Doe",
        "number": "4682185088924788",
        "csc": "021",
        "expiration": {
            "month": "06",
            "year": "2029"
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "32478982",
    "orderId": "v967373115140abc",
    "transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
    "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
    "paymentMethod": "CustomPay",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "value": 4307.23,
    "currency": "BRL",
    "installments": 1,
    "deviceFingerprint": "12ade389087fe",
    "card": {
        "holder": null,
        "number": null,
        "csc": null,
        "expiration": {
            "month": null,
            "year": null
        }
    },
    "miniCart": {
        "shippingValue": 11.44,
        "taxValue": 10.01,
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "CPF",
            "email": "[email protected]",
            "phone": "+5521987654321"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "132981",
                "name": "My First Product",
                "price": 2134.90,
                "quantity": 2,
                "discount": 5.00
            },
            {
                "id": "123242",
                "name": "My Second Product",
                "price": 21.98,
                "quantity": 1,
                "discount": 1.00
            }
        ]
    },
    "url": "https://admin.mystore.example.com/orders/v32478982",
    "callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/v32478982",
    "inboundRequestsUrl": "https://mystore.api.example.com/some-path/inbound-request/:action"
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "618272",
    "orderId": "1072430428324",
    "shopperInteraction": "ecommerce",
    "transactionId": "2F023FD5A72A49D48A8633252B7CCBD6",
    "paymentId": "01693EB95BE443AC85874E395CD91565",
    "paymentMethod": "BankInvoice",
    "merchantName": "mystore",
    "card": {
        "holder": null,
        "number": null,
        "csc": null,
        "expiration": {
            "month": null,
            "year": null
        },
        "document": null,
        "token": null
    },
    "value": 31.90,
    "currency": "BRL",
    "installments": 1,
    "installmentsInterestRate": 0.00,
    "installmentsValue": 31.90,
    "deviceFingerprint": "98073964",
    "ipAddress": "187.105.111.65",
    "miniCart": {
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "cpf",
            "corporateName": null,
            "tradeName": null,
            "corporateDocument": null,
            "isCorporate": false,
            "email": "[email protected]",
            "phone": "+5521999999999",
            "createdDate": "2020-02-18T18:17:45"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "8",
                "name": "Tenis Preto I",
                "price": 30.9,
                "quantity": 1,
                "discount": 0.0,
                "deliveryType": "Normal",
                "categoryId": "5",
                "sellerId": "1"
            }
        ],
        "shippingValue": 1.0,
        "taxValue": 0.0
    },
    "url": "https://admin.mystore.example.com/orders?q=1072430428324",
    "callbackUrl": "https://api.mystore.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/1072430428324",
    "inboundRequestsUrl": "https://api.mystore.example.com/checkout/order/1072430428324/inbound-request/:action",
    "recipients": [
        {
            "id": "mymarketplace",
            "name": "My Marketplace QA",
            "documentType": "CNPJ",
            "document": "99999999999999",
            "role": "marketplace",
            "chargeProcessingFee": true,
            "chargebackLiable": true,
            "amount": 31.90
        }
    ],
    "merchantSettings": [
        {
            "name": "field1",
            "value": "value1"
        },
        {
            "name": "field2",
            "value": "value2"
        }
    ]
}'
curl --location --request POST 'https://{{providerApiEndpoint}}/payments' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "reference": "618272",
    "orderId": "1072430428324",
    "shopperInteraction": "ecommerce",

    "transactionId": "2F023FD5A72A49D48A8633252B7CCBD6",
    "paymentId": "01693EB95BE443AC85874E395CD91565",
    "paymentMethod": "RedirectPay",
    "paymentMethodCustomCode": null,
    "merchantName": "mystore",
    "card": {
        "holder": null,
        "number": null,
        "csc": null,
        "expiration": {
            "month": null,
            "year": null
        },
        "document": null,
        "token": null
    },
    "value": 31.90,
    "currency": "BRL",
    "installments": 1,
    "installmentsInterestRate": 0.00,
    "installmentsValue": 31.90,
    "deviceFingerprint": "75076388",
    "ipAddress": "187.105.111.65",
    "miniCart": {
        "buyer": {
            "id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
            "firstName": "John",
            "lastName": "Doe",
            "document": "01234567890",
            "documentType": "cpf",
            "corporateName": null,
            "tradeName": null,
            "corporateDocument": null,
            "isCorporate": false,
            "email": "[email protected]",
            "phone": "+5521999999999",
            "createdDate": "2020-02-18T18:17:45"
        },
        "shippingAddress": {
            "country": "BRA",
            "street": "Praia de Botafogo St.",
            "number": "300",
            "complement": "3rd Floor",
            "neighborhood": "Botafogo",
            "postalCode": "22250040",
            "city": "Rio de Janeiro",
            "state": "RJ"
        },
        "billingAddress": {
            "country": "BRA",
            "street": "Brigadeiro Faria Lima Avenue",
            "number": "4440",
            "complement": "10th Floor",
            "neighborhood": "Itaim Bibi",
            "postalCode": "04538132",
            "city": "São Paulo",
            "state": "SP"
        },
        "items": [
            {
                "id": "8",
                "name": "Tenis Preto I",
                "price": 30.9,
                "quantity": 1,
                "discount": 0.0,
                "deliveryType": "Normal",
                "categoryId": "5",
                "sellerId": "1"
            }
        ],
        "shippingValue": 1.0,
        "taxValue": 0.0
    },
    "url": "https://admin.mystore.example.com/orders?q=1072430428324",
    "callbackUrl": "https://api.mystore.example.com/some-path/to-notify/status-changes?an=mystore",
    "returnUrl": "https://mystore.example.com/checkout/order/1072430428324",
    "inboundRequestsUrl": "https://api.mystore.example.com/checkout/order/1072430428324/inbound-request/:action",
    "recipients": [
        {
            "id": "mymarketplace",
            "name": "My Marketplace QA",
            "documentType": "CNPJ",
            "document": "99999999999999",
            "role": "marketplace",
            "chargeProcessingFee": true,
            "chargebackLiable": true,
            "amount": 31.90
        }
    ],
    "merchantSettings": [
        {
            "name": "field1",
            "value": "value1"
        },
        {
            "name": "field2",
            "value": "value2"
        }
    ]
}'
{
  "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  "status": "undefined",
  "tid": "TID1578324421",
  "authorizationId": null,
  "nsu": null,
  "code": "APP123",
  "paymentAppData": {
    "appName": "vendor.payment-auth-app",
    "payload": "{\"backendUrl\":\"https://api.example.org/payments/F5C1A4E20D3B4E07B7E871F5B5BC9F91\",\"randomString\":\"78818C2C64264212B8D5771BDC7B1A\",\"randomBool\":false,\"timestamp\":\"2019-10-07 21:30:09Z\"}"
  },
  "message": "The customer needs to finish the payment flow",
  "delayToAutoSettle": 604800,
  "delayToAutoSettleAfterAntifraud": 120,
  "delayToCancel": 604800
}
{
  "paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
  "status": "undefined",
  "tid": "TID1578324421",
  "authorizationId": null,
  "nsu": null,
  "code": "APP123",
  "paymentAppData": {
    "payload": "{\"code\":\"https://bacen.pix/pix/code\",\"qrCodeBase64Image\":\"iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAABQGlDQ1BJQ0MgUHJvZmlsZQAAKJFjYGDiSSwoyGFhYGDIzSspCnJ3UoiIjFJgf8LAxSDMwMkgwiCZmFxc4BgQ4ANUwgCjUcG3awyMIPqyLsgspwWXFu+Xeyundb6w0WL33C5M9SiAKyW1OBlI/wHihOSCohIGBsYYIFu5vKQAxG4AskWKgI4CsqeA2OkQ9goQOwnC3gNWExLkDGRfALIFkjMSU4DsB0C2ThKSeDoSG2ovCLAZGZkbhBNwKKmgJLWiBEQ75xdUFmWmZ5QoOAJDJ1XBMy9ZT0fByMDIgIEBFNYQ1Z9vgMOQUYwDIZapzMBgmQEUfIQQSxNmYNiZzsDAU4UQU5/PwMBrxMBw5GJBYlEi3AGM31iK04yNIGzu7QwMrNP+//8M9Ca7JgPD3+v////e/v//32UMDMy3GBgOfAMA4+RdqZ9YRkcAAABWZVhJZk1NACoAAAAIAAGHaQAEAAAAAQAAABoAAAAAAAOShgAHAAAAEgAAAESgAgAEAAAAAQAAAAKgAwAEAAAAAQAAAAIAAAAAQVNDSUkAAABTY3JlZW5zaG900Fpo3gAAAdJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6ZXhpZj0iaHR0cDovL25zLmFkb2JlLmNvbS9leGlmLzEuMC8iPgogICAgICAgICA8ZXhpZjpQaXhlbFhEaW1lbnNpb24+MjwvZXhpZjpQaXhlbFhEaW1lbnNpb24+CiAgICAgICAgIDxleGlmOlVzZXJDb21tZW50PlNjcmVlbnNob3Q8L2V4aWY6VXNlckNvbW1lbnQ+CiAgICAgICAgIDxleGlmOlBpeGVsWURpbWVuc2lvbj4yPC9leGlmOlBpeGVsWURpbWVuc2lvbj4KICAgICAgPC9yZGY6RGVzY3JpcHRpb24+CiAgIDwvcmRmOlJERj4KPC94OnhtcG1ldGE+Cl89Cn4AAAASSURBVAgdY/wPBAxAwAQiQAAAPfgEAIAu9DkAAAAASUVORK5CYII=\"}"
  },
  "message": "The customer needs to finish the payment flow",
  "delayToAutoSettle": 604800,
  "delayToAutoSettleAfterAntifraud": 120,
  "delayToCancel": 300
}
{
    "paymentId": "01693EB95BE443AC85874E395CD91565",
    "status": "approved",
    "authorizationId": "AUT-09DC5E8F03",
    "nsu": "NSU-107521E866",
    "tid": "TID-7B58BE1A08",
    "acquirer": "TestPay",
    "code": "2000",
    "message": null,
    "delayToAutoSettle": 21600,
    "delayToAutoSettleAfterAntifraud": 1800,
    "delayToCancel": 21600
}
{
    "paymentId": "01693EB95BE443AC85874E395CD91565",
    "status": "undefined",
    "authorizationId": "AUT-2E7CBF7290-ASYNC",
    "paymentUrl": "https://example.org/boleto/gatewayqa/2F023FD5A72A49D48A8633252B7CCBD6/01693EB95BE443AC85874E395CD91565",
    "identificationNumber": "23790504004199031316957008109209378300000019900",
    "identificationNumberFormatted": "23790.50400 41990.313169 57008.109209 3 78300000019900",
    "barCodeImageType": "i25",
    "barCodeImageNumber": "23793783000000199000504041990313165700810920",
    "nsu": "NSU-60F328ACD8-ASYNC",
    "tid": "TID-F3FB9B3FDB-ASYNC",
    "acquirer": "TestPay",
    "code": "2000-ASYNC",
    "message": null,
    "delayToAutoSettle": 21600,
    "delayToAutoSettleAfterAntifraud": 1800,
    "delayToCancel": 21600
}
{
    "paymentId": "01693EB95BE443AC85874E395CD91565",
    "status": "undefined",
    "authorizationId": "AUT-6929AD8429",
    "paymentAppData": {
        "appName": "vtex.payment",
        "payload": "{\"approvePaymentUrl\":\"https://api.mystore.example.com/payments/F5C1A4E20D3B4E07B7E871F5B5BC9F91/callback-trigger/approved?url=https://api.mystore.example.com/transactions/D3AA1FC8372E430E8236649DB5EBD08E/payments/F5C1A4E20D3B4E07B7E871F5B5BC9F91/notification\",\"denyPaymentUrl\":\"https://api.mystore.example.com/payments/F5C1A4E20D3B4E07B7E871F5B5BC9F91/callback-trigger/denied?url=https://api.mystore.example.com/transactions/D3AA1FC8372E430E8236649DB5EBD08E/payments/F5C1A4E20D3B4E07B7E871F5B5BC9F91/notification\",\"orderId\":\"1072650953886\",\"transactionId\":\"D3AA1FC8372E430E8236649DB5EBD08E\",\"paymentId\":\"F5C1A4E20D3B4E07B7E871F5B5BC9F91\",\"timestamp\":\"2020-10-29 17:15:59Z\"}"
    },
    "nsu": "NSU-227AFD0BD2",
    "tid": "TID-DBE4BFFB19",
    "acquirer": "TestPay",
    "code": "2001",
    "message": null,
    "delayToAutoSettle": 21600,
    "delayToAutoSettleAfterAntifraud": 1800,
    "delayToCancel": 21600
}
{
    "paymentId": "7ee64e51-a0d3-4405-874c-d7497ab84572",
    "status": "undefined",
    "tid": "214c699cb408ce6a7110",
    "paymentUrl": "http://php-connector.herokuapp.com/installments.php?paymentId=7ee64e51-a0d3-4405-874c-d7497ab84572"
}
{
    "paymentId": "7ee64e51-a0d3-4405-874c-d7497ab84572",
    "status": "approved",
    "authorizationId": "3baafb4097d6c8ad3883",
    "paymentUrl": null,
    "nsu": "214c699cb408ce6a7110",
    "tid": "214c699cb408ce6a7110",
    "acquirer": null,
    "code": null,
    "message": "Payment with custom installments approved",
    "delayToAutoSettle": 21600,
    "delayToAutoSettleAfterAntifraud": 1800,
    "delayToCancel": 21600
}
Language
Authentication
URL
Click Try It! to start a request and see the response here!