> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# dLocal - PIX

> Configure PIX via dLocal as a payment method in Gr4vy.

dLocal is a global payments platform that helps you accept local payment methods and cards across emerging markets.

PIX is Brazil's instant payment system, created by the Central Bank of Brazil, enabling real-time transfers and payments 24/7.

## Setup

Please follow the [common dLocal instructions](./dlocal) to get set up with PIX.

Next, make sure to enable PIX as a payment method on your configured account.

## Features

* **Tokenization** - Save payment methods for future use
* **Partial refunds** - Refund a portion of the captured amount
* **Refunds** - Full refund support
* **Settlement reporting** - Access to settlement reports
* **Transaction sync** - Automatic transaction status synchronization

## Supported countries

dLocal supports transactions from buyers in `BR`.

## Supported currencies

dLocal supports processing payments in `BRL`.

## Limitations

* **Capture** - Delayed capture is not supported
* **Void** - Transaction void is not supported

## Integration

For PIX, the default integration is through a redirect to a hosted payments page.

Start by creating a new transaction with the following required fields.

<CodeGroup>
  ```csharp C# theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
      transactionCreate: new TransactionCreate()
      {
          Amount = 1299,
          Currency = "BRL",
          Country = "BR",
          PaymentMethod =
              TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                  new RedirectPaymentMethodCreate()
                  {
                      Method = "pix",
                      RedirectUrl = "https://example.com/callback",
                  }
              ),
      }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "BRL"
  country := "BR"
  method := "pix"
  redirectUrl := "https://example.com/callback"

  redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
      Method: method,
      RedirectUrl: redirectUrl,
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

  transactionCreate := components.TransactionCreate{
      Amount:        amount,
      Currency:      currency,
      Country:       &country,
      PaymentMethod: &paymentMethod,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
      .transactionCreate(TransactionCreate.builder()
          .amount(1299L)
          .currency("BRL")
          .country("BR")
          .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
              .method("pix")
              .redirectUrl("https://example.com/callback")
              .build()))
          .build())
      .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
      amount: 1299,
      currency: 'BRL',
      country: 'BR',
      paymentMethod: new RedirectPaymentMethodCreate(
          method: 'pix',
          redirectUrl: 'https://example.com/callback'
      )
  );
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
      amount=1299,
      currency="BRL",
      country="BR",
      payment_method={
          "method": "pix",
          "redirect_url": "https://example.com/callback",
      }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
      amount: 1299,
      currency: "BRL",
      country: "BR",
      paymentMethod: {
          method: "pix",
          redirectUrl: "https://example.com/callback"
      }
  })
  ```
</CodeGroup>

After the transaction is created, the API response includes `payment_method.approval_url` and the status is set to `buyer_approval_pending`.

Redirect the buyer to the `approval_url` so they can complete the payment. After approval the buyer is redirected to the `redirect_url` you provided when creating the transaction. Do not rely solely on the redirect - either poll the transaction or (recommended) rely on webhooks to detect the final status (for example `capture_succeeded` or failure states).

## Recurring transactions

### Enrollment

To enroll a buyer in Pix Automático, create an initial payment with tokenization enabled and pass `dlocal-pix` connection options.

* Set `store` to `true` to save the payment method.
* Pass `connection_options.dlocal-pix.subscription` with the recurring enrollment details.

Use one of the following SDK requests:

