Pix Open Finance

Open Finance is the Brazilian open banking system. Open Finance enables faster and secure checkout experiences for shoppers when paying with Pix. During the initial payment, the shopper grants consent to Adyen to act as a payment initiator on their behalf. This is called an enrollment, and removes the need for the shopper to complete authentication for each payment on their banking app when they are using the same device.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

How it works

Pix Open Finance works with enrollments. An enrollment is a record of consent that the shopper lets Adyen act as a payment initiator on behalf of the shopper. Instead of storing the payment details of a shopper, Adyen receives a confirmation from Open Finance Brazil.

When a shopper proceeds to check out with Pix Open Finance, you check if the shopper and their device are already enrolled. You must implement your own logic to check whether the shopper is already enrolled.

• If the shopper is enrolled, you proceed to the payment, and offer a faster checkout experience by using their enrollment data.
• If the shopper is not enrolled, you make a request to enroll the shopper and their device. After they are enrolled, you proceed to the payment.

Enrollment

1. You make a zero-value authorization request to the /payments endpoint to get the shopper's consent. In the response, you get a link for an Adyen-hosted payment page.
2. You redirect the shopper to the Adyen-hosted payment page, where they select their bank from a list provided by Open Finance Brazil.
3. The shopper is redirected to their bank's website or app to authorizing the zero-value transaction.
4. The shopper is redirected to the Adyen-hosted payment page, and completes the enrollment by authenticating with their biometrics.
5. After the shopper completes their enrollment, you get the confirmation in a Recurring tokens lifecycle events webhook.
6. The shopper is redirected to your website or app, and you make a /payments/details request to check the result.

Subsequent payments

After an enrollment is created, subsequent payments where the shopper is using the same device, you can make payments using only biometric authentication. This removes the need for the shopper to be redirected to their bank's website or app to authorize the transaction.

1. You make a /payments request to get the link for an Adyen-hosted payment page.
2. You redirect the shopper to the Adyen-hosted payment page.
3. On the payment page, the shopper authenticates using biometrics.
4. After successful authentication, the payment is authorized, you make a /payments/details request to check the result.

Create an enrollment

To enroll a shopper and their device with Open Finance so that Adyen can act as a payment initiator:

1. Make a POST /payments request. In your request, include:

• Standard tokenization parameters:

  Parameters	Required	Description
  paymentMethod.type		paybybank_pix
  paymentMethod.subtype		redirect
  returnUrl		The URL to which your shopper should be redirected to after they complete the enrollement on the Adyen-hosted payment page.
  reference		The reference to uniquely identify a payment.
  shopperReference		Your unique identifier for the shopper. Minimum length: three characters. This field is case-sensitive. Do not include personally identifiable information (PII), such as name or email address.
  shopperInteraction		Set to Ecommerce.
  recurringProcessingModel		Set to CardOnFile.
  storePaymentMethod		Set to true to store the shopper's payment details for future recurring payments.
  amount		Set to 0 to complete a zero-value authorization.

• Pix-specific parameters:

  Parameters	Required	Description
  shopperName		The first and last name of the shopper.
  socialSecurityNumber		The shopper's CPF or CNPJ number. This will be shown to the shopper on the Pix payment form.

  The response contains the following data:

  • resultCode : RedirectShopper
  • action: contains the information that you must use to redirect the shopper.

2. From the response, use the action field that contains method, url and paymentMethodType to redirect the shopper to the Adyen-hosted payment page.
   On the Adyen-hosted payment page:

   1. The shopper selects their bank, and get redirected to their bank's website or app.
   2. The shopper authorizes the transaction in their bank's environment,
   3. The shopper is redirected to the Adyen-hosted payment page to complete authentication with biometrics.
   4. When the enrollment is completed, the shopper is redirected to your website.

3. After the shopper is redirected back to your website, check the payment result by making a POST /payments/details, specifying:

   • details: object that contains the URL-decoded redirectResult returned when the shopper was redirected back to your site.

4. In the response, note the following:

   • resultCode : use this to present the result to your shopper.

   • pspReference: our unique identifier for the transaction.

5. Wait for the following webhooks to get:

   • The outcome of your request.
   • storedPaymentMethodId: if the payment was successfully authorized, you receive the unique identifier for the shopper's enrollment in this field. You need this ID when you:
     • Make a payment.
     • Cancel an enrollment.

   Webhook	Description
   AUTHORISATION	Contains the success field, that informs you whether the zero-value authorization transaction is authorized.
   recurring.token.created	Contains the shopperReference, and the storedPaymentMethodId.

   When you receive an AUTHORISATION webhook with success: true, you can proceed to make a payment with the enrollment details.

Make a payment with an enrollment

When you enroll a shopper, Adyen stores the enrollment confirmation, and the device ID linked to the enrollment. When you make a /payments request with an amount greater than 0, we check whether an enrollment exists for the device your shopper is using, and trigger the Open Finance payment flow.

To make a payment:

1. Make a POST /payments request, including:

• Standard tokenization parameters:

  Parameters	Required	Description
  paymentMethod.type		paybybank_pix
  paymentMethod.subtype		redirect
  paymentMethod.storedPaymentMethodId		The unique identifier for the shopper's enrollment that you received in the recurring.token.created webhook. Alternatively, you can also get the enrollment identifier by making a /paymentMethods request including merchantAccount, and shopperReference. In the response, the id in the storedPaymentMethods array is the enrollment identifier.
  reference		The reference to uniquely identify a payment.
  returnUrl		The URL to which your shopper should be redirected to after they complete the enrollement on the Adyen-hosted payment page.
  amount		The currency and value of the recurring payment, in minor units. The value must be greater than 0.
  shopperReference		Your unique identifier for the shopper. Must be the same one you included with the request to enroll the shopper.
  shopperInteraction		Set to ContAuth.
  recurringProcessingModel		Set to CardOnFile.

• Pix-specific parameters:

  Parameters	Required	Description
  shopperName		The first and last name of the shopper.
  socialSecurityNumber		The shopper's CPF or CNPJ number. This will be shown to the shopper on the Pix payment form.

  The response contains the following data:

  • resultCode : RedirectShopper
  • action: contains the information that you must use to redirect the shopper.

2. From the response, use the action field that contains method, url and paymentMethodType to redirect the shopper to the Adyen-hosted payment page.
   When making a payment for an enrolled shopper, the shopper has to complete authentication using their biometrics, but they are not redirected to their bank environment. After the payment is successfully authenticated, the shopper is redirected to your website.

3. After the shopper is redirected back to your website, check the payment result by making a POST /payments/details, specifying:

   • details: object that contains the URL-decoded redirectResult returned when the shopper was redirected back to your site.

4. In the response, note the following:

   • resultCode: the outcome of the request.

   • pspReference: our unique identifier for the transaction.

5. Depending on the resultCode you get, inform the shopper.

   resultCode	Action
   Received	The payment will be completed asynchronously. This is an intermediate result code that indicates the payment has not reached a final state yet. You receive the payment outcome in an AUTHORISATION webhook.
   UnmatchedDevice	The shopper is using a device that does not match the one they used for the enrollment. Inform the shopper about the error.

Cancel an enrollment

If a shopper wants to revoke their consent and cancel their enrollment, delete the stored details with a DELETE /storedPaymentMethods/{storedPaymentMethodId} request.

When stored details are deleted, you receive a recurring.token.disabled webhook.

See also

• Pix API only
• Tokenization