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 | Yes | The interest rate |
installmentsInterestRate |
number | Yes | The interest rate |
deviceFingerprint |
string | Yes | A hash that represents the device used to initiate the payment |
ipAddress |
string | Yes | The IP Address of the buyer |
card |
object | Yes | Object containing the card information |
↳ 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 | Yes | Buyer's corporate name |
↳ tradeName |
string | Yes | Buyer's trade name |
↳ corporateDocument |
string | Yes | Buyer's corporate document number |
↳ isCorporate |
boolean | Yes | Indicates whether or not the buyer is corporate |
↳ email |
string | Yes | 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 | Yes | 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 | Yes | The item category Id |
↳ sellerId |
string | Yes | 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:
• approved
• denied
• undefined |
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:
• approved
• denied
• undefined |
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 thecallbackUrl
we have provided.Retry: If a payment returns with
undefined
status, you are expected to call the retry endpoint provided by thecallbackUrl
when the processing of the payment is completed, so we make another Create Payment request to update the status with the new value (authorized
ordenied
).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 theX-VTEX-API-AppKey
andX-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
}