<CodeGroup>
  ```csharp C# theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
      transactionCreate: new TransactionCreate()
      {
          Amount = 1299,
          Currency = "BRL",
          Country = "BR",
          PaymentMethod =
              TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                  new RedirectPaymentMethodCreate()
                  {
                      Method = "pix",
                      RedirectUrl = "https://example.com/callback",
                  }
              ),
          Store = true,
          ConnectionOptions = new Dictionary<string, object>()
          {
              ["dlocal-pix"] = new Dictionary<string, object>()
              {
                  ["subscription"] = new Dictionary<string, object>()
                  {
                      ["frequency"] = "MONTHLY",
                      ["amount"] = new Dictionary<string, string>()
                      {
                          ["type"] = "FIXED",
                          ["value"] = "10.00"
                      },
                      ["start_date"] = "2026-03-01",
                      ["end_date"] = "2027-03-01"
                  }
              }
          }
      }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "BRL"
  country := "BR"
  method := "pix"
  redirectUrl := "https://example.com/callback"
  store := true

  redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
      Method: method,
      RedirectUrl: redirectUrl,
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

  transactionCreate := components.TransactionCreate{
      Amount:        amount,
      Currency:      currency,
      Country:       &country,
      PaymentMethod: &paymentMethod,
      Store:         &store,
      ConnectionOptions: map[string]any{
          "dlocal-pix": map[string]any{
              "subscription": map[string]any{
                  "frequency": "MONTHLY",
                  "amount": map[string]string{
                      "type":  "FIXED",
                      "value": "10.00",
                  },
                  "start_date": "2026-03-01",
                  "end_date": "2027-03-01",
              },
          },
      },
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  Map<String, String> amountOptions = new HashMap<>();
  amountOptions.put("type", "FIXED");
  amountOptions.put("value", "10.00");

  Map<String, Object> subscriptionOptions = new HashMap<>();
  subscriptionOptions.put("frequency", "MONTHLY");
  subscriptionOptions.put("amount", amountOptions);
  subscriptionOptions.put("start_date", "2026-03-01");
  subscriptionOptions.put("end_date", "2027-03-01");

  Map<String, Object> pixOptions = new HashMap<>();
  pixOptions.put("subscription", subscriptionOptions);

  Map<String, Object> connectionOptions = new HashMap<>();
  connectionOptions.put("dlocal-pix", pixOptions);

  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
      .transactionCreate(TransactionCreate.builder()
          .amount(1299L)
          .currency("BRL")
          .country("BR")
          .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
              .method("pix")
              .redirectUrl("https://example.com/callback")
              .build()))
          .store(true)
          .connectionOptions(connectionOptions)
          .build())
      .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
      amount: 1299,
      currency: 'BRL',
      country: 'BR',
      paymentMethod: new RedirectPaymentMethodCreate(
          method: 'pix',
          redirectUrl: 'https://example.com/callback'
      ),
      store: true,
      connectionOptions: [
          'dlocal-pix' => [
              'subscription' => [
                  'frequency' => 'MONTHLY',
                  'amount' => [
                      'type' => 'FIXED',
                      'value' => '10.00'
                  ],
                  'start_date' => '2026-03-01',
                  'end_date' => '2027-03-01'
              ]
          ]
      ]
  );
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
      amount=1299,
      currency="BRL",
      country="BR",
      payment_method={
          "method": "pix",
          "redirect_url": "https://example.com/callback",
      },
      store=True,
      connection_options={
          "dlocal-pix": {
              "subscription": {
                  "frequency": "MONTHLY",
                  "amount": {
                      "type": "FIXED",
                      "value": "10.00"
                  },
                  "start_date": "2026-03-01",
                  "end_date": "2027-03-01"
              }
          }
      }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
      amount: 1299,
      currency: "BRL",
      country: "BR",
      paymentMethod: {
          method: "pix",
          redirectUrl: "https://example.com/callback"
      },
      store: true,
      connectionOptions: {
          "dlocal-pix": {
              subscription: {
                  frequency: "MONTHLY",
                  amount: {
                      type: "FIXED",
                      value: "10.00"
                  },
                  start_date: "2026-03-01",
                  end_date: "2027-03-01"
              }
          }
      }
  })
  ```
</CodeGroup>

After you create the enrollment transaction, redirect the buyer to the `approval_url` to complete the Pix Automático enrollment. Once the buyer approves it, the payment method is saved and available for subsequent recurring charges.

### Subsequent payment

After enrollment succeeds, create subsequent charges with the saved payment method ID.

* Set `payment_method.method` to `id` and pass the saved payment method ID.
* Set `payment_source` to `recurring`.
* Set `merchant_initiated` and `is_subsequent_payment` to `true`.
* Optionally set `connection_options.dlocal-pix.scheduled_date` in `YYYY-MM-DD` format.

