Skip to main content

Authentication

OAuth 2.0 Version#

Welcome to the PicPay Wallet 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. The OAuth 2.0 protocol provides a secure way to grant access to protected resources on behalf of a client. For more information about OAuth 2.0, refer to RFC 6749.

Authorization Flow with Grant Type client_credentials#

The client_credentials grant type is a variant of the OAuth 2.0 flow. It has been 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, refer to 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 in the Merchant Panel.
  2. Make an 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 prevent unauthorized access. Follow the steps below to obtain your credentials:

  1. Access the Merchant Panel and log in;
  2. Navigate to the E-commerce Integration section in the side menu;
  3. Find the PicPay Wallet integration in the V2 Credentials tab;
  4. Click the "Generate Token" button
  5. Securely store the client_id and client_secret displayed on the screen.
Warning!

This is the only moment 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 generated credential for the selected integration and you generate a new one, the previous credential for this integration will be revoked after 7 days.

Obtaining the Access Token#

After obtaining your credentials, you can request an access token to authenticate your requests to our API. Simply make a request to our authorization server by passing the credentials acquired in the previous step.

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

Here is an example of an access token request:

curl -X 'POST' \
'https://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.

SERVER TO SERVER!

This request must be made mandatorily from a backend system to our system. This approach prevents the exposure of authentication credentials to the end user.

EXPIRATION TIME

The access tokens obtained through this flow are valid for only 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 for authentication and authorization to access 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 process of obtaining the access token, a simultaneous request from the same client can result in the creation of duplicate tokens. Likewise, simultaneous token renewals can also lead to concurrency issues.

To properly handle concurrency, we recommend following the best practices cited by 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 efficient token storage and management strategies to avoid conflicts during the obtaining and renewing processes.
  • Use appropriate caching mechanisms to minimize token requests.

Remember, it is the client's responsibility to ensure the proper 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 the operations performed with our API.

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

Previous Versions#

Before OAuth 2.0, PicPay provided two integration keys: x-picpay-token and x-seller-token.

To access our previous Authentication model (x-picpay-token):

  1. Access the Merchant Panel and log in;
  2. Navigate to the E-commerce Integration section in the side menu;
  3. Click the "V1 Credentials" button in the PicPay Wallet integration;
  4. Use the x-picpay-token for your requests.

Attention: this version will be discontinued according to the migration to the OAuth 2.0 version.