Referência da API · superfície pública

Integre pagamentos
protegidos em poucas chamadas.

Esta é a superfície pública da API da Vero — a que marketplaces, plataformas e integradores usam. Cobre 20 operações em 3 grupos: a Partner API (chave + escopos), os links e checkout públicos e os webhooks de entrada. Execução financeira de alto risco permanece interna.

Ambientes

Produçãohttps://api.vero.com

Sandboxhttps://sandbox.api.vero.com

Localhttp://localhost:8080

Convenções

Valores monetários são strings decimais ("4199.00") + currency ISO-4217.
Datas em ISO-8601 UTC (2026-05-10T14:21:00Z).
Mutações aceitam Idempotency-Key onde indicado.
Todo erro traz um code estável — ramifique por ele.

Para agentes de IA · MCP

A especificação completa é legível por máquina — pronta para Swagger UI, Redoc ou para expor via MCP a agentes de integração.

openapi.json llms.txt

Partner API · 14

Partner API

A superfície versionada para terceiros e agentes/MCP. Autentica com uma chave de API (Authorization: Bearer vero_...) e um escopo por endpoint. É por aqui que marketplaces e plataformas integram.

GET/api/v1/merchants

List my sub-merchants

Partner APIescopo: merchants:read

All sellers the calling platform owns, newest first. Requires the merchants:read scope.

Respostas

200The platform's sellers.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

curl -X GET "https://api.vero.com/api/v1/merchants" \
  -H "Authorization: Bearer vero_sk_live_xxx"

[
  {
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "displayName": "Loja do João",
    "legalName": "João da Silva ME",
    "status": "ACTIVE",
    "blocked": false,
    "externalReference": "seller-1042",
    "createdAt": "2026-05-10T14:21:00Z"
  }
]

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/api/v1/merchants

Register a sub-merchant (seller)

Partner APIescopo: merchants:write

Register a seller account owned by the calling platform (e.g. a marketplace onboarding its sellers one by one). The account is created ACTIVE and platform-managed — no dashboard user is provisioned. Verification and activation still happen through onboarding before the seller can take payments. Requires the merchants:write scope.

Corpo da requisição

typeenum (INDIVIDUAL | BUSINESS)obrigatório

INDIVIDUAL follows KYC; BUSINESS follows KYB.

displayNamestringobrigatório

legalNamestring

externalReferencestring

The platform's own id for this seller; makes registration idempotent (a repeat is rejected 409).

Respostas

201The registered seller.

400Request body/params failed validation.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

409A seller is already registered for this externalReference.

curl -X POST "https://api.vero.com/api/v1/merchants" \
  -H "Authorization: Bearer vero_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "INDIVIDUAL",
  "displayName": "Loja do João",
  "legalName": "João da Silva ME",
  "externalReference": "seller-1042"
}'

{
  "type": "INDIVIDUAL",
  "displayName": "Loja do João",
  "legalName": "João da Silva ME",
  "externalReference": "seller-1042"
}

{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "displayName": "Loja do João",
  "legalName": "João da Silva ME",
  "status": "ACTIVE",
  "blocked": false,
  "externalReference": "seller-1042",
  "createdAt": "2026-05-10T14:21:00Z"
}

{
  "code": "VALIDATION_FAILED",
  "message": "O corpo ou os parâmetros da requisição falharam na validação.",
  "status": 400,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": [
    {
      "path": "destination",
      "message": "must not be blank"
    }
  ]
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "INVALID_STATE_TRANSITION",
  "message": "Conflito de estado, versão ou idempotência.",
  "status": 409,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

GET/api/v1/merchants/{merchantId}

Get a sub-merchant

Partner APIescopo: merchants:read

Fetch one seller the platform owns. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the merchants:read scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

Respostas

200The seller.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

curl -X GET "https://api.vero.com/api/v1/merchants/{merchantId}" \
  -H "Authorization: Bearer vero_sk_live_xxx"

{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "displayName": "Loja do João",
  "legalName": "João da Silva ME",
  "status": "ACTIVE",
  "blocked": false,
  "externalReference": "seller-1042",
  "createdAt": "2026-05-10T14:21:00Z"
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

PATCH/api/v1/merchants/{merchantId}

Update a sub-merchant

Partner APIescopo: merchants:write

Update a seller's display/legal name. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the merchants:write scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

Corpo da requisição

displayNamestring

legalNamestring

Respostas

200The updated seller.

400Request body/params failed validation.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

curl -X PATCH "https://api.vero.com/api/v1/merchants/{merchantId}" \
  -H "Authorization: Bearer vero_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Loja do João — Oficial",
  "legalName": "João da Silva ME"
}'

