Authentication

Authentication in the Card API happens in two layers that work together:

1. Mutual TLS (mTLS): every connection to the API uses a client certificate issued by PayZu, guaranteeing the identity of both the server and the client during communication.
2. JWT token: over the mTLS connection, you obtain an access_token via POST /token and send it in the Authorization: Bearer header on all other routes.

Environments

Mutual TLS

Before making any call, install the client certificate provided by the PayZu team and configure your system to use it in all API calls, always over HTTPS.

In curl, the certificate goes in through the --cert (client certificate), --key (private key), and --cacert (certificate authority chain) flags:

curl --request GET \
     --url https://api.sandbox.payzu.io/v1/charges \
     --header 'accept: application/json' \
     --cert cliente.crt \
     --key cliente.key \
     --cacert ca.pem

Get the token

The POST /token route returns a JWT token used to authenticate the other routes. It uses Basic Auth (your client_id as the username and client_secret as the password), always over the mTLS connection, and receives the grant_type client_credentials in the body:

curl --request POST \
     --url https://api.sandbox.payzu.io/v1/token \
     --user "$CLIENT_ID:$CLIENT_SECRET" \
     --header 'content-type: application/json' \
     --cert cliente.crt \
     --key cliente.key \
     --cacert ca.pem \
     --data '{ "grant_type": "client_credentials" }'

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

The response carries the token and its expiration time:

{
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0
}

Authenticated calls

After obtaining the token, every API route receives the Authorization: Bearer header, always over the same mTLS configuration:

curl --request GET \
     --url https://api.sandbox.payzu.io/v1/charges \
     --header 'accept: application/json' \
     --header "Authorization: Bearer $ACCESS_TOKEN" \
     --cert cliente.crt \
     --key cliente.key \
     --cacert ca.pem

Next steps