Skip to main content

Authentication

Welcome to the documentation for the authentication flow of the PicPay Payment Link API. 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's 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, please refer to RFC 6749.

Authorization Flow with the client_credentials Grant Type​

The client_credentials grant type is a variant of the OAuth 2.0 flow. It was chosen as the authorization method to protect 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 protected services, you need to obtain an access token by following these steps:

  1. Generate the credentials on the Seller Panel.
  2. Make 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​

The credentials consist 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 should be handled carefully to avoid unauthorized access. Follow the steps below to obtain your credentials:

  1. Access the Seller Panel and log in;
  2. Navigate to the Integrations section in the sidebar menu;
  3. Click the "Generate Token" button for the Payment Link integration;
  4. Safeguard the client_id and client_secret displayed on the screen.
Warning!

This is the only time that PicPay will display the client_secret field. Therefore, you should note these credentials in a secure place before closing the screen with the information. Subsequently, you can view these credentials in the same tab, but only the client_id field will be shown for credential identification purposes.

Attention!

If a credential already exists 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, you need to make a request to our authorization server passing the credentials acquired in the previous step.

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

Here is an example of the Access Token request:

curl -L 'https://api.picpay.com/oauth2/token' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "grant_type": "client_credentials",
  "client_id": "xxxxxx-xxxx-xxx-xxxx-xxxx",
  "client_secret": "xxxxxxxx"
  }'

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

Server-to-Server!

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

Expiration Time

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

Concurrency​

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

RFC 6749 addresses some relevant aspects regarding concurrency. It highlights that, during the acquisition of the access token, a simultaneous request from the same client can result in the creation of duplicate tokens. Similarly, the simultaneous renewal of tokens can also lead to concurrency issues.

To adequately handle concurrency, we recommend following the best practices mentioned by RFC 6749. Additionally, 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 efficient strategies for token storage and management that avoid conflicts during the token acquisition and renewal process.
  • Use appropriate caching mechanisms to minimize token requests.

Remember, it is the client’s responsibility to ensure the proper implementation of concurrency control mechanisms while using the OAuth 2.0 flow. By following these guidelines, you will help maintain the consistency, security, and integrity of the operations carried out on our API.

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