Menu
Guides
API Reference
App Development
Storefront Development
VTEX IO Apps
Troubleshooting
Release Notes
Guides
VTEX Platform Overview
API usage
Getting started
VTEX AI Developer Toolkit
FastStore monorepo
VTEX Business models
Integration Guides
Catalog
Checkout
CMS
Master Data
Payments
Orders
Logistics
B2B
VTEX Sales App
UI Customization
Message Center
Pricing
Promotions
Infrastructure
Search
Recommendations
VTEX Activity Flow
VTEX Ads
VTEX Session
VTEX Shield
Data Protection Plus
VTEX CX Platform (Weni)

Metadata information in payment transactions

Learn how a payment provider stores and retrieves custom metadata in the VTEX payment gateway using the Payment Provider Protocol.

3 min read

Payment providers can use Payment Provider Protocol (PPP) endpoints to record additional information they consider essential for processing a transaction. This information may include data related to orders or other platform modules, payment identifiers generated by the provider, and internal operational logs.

To use this feature, declare the metadata fields in the provider manifest and return their values in the PPP endpoint responses.

Before you begin

Make sure you meet the following requirements:

RequirementDescription
Payment provider integrationYou must have a payment provider implemented in accordance with the Payment Provider Protocol.
Manifest endpointYour provider must expose the List Payment Provider Manifest endpoint, as VTEX reads the metadata field names from it.
Field planningDefine which metadata fields you need in advance, respecting the limits described in Metadata field limits.

Metadata field limits

The following table describes the limits that apply to metadata fields:

ItemLimit
Number of fields declared in metadataFieldsMaximum of 3 strings
Length of each name in metadataFieldsMaximum of 20 characters
Length of connectorMetadata[].nameMaximum of 20 characters
Length of connectorMetadata[].valueMaximum of 200 characters

Validate these limits in your integration before sending the data to VTEX. The PPP schema documents the limits as descriptions, so they aren't enforced by schema validation.

Adding metadata information to your payment transactions

To use metadata in your payment transactions, follow these instructions:

  1. Update the provider manifest to include the metadataFields array, which declares the names of the metadata fields your provider sends to VTEX.


    _10
    ...
    _10
    "metadataFields": [
    _10
    "MetadataName1",
    _10
    "MetadataName2"
    _10
    ]
    _10
    ...

  2. Return the connectorMetadata array in the response body of the endpoints where you want to record metadata:

    Each item of the array must contain the following required fields:

    FieldTypeDescription
    namestringName of the metadata field. It must match one of the names declared in the metadataFields array of the provider manifest. Limited to 20 characters.
    valuestringContent of the metadata to be stored in the payment gateway. Limited to 200 characters.

    See the following example of a connectorMetadata array:


    _12
    ...
    _12
    "connectorMetadata": [
    _12
    {
    _12
    "name": "MetadataName1",
    _12
    "value": "MetadataValue1"
    _12
    },
    _12
    {
    _12
    "name": "MetadataName2",
    _12
    "value": "MetadataValue2"
    _12
    }
    _12
    ]
    _12
    ...

When VTEX receives your response, it stores the metadata in the payment gateway. The following example shows the response body returned by the Refund payment endpoint, including payment and metadata information.


_18
{
_18
"paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
_18
"refundId": "2EA354989E7E4BBC9F9D7B66674C2574",
_18
"value": 57,
_18
"code": null,
_18
"message": "Successfully refunded",
_18
"requestId": "LA4E20D3B4E07B7E871F5B5BC9F91",
_18
"connectorMetadata": [
_18
{
_18
"name": "MetadataName1",
_18
"value": "MetadataValue1"
_18
},
_18
{
_18
"name": "MetadataName2",
_18
"value": "MetadataValue2"
_18
}
_18
]
_18
}

Retrieving stored metadata

The connectorMetadata array is also part of the request schema of the Create payment, Cancel payment, Settle payment, Refund payment, and Inbound request (BETA) endpoints. This means the metadata stored for a payment can be sent back to your provider in the requests VTEX makes for subsequent operations on that payment.

The Payments Gateway API doesn't expose an endpoint for reading connectorMetadata. Metadata is available to your provider through the PPP request and response bodies described in this article.

Next steps