# Getting started (/en/docs/cartao/getting-started)

<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints" title="API reference" />

  <QuickLink href="/docs/cartao/authentication" title="Authentication" />

  <QuickLink href="/docs/cartao/test-cards" title="Test cards" />

  <QuickLink href="/docs/cartao/transaction-status" title="Transaction status" />

  <QuickLink href="/docs/cartao/webhooks" title="Webhooks" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Certificate + credentials&#x22;] --> B[&#x22;Get the token&#x22;]
  B --> C[&#x22;Create a charge&#x22;]
  C --> D[&#x22;Read the response&#x22;]
  D --> E[&#x22;Test scenarios&#x22;]

  click B &#x22;/docs/cartao/endpoints/token/post_token&#x22; &#x22;POST /token&#x22;
  click C &#x22;/docs/cartao/endpoints/charges/post_charges&#x22; &#x22;POST /charges&#x22;
  click D &#x22;/docs/cartao/transaction-status&#x22; &#x22;Transaction status&#x22;
  click E &#x22;/docs/cartao/test-cards&#x22; &#x22;Test cards&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style E fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

In this guide we use the **sandbox** (`https://api.sandbox.payzu.io/v1`). In production the base URL is `https://api.payzu.io/v1`.

<Steps>
  <Step>
    ### Prerequisites [#prerequisites]

    Before your first call you need two items, both provided by the PayZu team:

    * **Client mTLS certificate** (`cliente.crt`, `cliente.key` and `ca.pem`). Install the certificate and configure your system to use it on **every** API call, always over HTTPS. Details in [Authentication](/docs/cartao/authentication).
    * **Credentials** `client_id` and `client_secret`, used to obtain the access token.
  </Step>

  <Step>
    ### Get the token [#get-the-token]

    Call [`POST /token`](/docs/cartao/endpoints/token/post_token) using **Basic Auth** with `client_id` and `client_secret`, along with the mTLS certificate, and use the returned `access_token` as the Bearer token on the next calls. For the full request and response example, see [Authentication](/docs/cartao/authentication).
  </Step>

  <Step>
    ### Create the first charge [#create-the-first-charge]

    Create a charge via [`POST /charges`](/docs/cartao/endpoints/charges/post_charges). The required fields are `amount`, `customer`, `paymentType`, `cart`, `creditCardPayment` and `externalId`. Full schema in the reference.

    ```bash
    curl --request POST \
      --url https://api.sandbox.payzu.io/v1/charges \
      --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      --header 'Content-Type: application/json' \
      --cert cliente.crt \
      --key cliente.key \
      --cacert ca.pem \
      --data '{
        "amount": 10000,
        "externalId": "order-2026-0001",
        "paymentType": "creditcard",
        "customer": {
          "name": "John Smith"
        },
        "cart": [
          {
            "name": "Monthly plan",
            "quantity": 1,
            "sku": "PLAN-01",
            "unitPrice": 10000
          }
        ],
        "creditCardPayment": {
          "installments": 1,
          "authenticate": false,
          "card": {
            "number": "4111111111111111",
            "holder": "JOAO DA SILVA",
            "expiration": "12/2030",
            "cvv": "123"
          }
        }
      }'
    ```

    In production, switch the base URL to `https://api.payzu.io/v1`.

    <Callout type="info">
      Monetary values (`amount`, `unitPrice`) are always in **cents**. `10000` equals R$ 100.00.
    </Callout>

    With `authenticate: false` the buyer is not redirected to the issuer for authentication. For authenticated flows, see [3D Secure](/docs/cartao/three-d-secure).
  </Step>

  <Step>
    ### Read the response [#read-the-response]

    The response contains the charge `id`, the `externalId` you provided and the `creditCardPayment` object with `status`, `reasonCode` and `reasonMessage`. The main statuses:

    | Code | Status           | Meaning                                                              |
    | ---- | ---------------- | -------------------------------------------------------------------- |
    | 1    | Authorized       | Approved by the issuer, eligible for capture, but not yet completed. |
    | 2    | PaymentConfirmed | Payment confirmed and finalized.                                     |
    | 3    | Denied           | Payment denied by an authorizer.                                     |

    If `creditCardPayment.status` returned `2` (PaymentConfirmed), your first charge is confirmed. The full list of codes is in [Transaction status](/docs/cartao/transaction-status).
  </Step>

  <Step>
    ### Test scenarios and configure webhooks [#test-scenarios-and-configure-webhooks]

    To simulate approvals, denials and timeouts in the sandbox, use the [test cards](/docs/cartao/test-cards): the last digits of the card number determine the transaction outcome.

    To receive notifications about the charge status without polling the API, provide a `postbackUrl` when creating the charge. Payload structure and validation in [Webhooks](/docs/cartao/webhooks).
  </Step>
</Steps>

## Next steps [#next-steps]

<QuickLinks>
  <QuickLink href="/docs/cartao/three-d-secure" title="3D Secure" />

  <QuickLink href="/docs/cartao/antifraud" title="Antifraud" />

  <QuickLink href="/docs/cartao/recurrence" title="Recurrence" />

  <QuickLink href="/docs/cartao/international" title="International charges" />
</QuickLinks>