Skip to main content

Authentication

Ecommerce Wallet#

Welcome to the authentication flow documentation for the PicPay Wallet. In this page, we 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. Enable Ecommerce Wallet;
  2. Generate the credentials in the Merchant Panel.
  3. Make an authorization request to obtain an access token and authenticate your requests.
  4. Use the access token as a Bearer Token in API calls for authentication.

Enabling Ecommerce Wallet#

To obtain your credentials, you must have the Ecommerce Wallet enabled. If it is not yet active, follow these steps:

  1. Log in to the Merchant Panel;
  2. Go to the Integrations section in the sidebar menu;
  3. Click the Enable button under PicPay Ecommerce Wallet.
Attention!

If you already have the Ecommerce Wallet enabled, move on to the next step.

Obtaining the Credentials#

PicPay Wallet – Ecommerce#

This credential type is used in integrations that connect directly to the PicPay API. It is composed of a client_id, client_secret, and x-seller-token. The client_id is a unique identifier for the client, the client_secret is a secret key that must be handled with care to prevent unauthorized access, and the x-seller-token is the token sent by Ecommerce Carteira when making requests to the client (webhook/callback). Follow the steps below to get your credentials:

  1. Log in to the Merchant Panel;
  2. Navigate to Integrations;
  3. Locate PicPay Wallet – Ecommerce;
  4. Click "Generate credentials";
  5. Securely store the displayed client_id, client_secret, and x-seller-token.
Important!

This is the only time the client_secret will be displayed. Store these credentials securely before closing the screen. Later, you can retrieve the client_id for identification purposes, but not the client_secret.

Attention!

If you already have a credential for the selected integration and generate a new one, the previous credential will be revoked after 7 days.

PicPay Wallet – Ecommerce Plugins and Platforms#

This credential is used in indirect integrations via plugins and marketplaces. The credentials consist of an x-picpay-token and an x-seller-token. The x-picpay-token is the token sent by the customer to the Ecommerce Wallet when making requests. Follow the steps below to obtain your credentials:

  1. Access the Merchant Panel and log in;
  2. Navigate to the Integrations section in the side menu;;
  3. Locate PicPay Wallet – Ecommerce Plugins and Platforms;
  4. Click "Generate credentials";
  5. Store the x-picpay-token and x-seller-token securely.
Information

With Ecommerce Wallet enabled and the credentials generated, the PicPay Wallet should appear like this:

img Image 1 - Example of the PicPay Wallet

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 Ecommerce Carteira 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 Ecommerce Wallet 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.