{
  "openapi": "3.1.0",
  "info": {
    "version": "1.0.0",
    "title": "PayZu Credit Card API",
    "description": "PayZu credit card charges API: authorization, 3DS, antifraud, recurring payments, reversals and chargebacks.\n\nAuthentication: mTLS + Bearer token. See [Authentication](https://docs.payzu.com.br/docs/cartao/authentication).\n\nGuides and full reference at [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": "Authentication and access token issuance"
    },
    {
      "name": "Charges",
      "description": "Creation, query and reversal of card charges"
    },
    {
      "name": "Recurrences",
      "description": "Query and management of recurring payments"
    }
  ],
  "paths": {
    "/token": {
      "post": {
        "summary": "Get API token",
        "description": "Returns a JWT token to authenticate the routes. Send your account's `client_id` and `client_secret` via Basic Auth, over the mTLS connection.\n\nSee [Authentication](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": "OAuth grant type",
                    "enum": [
                      "client_credentials"
                    ],
                    "default": "client_credentials"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": {
                      "type": "string",
                      "description": "JWT token to send in the Authorization: Bearer header"
                    },
                    "token_type": {
                      "type": "string",
                      "description": "Token type"
                    },
                    "expires_in": {
                      "type": "number",
                      "description": "Token lifetime, in seconds"
                    }
                  }
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "value": {
                      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
                      "token_type": "Bearer",
                      "expires_in": 3600
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/charges": {
      "post": {
        "summary": "Create Charge",
        "description": "Creates a new credit card charge.\n\n- For 3DS authentication, see [Using 3DS](https://docs.payzu.com.br/docs/cartao/three-d-secure).\n- For the antifraud engine, see [Using Antifraud](https://docs.payzu.com.br/docs/cartao/antifraud).\n- For foreign currency charges, see [International charges](https://docs.payzu.com.br/docs/cartao/international).\n- For recurring payments, send the `recurrence` node. See [Recurring Payments](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": {
                "Simple charge": {
                  "summary": "Simple charge",
                  "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"
                      }
                    }
                  }
                },
                "Recurring charge": {
                  "summary": "Recurring charge (subscription)",
                  "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": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Charge"
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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": "4111111111111111",
                          "holder": "MARIA SOUZA",
                          "expiration": "12/2030",
                          "brand": "Visa"
                        },
                        "chargebacks": []
                      }
                    }
                  },
                  "Recurrence created": {
                    "summary": "Recurrence created",
                    "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": "4111111111111111",
                          "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
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List Charges",
        "description": "Returns a list of charges",
        "operationId": "get_charges",
        "tags": [
          "Charges"
        ],
        "security": [
          {
            "BearerAuth": [],
            "MutualTLS": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "startDate",
            "required": false,
            "description": "Start date to filter the results",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "endDate",
            "required": false,
            "description": "End date to filter the results",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "Maximum number of items to return in the query",
            "schema": {
              "type": "number",
              "default": 10
            }
          },
          {
            "in": "query",
            "name": "page",
            "required": false,
            "description": "Page number for result pagination",
            "schema": {
              "type": "number",
              "default": 1
            }
          },
          {
            "in": "query",
            "name": "recurrentPaymentId",
            "required": false,
            "description": "Filters the initial charge and the cycles generated by a recurrence",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "page": {
                      "type": "integer",
                      "description": "Current page"
                    },
                    "total": {
                      "type": "integer",
                      "description": "Total charges found"
                    },
                    "totalPages": {
                      "type": "integer",
                      "description": "Total pages"
                    },
                    "charges": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Charge"
                      }
                    }
                  }
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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": "4111111111111111",
                              "holder": "MARIA SOUZA",
                              "expiration": "12/2030",
                              "brand": "Visa"
                            },
                            "chargebacks": []
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/charges/{chargeId}": {
      "get": {
        "summary": "Retrieve Charge",
        "description": "Returns the details of a given charge",
        "operationId": "get_charges__chargeId_",
        "tags": [
          "Charges"
        ],
        "security": [
          {
            "BearerAuth": [],
            "MutualTLS": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "chargeId",
            "required": true,
            "description": "Charge id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Charge"
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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": "4111111111111111",
                          "holder": "MARIA SOUZA",
                          "expiration": "12/2030",
                          "brand": "Visa"
                        },
                        "chargebacks": []
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/charges/{chargeId}/reverse": {
      "put": {
        "summary": "Reverse Charge",
        "description": "Performs a full or partial reversal of a charge",
        "operationId": "put_charges__chargeId__reverse",
        "tags": [
          "Charges"
        ],
        "security": [
          {
            "BearerAuth": [],
            "MutualTLS": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "chargeId",
            "required": true,
            "description": "Charge id",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "amount",
            "required": false,
            "description": "Charge amount in cents, for a partial reversal",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Charge"
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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": "4111111111111111",
                          "holder": "MARIA SOUZA",
                          "expiration": "12/2030",
                          "brand": "Visa"
                        },
                        "chargebacks": []
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/charges/recurrences/{recurrentPaymentId}": {
      "get": {
        "summary": "Retrieve Recurrence",
        "description": "Returns the current state of the recurrence.\n\nTo list the initial charge and the cycles already generated, use [List Charges](https://docs.payzu.com.br/docs/cartao/endpoints/charges/get_charges) with the `recurrentPaymentId` filter.",
        "operationId": "get_charges_recurrences__recurrentPaymentId_",
        "tags": [
          "Recurrences"
        ],
        "security": [
          {
            "BearerAuth": [],
            "MutualTLS": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "recurrentPaymentId",
            "required": true,
            "description": "Recurrence id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recurrence"
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/charges/recurrences/{recurrentPaymentId}/amount": {
      "put": {
        "summary": "Update Recurrence amount",
        "description": "Updates the amount of the next charges of the recurrence. Cycles already generated are not affected.",
        "operationId": "put_charges_recurrences__recurrentPaymentId__amount",
        "tags": [
          "Recurrences"
        ],
        "security": [
          {
            "BearerAuth": [],
            "MutualTLS": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "recurrentPaymentId",
            "required": true,
            "description": "Recurrence id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "description": "New amount of each cycle, in cents",
                    "example": 12000
                  }
                }
              },
              "examples": {
                "Success": {
                  "summary": "Update amount",
                  "value": {
                    "amount": 12000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recurrence"
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/charges/recurrences/{recurrentPaymentId}/deactivate": {
      "put": {
        "summary": "Deactivate Recurrence",
        "description": "Stops the recurrence: no new cycle is generated and the status becomes `INACTIVE`.",
        "operationId": "put_charges_recurrences__recurrentPaymentId__deactivate",
        "tags": [
          "Recurrences"
        ],
        "security": [
          {
            "BearerAuth": [],
            "MutualTLS": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "recurrentPaymentId",
            "required": true,
            "description": "Recurrence id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recurrence"
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/charges/recurrences/{recurrentPaymentId}/reactivate": {
      "put": {
        "summary": "Reactivate Recurrence",
        "description": "Resumes a deactivated recurrence: the status returns to `ACTIVE` and cycles are generated again.",
        "operationId": "put_charges_recurrences__recurrentPaymentId__reactivate",
        "tags": [
          "Recurrences"
        ],
        "security": [
          {
            "BearerAuth": [],
            "MutualTLS": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "recurrentPaymentId",
            "required": true,
            "description": "Recurrence id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recurrence"
                },
                "examples": {
                  "Success": {
                    "summary": "Success",
                    "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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Your account's client_id and client_secret, only to get the token"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "JWT token obtained from POST /token"
      },
      "MutualTLS": {
        "type": "mutualTLS",
        "description": "mTLS client certificate issued by PayZu, required on every route"
      }
    },
    "schemas": {
      "Address": {
        "type": "object",
        "description": "Billing address",
        "required": [
          "street",
          "number",
          "zipCode",
          "city",
          "state",
          "country",
          "district"
        ],
        "properties": {
          "street": {
            "type": "string",
            "description": "Billing address street"
          },
          "number": {
            "type": "string",
            "description": "Billing address number"
          },
          "complement": {
            "type": "string",
            "description": "Billing address complement"
          },
          "zipCode": {
            "type": "string",
            "description": "Billing address postal code"
          },
          "city": {
            "type": "string",
            "description": "Billing address city"
          },
          "state": {
            "type": "string",
            "description": "Billing address state"
          },
          "country": {
            "type": "string",
            "description": "Billing address country"
          },
          "district": {
            "type": "string",
            "description": "Billing address district"
          }
        }
      },
      "CustomerRequest": {
        "type": "object",
        "description": "Buyer data",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Buyer's full name"
          },
          "identity": {
            "type": "string",
            "description": "Buyer's identification document number"
          },
          "identityType": {
            "type": "string",
            "description": "Buyer's identification document type",
            "example": "CPF"
          },
          "email": {
            "type": "string",
            "description": "Buyer's email"
          },
          "birthdate": {
            "type": "string",
            "description": "Buyer's birthdate"
          },
          "phone": {
            "type": "string",
            "description": "Buyer's phone number"
          },
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        }
      },
      "CustomerResponse": {
        "type": "object",
        "description": "Buyer data",
        "properties": {
          "id": {
            "type": "number",
            "description": "Internal buyer identifier"
          },
          "name": {
            "type": "string",
            "description": "Buyer's full name"
          },
          "identity": {
            "type": "string",
            "description": "Buyer's identification document number"
          },
          "identityType": {
            "type": "string",
            "description": "Buyer's identification document type"
          },
          "email": {
            "type": "string",
            "description": "Buyer's email"
          },
          "birthdate": {
            "type": "string",
            "description": "Buyer's birthdate"
          },
          "phone": {
            "type": "string",
            "description": "Buyer's phone number"
          },
          "address": {
            "type": "object",
            "description": "Billing address",
            "required": [
              "street",
              "number",
              "zipCode",
              "city",
              "state",
              "country",
              "district"
            ],
            "properties": {
              "street": {
                "type": "string",
                "description": "Billing address street"
              },
              "number": {
                "type": "string",
                "description": "Billing address number"
              },
              "complement": {
                "type": "string",
                "description": "Billing address complement"
              },
              "zipCode": {
                "type": "string",
                "description": "Billing address postal code"
              },
              "city": {
                "type": "string",
                "description": "Billing address city"
              },
              "state": {
                "type": "string",
                "description": "Billing address state"
              },
              "country": {
                "type": "string",
                "description": "Billing address country"
              },
              "district": {
                "type": "string",
                "description": "Billing address district"
              }
            },
            "nullable": true
          }
        }
      },
      "CartItem": {
        "type": "object",
        "required": [
          "name",
          "quantity",
          "sku",
          "unitPrice"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Product name"
          },
          "quantity": {
            "type": "number",
            "description": "Product quantity"
          },
          "sku": {
            "type": "string",
            "description": "Product SKU (Stock Keeping Unit)"
          },
          "unitPrice": {
            "type": "number",
            "description": "Product unit price in cents"
          }
        }
      },
      "CardRequest": {
        "type": "object",
        "description": "Card details",
        "required": [
          "number",
          "holder",
          "expiration",
          "cvv"
        ],
        "properties": {
          "number": {
            "type": "string",
            "description": "Credit card number",
            "example": "4111111111111111"
          },
          "holder": {
            "type": "string",
            "description": "Cardholder name as printed on the credit card",
            "example": "MARIA SOUZA"
          },
          "expiration": {
            "type": "string",
            "description": "Credit card expiration date",
            "example": "12/2030"
          },
          "cvv": {
            "type": "string",
            "description": "Security code on the back of the credit card",
            "example": "123"
          }
        }
      },
      "CardResponse": {
        "type": "object",
        "description": "Details of the card used in the charge",
        "properties": {
          "id": {
            "type": "number",
            "description": "Internal card identifier"
          },
          "number": {
            "type": "string",
            "description": "Credit card number"
          },
          "holder": {
            "type": "string",
            "description": "Cardholder name as printed on the credit card"
          },
          "expiration": {
            "type": "string",
            "description": "Credit card expiration date"
          },
          "brand": {
            "type": "string",
            "description": "Card brand. See [Brand](https://docs.payzu.com.br/docs/cartao/reference-codes)",
            "enum": [
              "Visa",
              "Master",
              "Elo",
              "Diners"
            ]
          }
        }
      },
      "ExternalAuthentication": {
        "type": "object",
        "description": "3DS authentication data performed outside PayZu (external authentication)",
        "required": [
          "cavv",
          "eci",
          "version",
          "referenceId"
        ],
        "properties": {
          "cavv": {
            "type": "string",
            "description": "Signature returned on successful authentication scenarios"
          },
          "xid": {
            "type": "string",
            "description": "XID returned in the authentication process"
          },
          "eci": {
            "type": "string",
            "description": "Electronic Commerce Indicator returned in the authentication process. See [ECI table](https://docs.payzu.com.br/docs/cartao/reference-codes)"
          },
          "version": {
            "type": "string",
            "description": "3DS version applied in the authentication process"
          },
          "referenceId": {
            "type": "string",
            "description": "RequestID returned in the authentication process"
          }
        }
      },
      "FraudAnalysis": {
        "type": "object",
        "description": "Data for the antifraud engine. Required on international charges. See [Using Antifraud](https://docs.payzu.com.br/docs/cartao/antifraud)",
        "required": [
          "fingerPrintId",
          "browser",
          "definedFields"
        ],
        "properties": {
          "fingerPrintId": {
            "type": "string",
            "description": "Identifier used to correlate information collected from the buyer's device"
          },
          "browser": {
            "type": "object",
            "description": "Information about the buyer's browser",
            "required": [
              "cookiesAccepted",
              "ipAddress"
            ],
            "properties": {
              "cookiesAccepted": {
                "type": "boolean",
                "description": "Indicates whether the buyer's browser accepts cookies"
              },
              "email": {
                "type": "string",
                "description": "Email registered in the buyer's browser"
              },
              "hostName": {
                "type": "string",
                "description": "Host name reported by the buyer's browser, identified through the HTTP header"
              },
              "ipAddress": {
                "type": "string",
                "description": "Buyer's IP address (IPv4 or IPv6)"
              },
              "type": {
                "type": "string",
                "description": "Name of the browser used by the buyer, identified through the HTTP header"
              }
            }
          },
          "definedFields": {
            "type": "array",
            "description": "Merchant Defined Data (MDD). See [MDD table](https://docs.payzu.com.br/docs/cartao/mdds)",
            "items": {
              "type": "object",
              "required": [
                "id",
                "value"
              ],
              "properties": {
                "id": {
                  "type": "number",
                  "description": "MDD identifier, as in the [MDD table](https://docs.payzu.com.br/docs/cartao/mdds)"
                },
                "value": {
                  "type": "string",
                  "description": "MDD value"
                }
              }
            }
          }
        }
      },
      "Chargeback": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "description": "Chargeback identifier"
          },
          "number": {
            "type": "string",
            "nullable": true,
            "description": "Chargeback number at the acquirer"
          },
          "amount": {
            "type": "number",
            "description": "Chargeback amount in cents"
          },
          "status": {
            "type": "string",
            "description": "Chargeback status. See [Chargeback status list](https://docs.payzu.com.br/docs/cartao/transaction-status)",
            "enum": [
              "RECEIVED",
              "ACCEPTED",
              "DEFENDED"
            ]
          },
          "reasonCode": {
            "type": "string",
            "nullable": true,
            "description": "Reason code provided by the card brand"
          },
          "reasonDescription": {
            "type": "string",
            "nullable": true,
            "description": "Reason description provided by the card brand"
          },
          "issuedAt": {
            "type": "string",
            "description": "Chargeback issue date"
          },
          "createdAt": {
            "type": "string",
            "description": "Record creation date"
          },
          "updatedAt": {
            "type": "string",
            "description": "Date the record was last updated"
          }
        }
      },
      "CreditCardPaymentResponse": {
        "type": "object",
        "description": "Credit card payment details",
        "properties": {
          "installments": {
            "type": "number",
            "description": "Number of installments"
          },
          "authenticate": {
            "type": "boolean",
            "description": "Indicates whether the buyer was redirected to the issuer for 3DS authentication"
          },
          "currency": {
            "type": "string",
            "description": "Charge currency. See [Currencies](https://docs.payzu.com.br/docs/cartao/reference-codes)",
            "example": "BRL"
          },
          "acquirerTransactionId": {
            "type": "string",
            "nullable": true,
            "description": "Transaction identifier at the acquirer"
          },
          "authorizationCode": {
            "type": "string",
            "nullable": true,
            "description": "Authorization code returned by the acquirer"
          },
          "reasonCode": {
            "type": "number",
            "description": "Reason code of the result. See [ReasonCode/ReasonMessage list](https://docs.payzu.com.br/docs/cartao/transaction-status)"
          },
          "reasonMessage": {
            "type": "string",
            "nullable": true,
            "description": "Reason message of the result. See [ReasonCode/ReasonMessage list](https://docs.payzu.com.br/docs/cartao/transaction-status)"
          },
          "status": {
            "type": "integer",
            "description": "Transaction status. See [Transaction status list](https://docs.payzu.com.br/docs/cartao/transaction-status)"
          },
          "returnCode": {
            "type": "string",
            "nullable": true,
            "description": "Return code from the acquirer. See [Error Codes](https://docs.payzu.com.br/docs/cartao/error-codes) and [ABECS return codes](https://docs.payzu.com.br/docs/cartao/abecs-codes)"
          },
          "returnMessage": {
            "type": "string",
            "nullable": true,
            "description": "Return message from the acquirer"
          },
          "externalAuthentication": {
            "type": "object",
            "description": "External 3DS authentication data, when sent at creation",
            "properties": {}
          },
          "reversedAmount": {
            "type": "number",
            "nullable": true,
            "description": "Reversed amount in cents, when a reversal exists"
          },
          "reversedDate": {
            "type": "string",
            "nullable": true,
            "description": "Reversal date, when present"
          },
          "chargeId": {
            "type": "string",
            "description": "Charge identifier"
          },
          "card": {
            "$ref": "#/components/schemas/CardResponse"
          },
          "chargebacks": {
            "type": "array",
            "description": "Chargebacks linked to the charge",
            "items": {
              "$ref": "#/components/schemas/Chargeback"
            }
          }
        }
      },
      "RecurrenceRequest": {
        "type": "object",
        "description": "Recurring payment configuration. The first charge is created immediately; the following cycles are generated automatically. Requires `installments` equal to 1. See [Recurring Payments](https://docs.payzu.com.br/docs/cartao/recurrence)",
        "required": [
          "interval"
        ],
        "properties": {
          "interval": {
            "type": "string",
            "description": "Interval between charges: `Monthly` or `Annual`",
            "enum": [
              "Monthly",
              "Annual"
            ]
          },
          "endDate": {
            "type": "string",
            "description": "Recurrence end date in `YYYY-MM-DD` format. Without it, the recurrence runs indefinitely",
            "example": "2027-06-12"
          }
        }
      },
      "Recurrence": {
        "type": "object",
        "description": "State of a recurrence",
        "properties": {
          "recurrentPaymentId": {
            "type": "string",
            "description": "Recurrence identifier. Use it on the recurrence query and management endpoints"
          },
          "interval": {
            "type": "string",
            "description": "Configured interval",
            "enum": [
              "MONTHLY",
              "ANNUAL"
            ]
          },
          "status": {
            "type": "string",
            "description": "Recurrence status. See [Recurring Payments](https://docs.payzu.com.br/docs/cartao/recurrence)",
            "enum": [
              "ACTIVE",
              "INACTIVE",
              "ENDED"
            ]
          },
          "amount": {
            "type": "number",
            "description": "Amount of each cycle, in cents"
          },
          "nextRecurrency": {
            "type": "string",
            "description": "Date of the next automatic charge"
          },
          "endDate": {
            "type": "string",
            "nullable": true,
            "description": "End date, if provided at creation"
          }
        }
      },
      "Charge": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Charge identifier"
          },
          "externalId": {
            "type": "string",
            "description": "Unique identifier generated externally"
          },
          "postbackUrl": {
            "type": "string",
            "nullable": true,
            "description": "Url for notifications about the charge status"
          },
          "amount": {
            "type": "number",
            "description": "Charge amount in cents"
          },
          "paymentType": {
            "type": "string",
            "description": "Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes)",
            "example": "creditcard"
          },
          "createdAt": {
            "type": "string",
            "description": "Charge creation date"
          },
          "updatedAt": {
            "type": "string",
            "description": "Date the charge was last updated"
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerResponse"
          },
          "cart": {
            "type": "array",
            "description": "Buyer's cart",
            "items": {
              "$ref": "#/components/schemas/CartItem"
            }
          },
          "creditCardPayment": {
            "$ref": "#/components/schemas/CreditCardPaymentResponse"
          },
          "recurrence": {
            "$ref": "#/components/schemas/Recurrence",
            "description": "Present when the charge belongs to a recurrence"
          },
          "recurrenceCycle": {
            "type": "integer",
            "nullable": true,
            "description": "Cycle number of the recurrence this charge belongs to: 0 is the initial charge, 1..n are the automatically generated cycles. Present only on recurrence charges"
          }
        }
      },
      "ChargeRequest": {
        "type": "object",
        "required": [
          "amount",
          "customer",
          "paymentType",
          "cart",
          "creditCardPayment",
          "externalId"
        ],
        "properties": {
          "amount": {
            "type": "number",
            "description": "Charge amount in cents"
          },
          "customer": {
            "$ref": "#/components/schemas/CustomerRequest"
          },
          "postbackUrl": {
            "type": "string",
            "description": "Url for notifications about the charge status. See [Webhooks](https://docs.payzu.com.br/docs/cartao/webhooks)"
          },
          "paymentType": {
            "type": "string",
            "description": "Charge payment type. See [Payment types](https://docs.payzu.com.br/docs/cartao/reference-codes)",
            "enum": [
              "creditcard"
            ]
          },
          "cart": {
            "type": "array",
            "description": "Buyer's cart",
            "items": {
              "$ref": "#/components/schemas/CartItem"
            }
          },
          "creditCardPayment": {
            "type": "object",
            "description": "Settings for the payment type: credit card",
            "required": [
              "installments",
              "card",
              "authenticate"
            ],
            "properties": {
              "installments": {
                "type": "number",
                "description": "Number of installments. Must be 1 on international charges and recurrences"
              },
              "card": {
                "$ref": "#/components/schemas/CardRequest"
              },
              "currency": {
                "type": "string",
                "description": "Charge currency. In a foreign currency, `amount` is expressed in that currency's smallest unit. See [Currencies](https://docs.payzu.com.br/docs/cartao/reference-codes) and [International charges](https://docs.payzu.com.br/docs/cartao/international)",
                "default": "BRL"
              },
              "authenticate": {
                "type": "boolean",
                "description": "Defines whether the buyer will be redirected to the issuer for card authentication (3DS)"
              },
              "externalAuthentication": {
                "$ref": "#/components/schemas/ExternalAuthentication"
              },
              "fraudAnalysis": {
                "$ref": "#/components/schemas/FraudAnalysis"
              }
            }
          },
          "recurrence": {
            "$ref": "#/components/schemas/RecurrenceRequest"
          },
          "externalId": {
            "type": "string",
            "description": "Unique identifier generated externally"
          }
        }
      }
    }
  }
}