{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "PayZu API Cartão de Crédito", "description": "API de cobranças com cartão de crédito da PayZu: autorização, 3DS, antifraude, recorrência, estornos e chargebacks.\n\nAutenticação: mTLS + Bearer token, descrita em [Autenticação](https://docs.payzu.com.br/docs/cartao/authentication).\n\nGuias e referência completa em [docs.payzu.com.br/docs/cartao](https://docs.payzu.com.br/docs/cartao)." }, "servers": [ { "url": "https://api.payzu.io/v1", "description": "Production" }, { "url": "https://api.sandbox.payzu.io/v1", "description": "Sandbox" } ], "tags": [ { "name": "Token", "description": "Autenticação e emissão de token de acesso" }, { "name": "Charges", "description": "Criação, consulta e estorno de cobranças com cartão" }, { "name": "Recurrences", "description": "Consulta e gestão de pagamentos recorrentes" }, { "name": "Currencies", "description": "Cotações de câmbio de referência e conversão para cobrança internacional" } ], "paths": { "/token": { "post": { "summary": "Obter token de API", "description": "Retorna um token JWT para autenticação das rotas. O `client_id` e o `client_secret` da conta são enviados via Basic Auth, sobre a conexão mTLS.\n\nPasso a passo em [Autenticação](https://docs.payzu.com.br/docs/cartao/authentication).", "operationId": "post_token", "tags": [ "Token" ], "security": [ { "BasicAuth": [], "MutualTLS": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Tipo de concessão OAuth", "enum": [ "client_credentials" ], "default": "client_credentials" } } } } } }, "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Token JWT a enviar no header Authorization: Bearer" }, "token_type": { "type": "string", "description": "Tipo do token" }, "expires_in": { "type": "number", "description": "Tempo de vida do token, em segundos" } } }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600 } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.io/v1/token' \\\n --user \"$PAYZU_CLIENT_ID:$PAYZU_CLIENT_SECRET\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"grant_type\": \"client_credentials\"\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/token';\n\nconst response = await fetch(url, {\n method: 'POST',\n dispatcher: agent,\n headers: {\n Authorization: `Basic ${Buffer.from(`${process.env.PAYZU_CLIENT_ID}:${process.env.PAYZU_CLIENT_SECRET}`).toString('base64')}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n grant_type: 'client_credentials'\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.io/v1/token',\n auth=(os.environ['PAYZU_CLIENT_ID'], os.environ['PAYZU_CLIENT_SECRET']),\n headers={\n 'Content-Type': 'application/json',\n },\n json={\n 'grant_type': 'client_credentials'\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/charges": { "post": { "summary": "Criar cobrança", "description": "Cria uma nova cobrança com cartão de crédito.\n\n- Autenticação 3DS: [3-D Secure](https://docs.payzu.com.br/docs/cartao/three-d-secure). Exige `authenticate` igual a `true` junto de `externalAuthentication`.\n- Motor antifraude: [Antifraude](https://docs.payzu.com.br/docs/cartao/antifraud).\n- Moeda estrangeira: [Cobrança internacional](https://docs.payzu.com.br/docs/cartao/international).\n- Pagamento recorrente: envie o nó `recurrence`, descrito em [Pagamentos recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence).", "operationId": "post_charges", "tags": [ "Charges" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeRequest" }, "examples": { "Cobrança simples": { "summary": "Cobrança simples", "value": { "amount": 10000, "paymentType": "creditcard", "externalId": "pedido-1234", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "phone": "11999998888" }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } } } }, "Cobrança recorrente": { "summary": "Cobrança recorrente (assinatura)", "value": { "amount": 10000, "paymentType": "creditcard", "externalId": "assinatura-123", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "customer": { "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "phone": "11999998888" }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "card": { "number": "4111111111111111", "holder": "MARIA SOUZA", "expiration": "12/2030", "cvv": "123" } }, "recurrence": { "interval": "Monthly", "endDate": "2027-06-12" } } } } } } }, "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "externalId": "pedido-1234", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "amount": 10000, "paymentType": "creditcard", "createdAt": "2026-06-12T14:35:22.000Z", "updatedAt": "2026-06-12T14:35:24.000Z", "customer": { "id": 501, "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "birthdate": "1990-04-15", "phone": "11999998888", "address": { "street": "Avenida Paulista", "number": "1000", "zipCode": "01310100", "city": "São Paulo", "state": "SP", "country": "BR", "district": "Bela Vista", "complement": "Conjunto 101" } }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "currency": "BRL", "acquirerTransactionId": "1049329871283a5d2b8e", "authorizationCode": "128734", "reasonCode": 0, "reasonMessage": "Successful", "status": 2, "returnCode": "6", "returnMessage": "Operação realizada com sucesso", "externalAuthentication": {}, "reversedAmount": null, "reversedDate": null, "chargeId": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "card": { "id": 42, "number": "411111******1111", "holder": "MARIA SOUZA", "expiration": "12/2030", "brand": "Visa" }, "chargebacks": [] } } }, "Recorrência criada": { "summary": "Recorrência criada", "value": { "id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "externalId": "assinatura-123", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "amount": 10000, "paymentType": "creditcard", "createdAt": "2026-06-12T14:35:22.000Z", "updatedAt": "2026-06-12T14:35:24.000Z", "customer": { "id": 501, "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "birthdate": "1990-04-15", "phone": "11999998888", "address": { "street": "Avenida Paulista", "number": "1000", "zipCode": "01310100", "city": "São Paulo", "state": "SP", "country": "BR", "district": "Bela Vista", "complement": "Conjunto 101" } }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "currency": "BRL", "acquirerTransactionId": "1049329871283a5d2b8e", "authorizationCode": "128734", "reasonCode": 0, "reasonMessage": "Successful", "status": 2, "returnCode": "6", "returnMessage": "Operação realizada com sucesso", "externalAuthentication": {}, "reversedAmount": null, "reversedDate": null, "chargeId": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "card": { "id": 42, "number": "411111******1111", "holder": "MARIA SOUZA", "expiration": "12/2030", "brand": "Visa" }, "chargebacks": [] }, "recurrence": { "recurrentPaymentId": "5f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" }, "recurrenceCycle": 0 } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request POST \\\n --url 'https://api.payzu.io/v1/charges' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 10000,\n \"paymentType\": \"creditcard\",\n \"externalId\": \"pedido-1234\",\n \"postbackUrl\": \"https://seusite.com.br/webhooks/payzu\",\n \"customer\": {\n \"name\": \"Maria Souza\",\n \"identity\": \"11144477735\",\n \"identityType\": \"CPF\",\n \"email\": \"maria.souza@example.com\",\n \"phone\": \"11999998888\"\n },\n \"cart\": [\n {\n \"name\": \"Plano Pro\",\n \"quantity\": 1,\n \"sku\": \"PRO\",\n \"unitPrice\": 10000\n }\n ],\n \"creditCardPayment\": {\n \"installments\": 1,\n \"authenticate\": false,\n \"card\": {\n \"number\": \"4111111111111111\",\n \"holder\": \"MARIA SOUZA\",\n \"expiration\": \"12/2030\",\n \"cvv\": \"123\"\n }\n }\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges';\n\nconst response = await fetch(url, {\n method: 'POST',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n amount: 10000,\n paymentType: 'creditcard',\n externalId: 'pedido-1234',\n postbackUrl: 'https://seusite.com.br/webhooks/payzu',\n customer: {\n name: 'Maria Souza',\n identity: '11144477735',\n identityType: 'CPF',\n email: 'maria.souza@example.com',\n phone: '11999998888'\n },\n cart: [\n {\n name: 'Plano Pro',\n quantity: 1,\n sku: 'PRO',\n unitPrice: 10000\n }\n ],\n creditCardPayment: {\n installments: 1,\n authenticate: false,\n card: {\n number: '4111111111111111',\n holder: 'MARIA SOUZA',\n expiration: '12/2030',\n cvv: '123'\n }\n }\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n 'https://api.payzu.io/v1/charges',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 10000,\n 'paymentType': 'creditcard',\n 'externalId': 'pedido-1234',\n 'postbackUrl': 'https://seusite.com.br/webhooks/payzu',\n 'customer': {\n 'name': 'Maria Souza',\n 'identity': '11144477735',\n 'identityType': 'CPF',\n 'email': 'maria.souza@example.com',\n 'phone': '11999998888'\n },\n 'cart': [\n {\n 'name': 'Plano Pro',\n 'quantity': 1,\n 'sku': 'PRO',\n 'unitPrice': 10000\n }\n ],\n 'creditCardPayment': {\n 'installments': 1,\n 'authenticate': False,\n 'card': {\n 'number': '4111111111111111',\n 'holder': 'MARIA SOUZA',\n 'expiration': '12/2030',\n 'cvv': '123'\n }\n }\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] }, "get": { "summary": "Listar cobranças", "description": "Retorna uma lista com as cobranças", "operationId": "get_charges", "tags": [ "Charges" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "query", "name": "startDate", "required": false, "description": "Data inicial para filtrar os resultados", "schema": { "type": "string" } }, { "in": "query", "name": "endDate", "required": false, "description": "Data final para filtrar os resultados", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "description": "Limite máximo de itens a serem retornados na consulta", "schema": { "type": "number", "default": 10 } }, { "in": "query", "name": "page", "required": false, "description": "Número da página para a paginação dos resultados", "schema": { "type": "number", "default": 1 } }, { "in": "query", "name": "recurrentPaymentId", "required": false, "description": "Filtra a cobrança inicial e os ciclos gerados por uma recorrência", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "description": "Página atual" }, "total": { "type": "integer", "description": "Total de cobranças encontradas" }, "totalPages": { "type": "integer", "description": "Total de páginas" }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } } } }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "page": 1, "total": 1, "totalPages": 1, "charges": [ { "id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "externalId": "pedido-1234", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "amount": 10000, "paymentType": "creditcard", "createdAt": "2026-06-12T14:35:22.000Z", "updatedAt": "2026-06-12T14:35:24.000Z", "customer": { "id": 501, "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "birthdate": "1990-04-15", "phone": "11999998888", "address": { "street": "Avenida Paulista", "number": "1000", "zipCode": "01310100", "city": "São Paulo", "state": "SP", "country": "BR", "district": "Bela Vista", "complement": "Conjunto 101" } }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "currency": "BRL", "acquirerTransactionId": "1049329871283a5d2b8e", "authorizationCode": "128734", "reasonCode": 0, "reasonMessage": "Successful", "status": 2, "returnCode": "6", "returnMessage": "Operação realizada com sucesso", "externalAuthentication": {}, "reversedAmount": null, "reversedDate": null, "chargeId": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "card": { "id": 42, "number": "411111******1111", "holder": "MARIA SOUZA", "expiration": "12/2030", "brand": "Visa" }, "chargebacks": [] } } ] } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.io/v1/charges' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges';\n\nconst response = await fetch(url, {\n method: 'GET',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.io/v1/charges',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/charges/{chargeId}": { "get": { "summary": "Consultar cobrança", "description": "Retorna os detalhes de uma determinada cobrança", "operationId": "get_charges__chargeId_", "tags": [ "Charges" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "chargeId", "required": true, "description": "Id da cobrança", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "externalId": "pedido-1234", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "amount": 10000, "paymentType": "creditcard", "createdAt": "2026-06-12T14:35:22.000Z", "updatedAt": "2026-06-12T14:35:24.000Z", "customer": { "id": 501, "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "birthdate": "1990-04-15", "phone": "11999998888", "address": { "street": "Avenida Paulista", "number": "1000", "zipCode": "01310100", "city": "São Paulo", "state": "SP", "country": "BR", "district": "Bela Vista", "complement": "Conjunto 101" } }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "currency": "BRL", "acquirerTransactionId": "1049329871283a5d2b8e", "authorizationCode": "128734", "reasonCode": 0, "reasonMessage": "Successful", "status": 2, "returnCode": "6", "returnMessage": "Operação realizada com sucesso", "externalAuthentication": {}, "reversedAmount": null, "reversedDate": null, "chargeId": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "card": { "id": 42, "number": "411111******1111", "holder": "MARIA SOUZA", "expiration": "12/2030", "brand": "Visa" }, "chargebacks": [] } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.io/v1/charges/9b1e7c34-5a2d-4f8b-8c1a-2e3f4a5b6c7d' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges/9b1e7c34-5a2d-4f8b-8c1a-2e3f4a5b6c7d';\n\nconst response = await fetch(url, {\n method: 'GET',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.io/v1/charges/9b1e7c34-5a2d-4f8b-8c1a-2e3f4a5b6c7d',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/charges/{chargeId}/reverse": { "put": { "summary": "Estornar cobrança", "description": "Realiza o estorno total ou parcial de uma cobrança", "operationId": "put_charges__chargeId__reverse", "tags": [ "Charges" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "chargeId", "required": true, "description": "Id da cobrança", "schema": { "type": "string" } }, { "in": "query", "name": "amount", "required": false, "description": "Valor da cobrança em centavos, para uma reversão parcial", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "externalId": "pedido-1234", "postbackUrl": "https://seusite.com.br/webhooks/payzu", "amount": 10000, "paymentType": "creditcard", "createdAt": "2026-06-12T14:35:22.000Z", "updatedAt": "2026-06-12T14:35:24.000Z", "customer": { "id": 501, "name": "Maria Souza", "identity": "11144477735", "identityType": "CPF", "email": "maria.souza@example.com", "birthdate": "1990-04-15", "phone": "11999998888", "address": { "street": "Avenida Paulista", "number": "1000", "zipCode": "01310100", "city": "São Paulo", "state": "SP", "country": "BR", "district": "Bela Vista", "complement": "Conjunto 101" } }, "cart": [ { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 } ], "creditCardPayment": { "installments": 1, "authenticate": false, "currency": "BRL", "acquirerTransactionId": "1049329871283a5d2b8e", "authorizationCode": "128734", "reasonCode": 0, "reasonMessage": "Successful", "status": 11, "returnCode": "6", "returnMessage": "Operação realizada com sucesso", "externalAuthentication": {}, "reversedAmount": 10000, "reversedDate": "2026-06-13T09:12:45.000Z", "chargeId": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90", "card": { "id": 42, "number": "411111******1111", "holder": "MARIA SOUZA", "expiration": "12/2030", "brand": "Visa" }, "chargebacks": [] } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PUT \\\n --url 'https://api.payzu.io/v1/charges/9b1e7c34-5a2d-4f8b-8c1a-2e3f4a5b6c7d/reverse' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges/9b1e7c34-5a2d-4f8b-8c1a-2e3f4a5b6c7d/reverse';\n\nconst response = await fetch(url, {\n method: 'PUT',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.put(\n 'https://api.payzu.io/v1/charges/9b1e7c34-5a2d-4f8b-8c1a-2e3f4a5b6c7d/reverse',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/charges/recurrences/{recurrentPaymentId}": { "get": { "summary": "Consultar recorrência", "description": "Retorna o estado atual da recorrência.\n\nPara listar a cobrança inicial e os ciclos já gerados, use [Listar Cobranças](https://docs.payzu.com.br/docs/cartao/endpoints/charges/get_charges) com o filtro `recurrentPaymentId`.", "operationId": "get_charges_recurrences__recurrentPaymentId_", "tags": [ "Recurrences" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "recurrentPaymentId", "required": true, "description": "Id da recorrência", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recurrence" }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "recurrentPaymentId": "5f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69';\n\nconst response = await fetch(url, {\n method: 'GET',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/charges/recurrences/{recurrentPaymentId}/amount": { "put": { "summary": "Alterar valor da recorrência", "description": "Altera o valor das próximas cobranças da recorrência. Não afeta ciclos já gerados.", "operationId": "put_charges_recurrences__recurrentPaymentId__amount", "tags": [ "Recurrences" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "recurrentPaymentId", "required": true, "description": "Id da recorrência", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "Novo valor de cada ciclo, em centavos", "example": 12000 } } }, "examples": { "Sucesso": { "summary": "Alterar valor", "value": { "amount": 12000 } } } } } }, "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recurrence" }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "recurrentPaymentId": "5f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "interval": "MONTHLY", "status": "ACTIVE", "amount": 12000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PUT \\\n --url 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/amount' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\" \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"amount\": 12000\n}'" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/amount';\n\nconst response = await fetch(url, {\n method: 'PUT',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n amount: 12000\n }),\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.put(\n 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/amount',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n 'Content-Type': 'application/json',\n },\n json={\n 'amount': 12000\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/charges/recurrences/{recurrentPaymentId}/deactivate": { "put": { "summary": "Desativar recorrência", "description": "Interrompe a recorrência: nenhum ciclo novo é gerado e o status passa a `INACTIVE`.", "operationId": "put_charges_recurrences__recurrentPaymentId__deactivate", "tags": [ "Recurrences" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "recurrentPaymentId", "required": true, "description": "Id da recorrência", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recurrence" }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "recurrentPaymentId": "5f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "interval": "MONTHLY", "status": "INACTIVE", "amount": 10000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PUT \\\n --url 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/deactivate' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/deactivate';\n\nconst response = await fetch(url, {\n method: 'PUT',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.put(\n 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/deactivate',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/charges/recurrences/{recurrentPaymentId}/reactivate": { "put": { "summary": "Reativar recorrência", "description": "Retoma uma recorrência desativada: o status volta para `ACTIVE` e os ciclos voltam a ser gerados.", "operationId": "put_charges_recurrences__recurrentPaymentId__reactivate", "tags": [ "Recurrences" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "recurrentPaymentId", "required": true, "description": "Id da recorrência", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Requisição bem sucedida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Recurrence" }, "examples": { "Sucesso": { "summary": "Sucesso", "value": { "recurrentPaymentId": "5f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "interval": "MONTHLY", "status": "ACTIVE", "amount": 10000, "nextRecurrency": "2026-07-12T00:00:00.000Z", "endDate": "2027-06-12T00:00:00.000Z" } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request PUT \\\n --url 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/reactivate' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/reactivate';\n\nconst response = await fetch(url, {\n method: 'PUT',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.put(\n 'https://api.payzu.io/v1/charges/recurrences/3f5a1b2c-9d8e-4c7b-a6f5-1e2d3c4b5a69/reactivate',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/currencies/{code}/rate": { "get": { "summary": "Cotação de moeda", "description": "Retorna a cotação bid/ask atual de uma moeda, em BRL por unidade estrangeira.\n\nA cotação é um número decimal, não um valor em centavos.", "operationId": "get_currency_rate", "tags": [ "Currencies" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "code", "required": true, "description": "Código de moeda ISO 4217. BRL não é aceito.", "schema": { "type": "string", "example": "USD" } } ], "responses": { "200": { "description": "Cotação atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyRate" }, "examples": { "usd": { "value": { "code": "USD", "rate": { "bid": 5.42, "ask": 5.43 } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.io/v1/currencies/USD/rate' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/currencies/USD/rate';\n\nconst response = await fetch(url, {\n method: 'GET',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.io/v1/currencies/USD/rate',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/currencies/{code}/convert": { "get": { "summary": "Converter valor", "description": "Converte um valor informado em centavos de BRL para a moeda de destino, usando a cotação bid ou ask.\n\nA saída também é expressa em centavos da moeda de destino.", "operationId": "get_currency_convert", "tags": [ "Currencies" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "parameters": [ { "in": "path", "name": "code", "required": true, "description": "Código de moeda ISO 4217. BRL não é aceito.", "schema": { "type": "string", "example": "USD" } }, { "in": "query", "name": "amount", "required": true, "description": "Valor em centavos de BRL. Mínimo 100 (R$1,00).", "schema": { "type": "integer", "minimum": 100, "example": 10000 } }, { "in": "query", "name": "type", "required": true, "description": "Qual lado da cotação usar.", "schema": { "type": "string", "enum": [ "bid", "ask" ], "example": "ask" } } ], "responses": { "200": { "description": "Valor convertido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrencyConvertResponse" }, "examples": { "usd": { "value": { "amount": 1841.62, "currency": { "code": "USD", "rate": { "ask": 5.43 } } } } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.io/v1/currencies/USD/convert?amount=10000&type=ask' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/currencies/USD/convert?amount=10000&type=ask';\n\nconst response = await fetch(url, {\n method: 'GET',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.io/v1/currencies/USD/convert?amount=10000&type=ask',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } }, "/currencies/rates": { "get": { "summary": "Listar cotações", "description": "Lista as cotações bid/ask de todas as moedas do último fechamento do BCB.\n\nCada cotação é um número decimal, não um valor em centavos.", "operationId": "get_currency_rates", "tags": [ "Currencies" ], "security": [ { "BearerAuth": [], "MutualTLS": [] } ], "responses": { "200": { "description": "Lista de cotações.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyRate" } }, "examples": { "list": { "value": [ { "code": "USD", "rate": { "bid": 5.42, "ask": 5.43 } }, { "code": "EUR", "rate": { "bid": 5.88, "ask": 5.89 } } ] } } } } } }, "x-codeSamples": [ { "id": "curl", "lang": "bash", "label": "cURL", "source": "curl --request GET \\\n --url 'https://api.payzu.io/v1/currencies/rates' \\\n --header \"Authorization: Bearer $PAYZU_TOKEN\" \\\n --cert \"$PAYZU_CLIENT_CERT\" --key \"$PAYZU_CLIENT_KEY\"" }, { "id": "js", "lang": "js", "label": "Node.js", "source": "import { readFileSync } from 'node:fs';\nimport { Agent } from 'undici';\n\nconst agent = new Agent({\n connect: {\n cert: readFileSync(process.env.PAYZU_CLIENT_CERT),\n key: readFileSync(process.env.PAYZU_CLIENT_KEY),\n },\n});\n\nconst url = 'https://api.payzu.io/v1/currencies/rates';\n\nconst response = await fetch(url, {\n method: 'GET',\n dispatcher: agent,\n headers: {\n Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,\n },\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "id": "python", "lang": "python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n 'https://api.payzu.io/v1/currencies/rates',\n headers={\n 'Authorization': f'Bearer {os.environ[\"PAYZU_TOKEN\"]}',\n },\n cert=(os.environ['PAYZU_CLIENT_CERT'], os.environ['PAYZU_CLIENT_KEY']),\n)\n\nprint(response.json())" } ] } } }, "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "client_id e client_secret da sua conta, apenas para obter o token" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Token JWT obtido em POST /token" }, "MutualTLS": { "type": "mutualTLS", "description": "Certificado de cliente mTLS emitido pela PayZu, exigido em todas as rotas" } }, "schemas": { "Address": { "type": "object", "description": "Endereço de cobrança", "required": [ "street", "number", "zipCode", "city", "state", "country", "district" ], "properties": { "street": { "type": "string", "description": "Logradouro do endereço de cobrança", "example": "Avenida Paulista" }, "number": { "type": "string", "description": "Número do endereço de cobrança", "example": "1000" }, "complement": { "type": "string", "description": "Complemento do endereço de cobrança", "example": "Conjunto 101" }, "zipCode": { "type": "string", "description": "Código postal do endereço de cobrança", "example": "01310100" }, "city": { "type": "string", "description": "Cidade do endereço de cobrança", "example": "Sao Paulo" }, "state": { "type": "string", "description": "Estado do endereço de cobrança", "example": "SP" }, "country": { "type": "string", "description": "País do endereço de cobrança", "example": "BR" }, "district": { "type": "string", "description": "Bairro do endereço de cobrança", "example": "Bela Vista" } } }, "CustomerRequest": { "type": "object", "description": "Dados do comprador", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Nome completo do comprador", "example": "Maria Souza" }, "identity": { "type": "string", "description": "Número do documento de identificação do comprador", "example": "12345678909" }, "identityType": { "type": "string", "description": "Tipo de documento de identificação do comprador", "example": "CPF" }, "email": { "type": "string", "description": "E-mail do comprador", "example": "maria.souza@example.com" }, "birthdate": { "type": "string", "description": "Data de nascimento do comprador", "example": "1990-05-20" }, "phone": { "type": "string", "description": "Número do telefone do comprador", "example": "+5511999998888" }, "address": { "$ref": "#/components/schemas/Address" } } }, "CustomerResponse": { "type": "object", "description": "Dados do comprador", "properties": { "id": { "type": "number", "description": "Identificador do comprador." }, "name": { "type": "string", "description": "Nome completo do comprador" }, "identity": { "type": "string", "description": "Número do documento de identificação do comprador" }, "identityType": { "type": "string", "description": "Tipo de documento de identificação do comprador" }, "email": { "type": "string", "description": "E-mail do comprador" }, "birthdate": { "type": "string", "description": "Data de nascimento do comprador" }, "phone": { "type": "string", "description": "Número do telefone do comprador" }, "address": { "type": "object", "description": "Endereço de cobrança", "required": [ "street", "number", "zipCode", "city", "state", "country", "district" ], "properties": { "street": { "type": "string", "description": "Logradouro do endereço de cobrança" }, "number": { "type": "string", "description": "Número do endereço de cobrança" }, "complement": { "type": "string", "description": "Complemento do endereço de cobrança" }, "zipCode": { "type": "string", "description": "Código postal do endereço de cobrança" }, "city": { "type": "string", "description": "Cidade do endereço de cobrança" }, "state": { "type": "string", "description": "Estado do endereço de cobrança" }, "country": { "type": "string", "description": "País do endereço de cobrança" }, "district": { "type": "string", "description": "Bairro do endereço de cobrança" } }, "nullable": true } } }, "CartItem": { "type": "object", "required": [ "name", "quantity", "sku", "unitPrice" ], "properties": { "name": { "type": "string", "description": "Nome do produto", "example": "Camiseta PayZu" }, "quantity": { "type": "number", "description": "Quantidade do produto", "example": 1 }, "sku": { "type": "string", "description": "SKU (Stock Keeping Unit - Unidade de Controle de Estoque) do produto", "example": "CAM-PZ-001" }, "unitPrice": { "type": "number", "description": "Preço unitário do produto em centavos", "example": 10000 } } }, "CardRequest": { "type": "object", "description": "Detalhes do cartão", "required": [ "number", "holder", "expiration", "cvv" ], "properties": { "number": { "type": "string", "description": "Número do cartão de crédito", "example": "4111111111111111" }, "holder": { "type": "string", "description": "Nome do portador impresso no cartão de crédito", "example": "MARIA SOUZA" }, "expiration": { "type": "string", "description": "Data de validade do cartão de crédito", "example": "12/2030" }, "cvv": { "type": "string", "description": "Código de segurança no verso do cartão de crédito", "example": "123" } } }, "CardResponse": { "type": "object", "description": "Detalhes do cartão utilizado na cobrança", "properties": { "id": { "type": "number", "description": "Identificador do cartão." }, "number": { "type": "string", "description": "Número do cartão de crédito" }, "holder": { "type": "string", "description": "Nome do portador impresso no cartão de crédito" }, "expiration": { "type": "string", "description": "Data de validade do cartão de crédito" }, "brand": { "type": "string", "description": "Bandeira do cartão. Valores em [Códigos de referência](https://docs.payzu.com.br/docs/cartao/reference-codes)", "enum": [ "Visa", "Master", "Elo", "Diners", "Hipercard" ] } } }, "ExternalAuthentication": { "type": "object", "description": "Dados de autenticação 3DS realizada fora da PayZu (autenticação externa)", "required": [ "cavv", "eci", "version", "referenceId" ], "properties": { "cavv": { "type": "string", "description": "Assinatura retornada nos cenários de sucesso na autenticação", "example": "AAABCZIhcQAAAABZlyFxAAAAAAA=" }, "xid": { "type": "string", "description": "XID retornado no processo de autenticação", "example": "MDAwMDAwMDAwMDAwMDAwMTIzNDU=" }, "eci": { "type": "string", "description": "Electronic Commerce Indicator devolvido na autenticação. Tabela em [3-D Secure](https://docs.payzu.com.br/docs/cartao/three-d-secure#tabela-eci)", "example": "05" }, "version": { "type": "string", "description": "Versão do 3DS aplicado no processo de autenticação", "example": "2.2.0" }, "referenceId": { "type": "string", "description": "RequestID retornado no processo de autenticação", "example": "8c1b3e2a-1234-4a56-9b78-abcdef012345" } } }, "FraudAnalysis": { "type": "object", "description": "Dados para o motor antifraude. Obrigatório em cobranças internacionais. Regras em [Antifraude](https://docs.payzu.com.br/docs/cartao/antifraud)", "required": [ "fingerPrintId", "browser", "definedFields" ], "properties": { "fingerPrintId": { "type": "string", "description": "Identificador utilizado para cruzar informações obtidas do dispositivo do comprador", "example": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" }, "browser": { "type": "object", "description": "Informações sobre o navegador do comprador", "required": [ "cookiesAccepted", "ipAddress" ], "properties": { "cookiesAccepted": { "type": "boolean", "description": "Identifica se o browser do comprador aceita cookies", "example": true }, "email": { "type": "string", "description": "E-mail registrado no browser do comprador", "example": "maria.souza@example.com" }, "hostName": { "type": "string", "description": "Nome do host informado pelo browser do comprador e identificado através do cabeçalho HTTP", "example": "www.sualoja.com.br" }, "ipAddress": { "type": "string", "description": "Endereço de IP do comprador (IPv4 ou IPv6)", "example": "200.201.202.203" }, "type": { "type": "string", "description": "Nome do browser utilizado pelo comprador e identificado através do cabeçalho HTTP", "example": "Chrome" } } }, "definedFields": { "type": "array", "description": "Merchant Defined Data (MDD). Lista em [Tabela de MDDs](https://docs.payzu.com.br/docs/cartao/mdds)", "items": { "type": "object", "required": [ "id", "value" ], "properties": { "id": { "type": "number", "description": "Identificador do MDD, conforme [Tabela de MDDs](https://docs.payzu.com.br/docs/cartao/mdds)", "example": 2 }, "value": { "type": "string", "description": "Valor do MDD", "example": "Web" } } } } } }, "Chargeback": { "type": "object", "properties": { "id": { "type": "number", "description": "Identificador do chargeback" }, "number": { "type": "string", "nullable": true, "description": "Número do chargeback junto à adquirente" }, "amount": { "type": "number", "description": "Valor do chargeback em centavos" }, "status": { "type": "string", "description": "Status do chargeback. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status)", "enum": [ "RECEIVED", "ACCEPTED", "DEFENDED" ] }, "reasonCode": { "type": "string", "nullable": true, "description": "Código do motivo informado pela bandeira" }, "reasonDescription": { "type": "string", "nullable": true, "description": "Descrição do motivo informado pela bandeira" }, "issuedAt": { "type": "string", "description": "Data de emissão do chargeback" }, "createdAt": { "type": "string", "description": "Data de criação do registro" }, "updatedAt": { "type": "string", "description": "Data da última atualização do registro" } } }, "CreditCardPaymentResponse": { "type": "object", "description": "Detalhes do pagamento com cartão de crédito", "properties": { "installments": { "type": "number", "description": "Número de parcelas" }, "authenticate": { "type": "boolean", "description": "Indica se o comprador foi direcionado ao emissor para autenticação 3DS" }, "currency": { "type": "string", "description": "Moeda da cobrança. Lista em [Moedas suportadas](https://docs.payzu.com.br/docs/cartao/currencies)", "example": "BRL" }, "acquirerTransactionId": { "type": "string", "nullable": true, "description": "Identificador da transação na adquirente" }, "authorizationCode": { "type": "string", "nullable": true, "description": "Código de autorização retornado pela adquirente" }, "reasonCode": { "type": "number", "description": "Código do motivo do resultado. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status)" }, "reasonMessage": { "type": "string", "nullable": true, "description": "Mensagem do motivo do resultado. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status)" }, "status": { "type": "integer", "description": "Status da transação. Lista em [Status e motivos da transação](https://docs.payzu.com.br/docs/cartao/transaction-status)" }, "returnCode": { "type": "string", "nullable": true, "description": "Código de retorno da adquirente, lido na tabela de [Códigos de erro](https://docs.payzu.com.br/docs/cartao/error-codes). O mesmo número tem outro significado na tabela [ABECS](https://docs.payzu.com.br/docs/cartao/abecs-codes), que é o padrão das bandeiras para recusas." }, "returnMessage": { "type": "string", "nullable": true, "description": "Mensagem de retorno da adquirente" }, "externalAuthentication": { "type": "object", "description": "Dados da autenticação externa 3DS, quando enviados na criação", "properties": {} }, "reversedAmount": { "type": "number", "nullable": true, "description": "Valor estornado em centavos, quando houver estorno" }, "reversedDate": { "type": "string", "nullable": true, "description": "Data do estorno, quando houver" }, "chargeId": { "type": "string", "description": "Identificador da cobrança" }, "card": { "$ref": "#/components/schemas/CardResponse" }, "chargebacks": { "type": "array", "description": "Chargebacks vinculados à cobrança", "items": { "$ref": "#/components/schemas/Chargeback" } } } }, "RecurrenceRequest": { "type": "object", "description": "Configuração de pagamento recorrente. A primeira cobrança é criada na hora, os ciclos seguintes são gerados automaticamente e `installments` precisa ser 1. Regras em [Pagamentos recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence)", "required": [ "interval" ], "properties": { "interval": { "type": "string", "description": "Intervalo entre as cobranças: `Monthly` (mensal) ou `Annual` (anual)", "enum": [ "Monthly", "Annual" ] }, "endDate": { "type": "string", "description": "Data final da recorrência no formato `YYYY-MM-DD`. Sem ela, a recorrência segue indefinidamente", "example": "2027-06-12" } } }, "Recurrence": { "type": "object", "description": "Estado de uma recorrência", "properties": { "recurrentPaymentId": { "type": "string", "description": "Identificador da recorrência. Use nos endpoints de consulta e gestão de recorrências" }, "interval": { "type": "string", "description": "Intervalo configurado", "enum": [ "MONTHLY", "ANNUAL" ] }, "status": { "type": "string", "description": "Status da recorrência. Valores em [Pagamentos recorrentes](https://docs.payzu.com.br/docs/cartao/recurrence)", "enum": [ "ACTIVE", "INACTIVE", "ENDED" ] }, "amount": { "type": "number", "description": "Valor de cada ciclo, em centavos" }, "nextRecurrency": { "type": "string", "description": "Data da próxima cobrança automática" }, "endDate": { "type": "string", "nullable": true, "description": "Data final, se informada na criação" } } }, "Charge": { "type": "object", "properties": { "id": { "type": "string", "description": "Identificador da cobrança" }, "externalId": { "type": "string", "description": "Identificador único gerado externamente" }, "postbackUrl": { "type": "string", "nullable": true, "description": "Url para notificações sobre o status da cobrança" }, "amount": { "type": "number", "description": "Valor da cobrança em centavos" }, "paymentType": { "type": "string", "description": "Tipo de pagamento da cobrança. Valores em [Códigos de referência](https://docs.payzu.com.br/docs/cartao/reference-codes)", "example": "creditcard" }, "createdAt": { "type": "string", "description": "Data de criação da cobrança" }, "updatedAt": { "type": "string", "description": "Data da última atualização da cobrança" }, "customer": { "$ref": "#/components/schemas/CustomerResponse" }, "cart": { "type": "array", "description": "Carrinho do comprador", "items": { "$ref": "#/components/schemas/CartItem" } }, "creditCardPayment": { "$ref": "#/components/schemas/CreditCardPaymentResponse" }, "recurrence": { "$ref": "#/components/schemas/Recurrence", "description": "Presente quando a cobrança pertence a uma recorrência" }, "recurrenceCycle": { "type": "integer", "nullable": true, "description": "Número do ciclo da recorrência a que esta cobrança pertence: 0 é a cobrança inicial, 1..n são os ciclos gerados automaticamente. Presente apenas em cobranças de recorrência" } } }, "ChargeRequest": { "type": "object", "required": [ "amount", "customer", "paymentType", "cart", "creditCardPayment", "externalId" ], "properties": { "amount": { "type": "number", "description": "Valor da cobrança em centavos", "example": 10000 }, "customer": { "$ref": "#/components/schemas/CustomerRequest" }, "postbackUrl": { "type": "string", "description": "URL que recebe as notificações de status da cobrança. Formato em [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks)", "example": "https://sualoja.com.br/webhooks/cartao" }, "paymentType": { "type": "string", "description": "Tipo de pagamento da cobrança. Valores em [Códigos de referência](https://docs.payzu.com.br/docs/cartao/reference-codes)", "enum": [ "creditcard" ] }, "cart": { "type": "array", "description": "Carrinho do comprador", "items": { "$ref": "#/components/schemas/CartItem" } }, "creditCardPayment": { "type": "object", "description": "Definições para o tipo de pagamento: cartão de crédito", "required": [ "installments", "card", "authenticate" ], "properties": { "installments": { "type": "number", "description": "Número de parcelas. Em cobranças internacionais e em recorrências deve ser 1", "example": 1 }, "card": { "$ref": "#/components/schemas/CardRequest" }, "currency": { "type": "string", "description": "Moeda da cobrança. Em moeda estrangeira, `amount` passa a ser expresso na menor unidade dessa moeda. Lista em [Moedas suportadas](https://docs.payzu.com.br/docs/cartao/currencies) e regras em [Cobrança internacional](https://docs.payzu.com.br/docs/cartao/international)", "default": "BRL" }, "authenticate": { "type": "boolean", "description": "Define se o comprador será direcionado ao emissor para autenticação do cartão (3DS)", "example": false }, "externalAuthentication": { "$ref": "#/components/schemas/ExternalAuthentication" }, "fraudAnalysis": { "$ref": "#/components/schemas/FraudAnalysis" } } }, "recurrence": { "$ref": "#/components/schemas/RecurrenceRequest" }, "externalId": { "type": "string", "description": "Identificador único gerado externamente", "example": "pedido-2025-001" } } }, "CurrencyRate": { "type": "object", "properties": { "code": { "type": "string", "example": "USD", "description": "Código ISO 4217 da moeda." }, "rate": { "type": "object", "properties": { "bid": { "type": "number", "description": "Taxa de compra (BRL por unidade estrangeira).", "example": 5.42 }, "ask": { "type": "number", "description": "Taxa de venda (BRL por unidade estrangeira).", "example": 5.43 } }, "required": [ "bid", "ask" ], "description": "Cotação de compra e de venda da moeda, em BRL por unidade estrangeira." } }, "required": [ "code", "rate" ] }, "CurrencyConvertResponse": { "type": "object", "properties": { "amount": { "type": "number", "description": "Valor convertido, em centavos da moeda de destino (`amount` dividido pela cotação), arredondado a 2 casas decimais.", "example": 1841.62 }, "currency": { "type": "object", "properties": { "code": { "type": "string", "example": "USD" }, "rate": { "type": "object", "properties": { "bid": { "type": "number" }, "ask": { "type": "number" } } } }, "description": "Moeda de destino e a cotação usada na conversão." } }, "required": [ "amount", "currency" ] } } } }