Getting started

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.
• Credentials client_id and client_secret, used to obtain the access token.

Get the token

Call 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.

Create the first charge

Create a charge via POST /charges. The required fields are amount, customer, paymentType, cart, creditCardPayment and externalId. Full schema in the reference.

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.

With authenticate: false the buyer is not redirected to the issuer for authentication. For authenticated flows, see 3D Secure.

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:

If creditCardPayment.status returned 2 (PaymentConfirmed), your first charge is confirmed. The full list of codes is in Transaction status.

Test scenarios and configure webhooks

To simulate approvals, denials and timeouts in the sandbox, use the 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.