Skip to main content

Authentication

Welcome to the PicPay Checkout API authentication flow documentation. On this page, we will explain how to authenticate and access our services using the OAuth 2.0 authentication flow with the client_credentials grant type.

OAuth 2.0​

Our API authentication is based on the OAuth 2.0 protocol. This protocol provides a secure way to grant access to protected resources on behalf of a client. For more information about OAuth 2.0, see RFC 6749.

Authorization Flow with Grant Type client_credentials​

The client_credentials grant type is a variant of the OAuth 2.0 flow. It was chosen as the authorization method to secure our API. This grant type is ideal for scenarios where authentication occurs between systems, without involving end users. To understand more about the client_credentials grant type, see the corresponding section in RFC 6749.

Steps​

To access our secured services, you must obtain an access token by following the following steps:

  1. Generate credentials in the PicPay Panel.
  2. Perform the authorization request to obtain an access token and authenticate your requests.
  3. Use the access token as a Bearer Token in API calls for authentication.

Obtaining Credentials​

Credentials are composed of a client_id and a client_secret. The client_id is a unique identifier for the client and the client_secret is a secret key that must be handled carefully to prevent unauthorized access. Follow the steps below to obtain your credentials:

  1. Access the PicPay Merchant Panel and log in;
  2. Navigate to the Integrações section in the side menu;
  3. Click on the "Gerar Token" button in the Checkout integration;
  4. Safely store the client_id and client_secret that appear on the screen.
CAREFUL!

This is the only time PicPay will display the client_secret field. Therefore, it is important to write down these credentials in a safe place before closing the screen with the information. Later, you can consult these credentials in the same tab, however, only the client_id field will be displayed for credential identification purposes.

ATTENTION!

If there is already a credential generated for the selected integration and you generate a new one, the previous credential for this integration will be revoked after a period of 7 days.

Obtaining the Access Token​

After obtaining your credentials, you can request an access token to authenticate your requests to our API. To do this, simply make a request to our authorization server using the credentials acquired in the previous step.

  • Authorization Endpoint: https://checkout-api.picpay.com/oauth2/token
  • Request Parameters:
  • grant_type: Defines the authorization grant flow. It will always have the value client_credentials;
  • client_id e client_secret: Obtained in the previous step.

Below is an example of the Access Token request:

curl -X 'POST' \
'https://checkout-api.picpay.com/oauth2/token' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "grant_type": "client_credentials",
    "client_id": "66b64c55-6ab9-4894-b2b0-4772472f4f72",
    "client_secret": "n9CmYbIavNTadlYFCxBVbF2345ROPgzM4"
}'

For more details on the Access Token request, see the Auth section of our API Reference.

FROM SERVER TO SERVER!

This request must be made from a backend system for our system. This approach avoids exposing authentication credentials to the end client.

EXPIRATION TIME

Access tokens obtained through this flow are only valid for 5 minutes. After this period, it will be necessary to generate a new token, with the same credentials, to continue using the API.

Concurrency​

When using the OAuth 2.0 flow to authenticate and authorize access to our API, it is important to consider challenges related to concurrency during the process of obtaining and renewing access tokens.

RFC 6749 addresses some relevant aspects in relation to concurrency . It highlights that, when obtaining the access token, a simultaneous request from the same client can result in the creation of duplicate tokens. Likewise, the simultaneous renewal of tokens can also lead to competition issues.

To properly deal with concurrency, we recommend following the best practices cited in RFC 6749. Additionally, it is important to consider the following guidelines:

  • Use concurrency control mechanisms in your system to prevent multiple requests from creating or renewing the same access token simultaneously.
  • Implement token storage and management strategies that are efficient and avoid conflicts during the acquisition and renewal process.
  • Use appropriate caching mechanisms to minimize token requests.

Please note that it is the customer's responsibility to ensure adequate implementation of concurrency control mechanisms when using the OAuth 2.0 flow. By following these guidelines, you will help maintain the consistency, security, and integrity of operations performed on our API.

If you have any additional questions or need technical support, our team is ready to help. Contact us through the channels available on the Support Portal.