{
  "displayName": "Loja do João — Oficial",
  "legalName": "João da Silva ME"
}

{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "displayName": "Loja do João",
  "legalName": "João da Silva ME",
  "status": "ACTIVE",
  "blocked": false,
  "externalReference": "seller-1042",
  "createdAt": "2026-05-10T14:21:00Z"
}

{
  "code": "VALIDATION_FAILED",
  "message": "O corpo ou os parâmetros da requisição falharam na validação.",
  "status": 400,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": [
    {
      "path": "destination",
      "message": "must not be blank"
    }
  ]
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/api/v1/merchants/{merchantId}/block

Block a sub-merchant

Partner APIescopo: merchants:write

Block a seller (reversible). The account moves to SUSPENDED and the authorization layer refuses every money-moving and management action for it until unblock. Idempotent. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the merchants:write scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

Respostas

200The blocked seller.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

curl -X POST "https://api.vero.com/api/v1/merchants/{merchantId}/block" \
  -H "Authorization: Bearer vero_sk_live_xxx"

{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "displayName": "Loja do João",
  "legalName": "João da Silva ME",
  "status": "ACTIVE",
  "blocked": false,
  "externalReference": "seller-1042",
  "createdAt": "2026-05-10T14:21:00Z"
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

GET/api/v1/merchants/{merchantId}/payment-links

List a seller's payment links

Partner APIescopo: payment_links:read

List the seller's payment links. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the payment_links:read scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

Respostas

200The seller's links.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

curl -X GET "https://api.vero.com/api/v1/merchants/{merchantId}/payment-links" \
  -H "Authorization: Bearer vero_sk_live_xxx"

[
  {
    "linkId": "string",
    "status": "DRAFT",
    "transactionType": "GOODS",
    "amount": "string",
    "currency": "string",
    "expiresAt": "2026-05-10T14:21:00Z",
    "title": "string"
  }
]

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/api/v1/merchants/{merchantId}/payment-links

Create a payment link for a seller

Partner APIescopo: payment_links:write

Create a DRAFT payment link on behalf of a seller. The seller must be active (not blocked) and activated (holds the create-payment-link capability). The seller must be one the calling platform owns; another platform's seller returns 404. Requires the payment_links:write scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

Corpo da requisição

transactionTypeenum (GOODS | SERVICE)obrigatório

amountstringobrigatório

Decimal item amount.

currencystringobrigatório

ISO-4217.

feePayerenum (BUYER | MERCHANT | SPLIT)obrigatório

methodsarray · enum (PIX | CARD | BOLETO)obrigatório

expiresAtstring · date-timeobrigatório

buyerRequirementsarray · string

goodsobject

Required when transactionType is GOODS.

titlestring

descriptionstring

quantityinteger

conditionstring

deliveryModestring

shippingAddressRequiredboolean

shippingTermsstring

serviceobject

Required when transactionType is SERVICE.

titlestring

descriptionstring

startConditionsstring

estimatedDurationDaysinteger

maximumDurationDaysinteger

deliverablesarray · string

completionCriteriastring

Respostas

201Created draft link.

400Request body/params failed validation.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

409The seller cannot create links yet (not activated).

curl -X POST "https://api.vero.com/api/v1/merchants/{merchantId}/payment-links" \
  -H "Authorization: Bearer vero_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionType": "GOODS",
  "amount": "string",
  "currency": "string",
  "feePayer": "BUYER",
  "methods": [
    "PIX"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "buyerRequirements": [
    "string"
  ],
  "goods": {
    "title": "string",
    "description": "string",
    "quantity": 0,
    "condition": "string",
    "deliveryMode": "string",
    "shippingAddressRequired": true,
    "shippingTerms": "string"
  },
  "service": {
    "title": "string",
    "description": "string",
    "startConditions": "string",
    "estimatedDurationDays": 0,
    "maximumDurationDays": 0,
    "deliverables": [
      "string"
    ],
    "completionCriteria": "string"
  }
}'

{
  "transactionType": "GOODS",
  "amount": "string",
  "currency": "string",
  "feePayer": "BUYER",
  "methods": [
    "PIX"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "buyerRequirements": [
    "string"
  ],
  "goods": {
    "title": "string",
    "description": "string",
    "quantity": 0,
    "condition": "string",
    "deliveryMode": "string",
    "shippingAddressRequired": true,
    "shippingTerms": "string"
  },
  "service": {
    "title": "string",
    "description": "string",
    "startConditions": "string",
    "estimatedDurationDays": 0,
    "maximumDurationDays": 0,
    "deliverables": [
      "string"
    ],
    "completionCriteria": "string"
  }
}

{
  "linkId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "publicToken": "plink_9aZ",
  "status": "DRAFT"
}

{
  "code": "VALIDATION_FAILED",
  "message": "O corpo ou os parâmetros da requisição falharam na validação.",
  "status": 400,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": [
    {
      "path": "destination",
      "message": "must not be blank"
    }
  ]
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "INVALID_STATE_TRANSITION",
  "message": "Conflito de estado, versão ou idempotência.",
  "status": 409,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

GET/api/v1/merchants/{merchantId}/payment-links/{linkId}

Get a payment link

Partner APIescopo: payment_links:read

Fetch one of the seller's payment links. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the payment_links:read scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

linkIdstring obrigatório

The payment link id.

Respostas

200The link.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

curl -X GET "https://api.vero.com/api/v1/merchants/{merchantId}/payment-links/{linkId}" \
  -H "Authorization: Bearer vero_sk_live_xxx"

{
  "linkId": "string",
  "status": "DRAFT",
  "transactionType": "GOODS",
  "amount": "string",
  "currency": "string",
  "feePayer": "BUYER",
  "methods": [
    "string"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "title": "string",
  "buyerRequirements": [
    "string"
  ],
  "pricing": {
    "itemAmount": "string",
    "feeAmount": "string",
    "buyerTotal": "string",
    "merchantExpectedNet": "string",
    "currency": "string",
    "feePayer": "string"
  }
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

PATCH/api/v1/merchants/{merchantId}/payment-links/{linkId}

Update a payment link

Partner APIescopo: payment_links:write

Replace a DRAFT link's definition. Only a DRAFT link can be updated. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the payment_links:write scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

linkIdstring obrigatório

The payment link id.

Corpo da requisição

transactionTypeenum (GOODS | SERVICE)obrigatório

amountstringobrigatório

Decimal item amount.

currencystringobrigatório

ISO-4217.

feePayerenum (BUYER | MERCHANT | SPLIT)obrigatório

methodsarray · enum (PIX | CARD | BOLETO)obrigatório

expiresAtstring · date-timeobrigatório

buyerRequirementsarray · string

goodsobject

Required when transactionType is GOODS.

titlestring

descriptionstring

quantityinteger

conditionstring

deliveryModestring

shippingAddressRequiredboolean

shippingTermsstring

serviceobject

Required when transactionType is SERVICE.

titlestring

descriptionstring

startConditionsstring

estimatedDurationDaysinteger

maximumDurationDaysinteger

deliverablesarray · string

completionCriteriastring

Respostas

200The updated link.

400Request body/params failed validation.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

409The link is not editable in its current state.

curl -X PATCH "https://api.vero.com/api/v1/merchants/{merchantId}/payment-links/{linkId}" \
  -H "Authorization: Bearer vero_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionType": "GOODS",
  "amount": "string",
  "currency": "string",
  "feePayer": "BUYER",
  "methods": [
    "PIX"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "buyerRequirements": [
    "string"
  ],
  "goods": {
    "title": "string",
    "description": "string",
    "quantity": 0,
    "condition": "string",
    "deliveryMode": "string",
    "shippingAddressRequired": true,
    "shippingTerms": "string"
  },
  "service": {
    "title": "string",
    "description": "string",
    "startConditions": "string",
    "estimatedDurationDays": 0,
    "maximumDurationDays": 0,
    "deliverables": [
      "string"
    ],
    "completionCriteria": "string"
  }
}'

{
  "transactionType": "GOODS",
  "amount": "string",
  "currency": "string",
  "feePayer": "BUYER",
  "methods": [
    "PIX"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "buyerRequirements": [
    "string"
  ],
  "goods": {
    "title": "string",
    "description": "string",
    "quantity": 0,
    "condition": "string",
    "deliveryMode": "string",
    "shippingAddressRequired": true,
    "shippingTerms": "string"
  },
  "service": {
    "title": "string",
    "description": "string",
    "startConditions": "string",
    "estimatedDurationDays": 0,
    "maximumDurationDays": 0,
    "deliverables": [
      "string"
    ],
    "completionCriteria": "string"
  }
}

{
  "linkId": "string",
  "status": "DRAFT",
  "transactionType": "GOODS",
  "amount": "string",
  "currency": "string",
  "feePayer": "BUYER",
  "methods": [
    "string"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "title": "string",
  "buyerRequirements": [
    "string"
  ],
  "pricing": {
    "itemAmount": "string",
    "feeAmount": "string",
    "buyerTotal": "string",
    "merchantExpectedNet": "string",
    "currency": "string",
    "feePayer": "string"
  }
}

{
  "code": "VALIDATION_FAILED",
  "message": "O corpo ou os parâmetros da requisição falharam na validação.",
  "status": 400,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": [
    {
      "path": "destination",
      "message": "must not be blank"
    }
  ]
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "INVALID_STATE_TRANSITION",
  "message": "Conflito de estado, versão ou idempotência.",
  "status": 409,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/api/v1/merchants/{merchantId}/payment-links/{linkId}/activate

Activate a payment link

Partner APIescopo: payment_links:write

Activate a DRAFT link so it can be funded. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the payment_links:write scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

linkIdstring obrigatório

The payment link id.

Respostas

200The activated link.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

409The link cannot be activated in its current state.

curl -X POST "https://api.vero.com/api/v1/merchants/{merchantId}/payment-links/{linkId}/activate" \
  -H "Authorization: Bearer vero_sk_live_xxx"

{
  "linkId": "string",
  "status": "DRAFT",
  "transactionType": "GOODS",
  "amount": "string",
  "currency": "string",
  "feePayer": "BUYER",
  "methods": [
    "string"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "title": "string",
  "buyerRequirements": [
    "string"
  ],
  "pricing": {
    "itemAmount": "string",
    "feeAmount": "string",
    "buyerTotal": "string",
    "merchantExpectedNet": "string",
    "currency": "string",
    "feePayer": "string"
  }
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "INVALID_STATE_TRANSITION",
  "message": "Conflito de estado, versão ou idempotência.",
  "status": 409,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/api/v1/merchants/{merchantId}/payment-links/{linkId}/cancel

Cancel (deactivate) a payment link

Partner APIescopo: payment_links:write

Cancel a draft or active link. This is a soft deactivation — the link moves to CANCELLED and can no longer be funded. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the payment_links:write scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

linkIdstring obrigatório

The payment link id.

Respostas

204Cancelled.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

curl -X POST "https://api.vero.com/api/v1/merchants/{merchantId}/payment-links/{linkId}/cancel" \
  -H "Authorization: Bearer vero_sk_live_xxx"

// 204 · sem conteúdo

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/api/v1/merchants/{merchantId}/unblock

Unblock a sub-merchant

Partner APIescopo: merchants:write

Restore a blocked seller to ACTIVE. Idempotent. The seller must be one the calling platform owns; another platform's seller returns 404. Requires the merchants:write scope.

Parâmetros de caminho

merchantIdstring obrigatório

The sub-merchant (seller) id.

Respostas

200The reinstated seller.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

404Resource not found (or hidden cross-tenant).

curl -X POST "https://api.vero.com/api/v1/merchants/{merchantId}/unblock" \
  -H "Authorization: Bearer vero_sk_live_xxx"

{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "displayName": "Loja do João",
  "legalName": "João da Silva ME",
  "status": "ACTIVE",
  "blocked": false,
  "externalReference": "seller-1042",
  "createdAt": "2026-05-10T14:21:00Z"
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

GET/api/v1/transactions

List transactions (demonstration surface)

Partner APIescopo: transactions:read

Lists transactions for the calling key's merchant. Surface: Partner API. Requires the
transactions:read scope. In this version the data array is a documented placeholder (empty).

Cabeçalhos

X-Request-Idstring

Respostas

200Transaction list envelope.

401Authentication missing or invalid.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

curl -X GET "https://api.vero.com/api/v1/transactions" \
  -H "Authorization: Bearer vero_sk_live_xxx"

{
  "requestId": "7f3c2b10-...",
  "merchantId": "3a2b...",
  "data": []
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

GET/api/v1/whoami

Identity of the calling API key

Partner API

Returns the merchant, environment and granted scopes for the presented API key.
Surface: Partner API. Any valid key; no specific scope required.
Send X-Request-Id to have it echoed back (else one is generated).

Cabeçalhos

X-Request-Idstring

Respostas

200The calling key's identity.

401Authentication missing or invalid.

curl -X GET "https://api.vero.com/api/v1/whoami" \
  -H "Authorization: Bearer vero_sk_live_xxx"

{
  "requestId": "7f3c2b10-...",
  "merchantId": "3a2b...",
  "environment": "SANDBOX",
  "scopes": [
    "transactions:read"
  ]
}

{
  "code": "AUTHENTICATION_FAILED",
  "message": "Credenciais ausentes ou inválidas (chave, token ou assinatura).",
  "status": 401,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

Links & checkout público · 3

Links & checkout público

Páginas e ações voltadas ao comprador, abertas com um token opaco no caminho — sem credencial de conta. Retornam apenas campos seguros para o comprador.

GET/v1/payment-links/{token}

Resolve a public link (buyer-safe)

Público

Resolves a public link token to the buyer-safe offer. Surface: Public — the link token is the only credential. No ids, fee split or merchant net.

Parâmetros de caminho

tokenstring obrigatório

Respostas

200Buyer-safe offer.

404Resource not found (or hidden cross-tenant).

curl -X GET "https://api.vero.com/v1/payment-links/{token}"

{
  "merchantDisplayName": "string",
  "transactionType": "GOODS",
  "title": "string",
  "description": "string",
  "buyerTotal": "string",
  "currency": "string",
  "methods": [
    "string"
  ],
  "buyerRequirements": [
    "string"
  ],
  "expiresAt": "2026-05-10T14:21:00Z",
  "status": "AVAILABLE"
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/v1/payment-links/{token}/fund

Fund a link (create the escrow agreement)

Público

Records the durable escrow agreement (creates a Transaction) and consumes the single-use link. Surface: Public — no session; a fresh anonymous buyer id is minted. Distinct from /v1/public/payment-links/{token} (checkout).

Parâmetros de caminho

tokenstring obrigatório

Corpo da requisição

buyerNamestring

contactReferencesarray · string

shippingRecipientstring

shippingAddressstring

maskedDocumentReferencestring

descriptionstring

sellerReferencestring

Respostas

201Transaction created.

404Resource not found (or hidden cross-tenant).

409State / version / idempotency conflict.

curl -X POST "https://api.vero.com/v1/payment-links/{token}/fund" \
  -H "Content-Type: application/json" \
  -d '{
  "buyerName": "string",
  "contactReferences": [
    "string"
  ],
  "shippingRecipient": "string",
  "shippingAddress": "string",
  "maskedDocumentReference": "string",
  "description": "string",
  "sellerReference": "string"
}'

{
  "buyerName": "string",
  "contactReferences": [
    "string"
  ],
  "shippingRecipient": "string",
  "shippingAddress": "string",
  "maskedDocumentReference": "string",
  "description": "string",
  "sellerReference": "string"
}

{
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

{
  "code": "INVALID_STATE_TRANSITION",
  "message": "Conflito de estado, versão ou idempotência.",
  "status": 409,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

GET/v1/status/{accessToken}

Public transaction status

Público

Buyer-safe public status view for a transaction identified solely by its status access token. Surface: Public token. Read-only; buyer-safe fields only.

Parâmetros de caminho

accessTokenstring obrigatório

Respostas

200Public status view.

404Resource not found (or hidden cross-tenant).

curl -X GET "https://api.vero.com/v1/status/{accessToken}"

{
  "merchantDisplayName": "string",
  "title": "string",
  "buyerTotal": "string",
  "currency": "string",
  "outcomeState": "PENDING",
  "financialState": "string",
  "protectedAmount": "string",
  "messageCode": "string",
  "nextAction": "AWAIT_FULFILLMENT",
  "escrowStages": [
    {
      "key": "PAYMENT",
      "status": "DONE"
    }
  ]
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado (ou oculto entre tenants).",
  "status": 404,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

Webhooks de entrada · 3

Webhooks de entrada

Callbacks que a Vero recebe de provedores de pagamento e transportadoras. Autenticados por segredo compartilhado ou assinatura, idempotentes e seguros contra enumeração.

POST/v1/integrations/payments/{provider}/webhook

Inbound payment provider webhook

Webhook

Receives a normalized provider payment event, dedups it, drives the attempt through the state
machine and protects funds if confirmed. Surface: Webhook — authenticated by a static
X-Webhook-Secret (constant-time compare, not an HMAC of the body).

Parâmetros de caminho

providerstring obrigatório

Corpo da requisição

providerReferencestringobrigatório

eventIdstringobrigatório

Used for dedup.

amountMinorinteger

currencystring

Respostas

200Processing result.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

curl -X POST "https://api.vero.com/v1/integrations/payments/{provider}/webhook" \
  -H "X-Webhook-Secret: $WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "providerReference": "string",
  "eventId": "string",
  "status": "INITIATED",
  "amountMinor": 0,
  "currency": "string"
}'

{
  "providerReference": "string",
  "eventId": "string",
  "status": "INITIATED",
  "amountMinor": 0,
  "currency": "string"
}

{
  "callbackOutcome": "PROCESSED",
  "protectionOutcome": "PROTECTED",
  "attemptStatus": "string"
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/v1/integrations/tracking/{provider}/webhook

Inbound tracking webhook (normalized)

Webhook

Applies a normalized canonical state to a shipment. Surface: Webhook — X-Webhook-Secret constant-time compare. Unknown tracking code is an enumeration-safe no-op (still 200).

Parâmetros de caminho

providerstring obrigatório

Corpo da requisição

trackingCodestring

canonicalStatestring

A GoodsFulfillmentState name.

sourceReferencestring

occurredAtstring · date-time

Respostas

200Result.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

curl -X POST "https://api.vero.com/v1/integrations/tracking/{provider}/webhook" \
  -H "X-Webhook-Secret: $WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "trackingCode": "string",
  "canonicalState": "string",
  "sourceReference": "string",
  "occurredAt": "2026-05-10T14:21:00Z"
}'

{
  "trackingCode": "string",
  "canonicalState": "string",
  "sourceReference": "string",
  "occurredAt": "2026-05-10T14:21:00Z"
}

{
  "outcome": "APPLIED"
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

POST/v1/logistics/carriers/{carrierId}/webhook

Inbound carrier webhook (signed)

Webhook · transportadora

Signature-validated carrier webhook, normalized and deduped into tracking ingestion. Surface: Webhook — X-Carrier-Signature validated over trackingNumber|rawStatus|carrierEventId before the body is trusted. Never releases escrow or mutates the ledger.

Parâmetros de caminho

carrierIdstring obrigatório

Corpo da requisição

trackingNumberstring

rawStatusstring

carrierEventIdstring

Used for dedup.

occurredAtstring · date-time

rawPayloadRefstring

Respostas

200Result.

403Authenticated but not allowed (missing scope/permission, step-up required, or tenant mismatch).

curl -X POST "https://api.vero.com/v1/logistics/carriers/{carrierId}/webhook" \
  -H "X-Carrier-Signature: $CARRIER_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
  "trackingNumber": "string",
  "rawStatus": "string",
  "carrierEventId": "string",
  "occurredAt": "2026-05-10T14:21:00Z",
  "rawPayloadRef": "string"
}'

{
  "trackingNumber": "string",
  "rawStatus": "string",
  "carrierEventId": "string",
  "occurredAt": "2026-05-10T14:21:00Z",
  "rawPayloadRef": "string"
}

{
  "outcome": "IGNORED_UNKNOWN_TRACKING"
}

{
  "code": "AUTHORIZATION_FAILED",
  "message": "Autenticado, mas sem permissão (escopo ou escopo insuficiente).",
  "status": 403,
  "correlationId": "6b1d2c7e-9a1f-4a1e-9b2c-2f0b7d3a9e11",
  "timestamp": "2026-05-10T14:21:00Z",
  "details": []
}

Integre pagamentosprotegidos em poucas chamadas.

Partner API

List my sub-merchants

Register a sub-merchant (seller)

Get a sub-merchant

Update a sub-merchant

Block a sub-merchant

List a seller's payment links

Create a payment link for a seller

Get a payment link

Update a payment link

Activate a payment link

Cancel (deactivate) a payment link

Unblock a sub-merchant

List transactions (demonstration surface)

Identity of the calling API key

Links & checkout público

Resolve a public link (buyer-safe)

Fund a link (create the escrow agreement)

Public transaction status

Webhooks de entrada

Inbound payment provider webhook

Inbound tracking webhook (normalized)

Inbound carrier webhook (signed)

Integre pagamentos
protegidos em poucas chamadas.