<CodeGroup>
  ```csharp C# theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
      transactionCreate: new TransactionCreate()
      {
          Amount = 1299,
          Currency = "BRL",
          Country = "BR",
          PaymentMethod = TransactionCreatePaymentMethod.CreatePaymentMethodIdRequest(
              new PaymentMethodIdRequest()
              {
                  Method = PaymentMethodIdRequest.MethodEnum.Id,
                  Id = "f758d736-9a81-4bd0-85a9-2d3ee361b863"
              }
          ),
          IsSubsequentPayment = true,
          MerchantInitiated = true,
          PaymentSource = TransactionCreate.PaymentSourceEnum.Recurring,
          ConnectionOptions = new Dictionary<string, object>()
          {
              ["dlocal-pix"] = new Dictionary<string, string>()
              {
                  ["scheduled_date"] = "2026-03-05"
              }
          }
      }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "BRL"
  country := "BR"
  paymentSource := "recurring"

  paymentMethodIdRequest := components.PaymentMethodIdRequest{
      Method: components.PaymentMethodIdRequestMethodID,
      ID:     "f758d736-9a81-4bd0-85a9-2d3ee361b863",
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodPaymentMethodIdRequest(paymentMethodIdRequest)

  transactionCreate := components.TransactionCreate{
      Amount:              amount,
      Currency:            currency,
      Country:             &country,
      PaymentMethod:       &paymentMethod,
      IsSubsequentPayment: gr4vy.Bool(true),
      MerchantInitiated:   gr4vy.Bool(true),
      PaymentSource:       &paymentSource,
      ConnectionOptions: map[string]any{
          "dlocal-pix": map[string]string{
              "scheduled_date": "2026-03-05",
          },
      },
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
      .transactionCreate(TransactionCreate.builder()
          .amount(1299L)
          .currency("BRL")
          .country("BR")
          .paymentMethod(TransactionCreatePaymentMethod.of(PaymentMethodIdRequest.builder()
              .method(PaymentMethodIdRequest.Method.ID)
              .id("f758d736-9a81-4bd0-85a9-2d3ee361b863")
              .build()))
          .isSubsequentPayment(true)
          .merchantInitiated(true)
          .paymentSource(PaymentSource.RECURRING)
          .connectionOptions(Map.of(
              "dlocal-pix", Map.of(
                  "scheduled_date", "2026-03-05"
              )
          ))
          .build())
      .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
      amount: 1299,
      currency: 'BRL',
      country: 'BR',
      paymentMethod: new PaymentMethodIdRequest(
          method: PaymentMethodIdRequestMethod::ID,
          id: 'f758d736-9a81-4bd0-85a9-2d3ee361b863'
      ),
      isSubsequentPayment: true,
      merchantInitiated: true,
      paymentSource: PaymentSource::Recurring,
      connectionOptions: [
          'dlocal-pix' => [
              'scheduled_date' => '2026-03-05'
          ]
      ]
  );
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
      amount=1299,
      currency="BRL",
      country="BR",
      payment_method=models.PaymentMethodIdRequest(
          method=models.PaymentMethodIdRequestMethod.ID,
          id="f758d736-9a81-4bd0-85a9-2d3ee361b863"
      ),
      is_subsequent_payment=True,
      merchant_initiated=True,
      payment_source=models.PaymentSource.RECURRING,
      connection_options={
          "dlocal-pix": {
              "scheduled_date": "2026-03-05"
          }
      }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
      amount: 1299,
      currency: "BRL",
      country: "BR",
      paymentMethod: {
          method: "id",
          id: "f758d736-9a81-4bd0-85a9-2d3ee361b863"
      },
      isSubsequentPayment: true,
      merchantInitiated: true,
      paymentSource: "recurring",
      connectionOptions: {
          "dlocal-pix": {
              scheduled_date: "2026-03-05"
          }
      }
  })
  ```
</CodeGroup>

### Connection options

* `subscription.frequency` - Recurrence interval. Supported values are `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUAL`, and `ANNUAL`.
* `subscription.amount.type` - Amount model. Use `FIXED` for a fixed amount or `VARIABLE` for a variable amount.
* `subscription.amount.value` - Fixed amount in local currency. Use this when `subscription.amount.type` is `FIXED`.
* `subscription.amount.min_value` - Minimum enrollment limit in local currency. Use this when `subscription.amount.type` is `VARIABLE`.
* `subscription.start_date` - Subscription start date in `YYYY-MM-DD` format.
* `subscription.end_date` - Subscription end date in `YYYY-MM-DD` format.

For subsequent recurring charges, you can pass `connection_options.dlocal-pix.scheduled_date` in `YYYY-MM-DD` format. If you omit it, dLocal defaults to 2 days in the future.

## Sandbox testing

In production, Gr4vy passes `merchant_reference` to dLocal as the payment description.

In sandbox, Gr4vy sends `100:approved` as the payment description so dLocal can return an approved transaction.