> ## 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.

# Nuvei - PSE

> Configure PSE via Nuvei as a payment method in Gr4vy.

Nuvei is a global payment provider that provides comprehensive payment processing solutions across multiple payment methods and regions.

PSE is a popular online payment method in Colombia that allows customers to pay directly from their bank account using the Colombian banking system. It is widely used for e-commerce transactions in Colombia.

## Setup

Please follow the [common Nuvei instructions](./nuvei) to get set up with Nuvei.

After setting up your Nuvei account, make sure PSE is enabled as a payment method on your account.

## Features

Nuvei PSE payments support the following features:

* **Transaction synchronization** - Keep payment statuses synchronized with Nuvei

## Supported countries

Nuvei supports transactions from buyers in `CO`.

## Supported currencies

Nuvei supports processing payments in `COP` and `USD`.

## Limitations

The following features are not supported by this connector:

* **Refunds** - Cannot refund PSE transactions
* **Delayed capture** - Authorization and capture must happen together
* **Partial capture** - Cannot capture a portion of the authorized amount
* **Void** - Cannot cancel transactions once initiated
* **Payment method tokenization** - Cannot store payment methods for recurring transactions
* **Zero auth** - Zero-dollar verification transactions are not supported
* **Settlement reporting** - Settlement reporting is not available

## Integration

For PSE, the default integration for Nuvei is through a redirect to a hosted payments page.

The PSE connection via Nuvei requires a few fields in the transaction request:

* `buyer.billing_details.first_name` and `buyer.billing_details.last_name` - Customer name
* `buyer.billing_details.email_address` - Customer's email
* `connection_options.nuvei-pse.userType` - Customer type ("N" for personal, "J" for a legal entity)
* `connection_options.nuvei-pse.userFisNumber` - Customer's document type
* `connection_options.nuvei-pse.fiscalNumber` - Customer's document number
* `connection_options.nuvei-pse.bankCode` - The bank code of the selected bank

Start by creating a new transaction with the required fields:

<CodeGroup>
  ```csharp C# theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
      Amount = 4000,
      Currency = "COP",
      Country = "CO",
      PaymentMethod =
        TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
          new RedirectPaymentMethodCreate()
          {
            Method = "pse",
            RedirectUrl = "https://example.com/callback",
          }
        ),
      Buyer = new TransactionCreateBuyer()
      {
        BillingDetails = new BillingDetails()
        {
          FirstName = "John",
          LastName = "Doe",
          EmailAddress = "john.doe@example.com"
        }
      },
      ConnectionOptions = new Dictionary<string, object>()
      {
        ["nuvei-pse"] = new Dictionary<string, string>()
        {
          ["userType"] = "N",
          ["userFisNumber"] = "CC",
          ["fiscalNumber"] = "1148217216",
          ["bankCode"] = "1022"
        }
      }
    }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(4000)
  currency := "COP"
  country := "CO"
  method := "pse"
  redirectUrl := "https://example.com/callback"
  firstName := "John"
  lastName := "Doe"
  emailAddress := "john.doe@example.com"

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

  transactionCreate := components.TransactionCreate{
    Amount:        amount,
    Currency:      currency,
    Country:       &country,
    PaymentMethod: &paymentMethod,
    Buyer: &components.TransactionCreateBuyer{
      BillingDetails: &components.BillingDetails{
        FirstName:    &firstName,
        LastName:     &lastName,
        EmailAddress: &emailAddress,
      },
    },
    ConnectionOptions: map[string]any{
      "nuvei-pse": map[string]string{
        "userType":      "N",
        "userFisNumber": "CC",
        "fiscalNumber":  "1148217216",
        "bankCode":      "1022",
      },
    },
  }

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

  ```java Java theme={"system"}
  Map<String, String> pseOptions = new HashMap<>();
  pseOptions.put("userType", "N");
  pseOptions.put("userFisNumber", "CC");
  pseOptions.put("fiscalNumber", "1148217216");
  pseOptions.put("bankCode", "1022");

  Map<String, Object> connectionOptions = new HashMap<>();
  connectionOptions.put("nuvei-pse", pseOptions);

  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
      .amount(4000L)
      .currency("COP")
      .country("CO")
      .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
        .method("pse")
        .redirectUrl("https://example.com/callback")
        .build()))
      .buyer(TransactionCreateBuyer.builder()
        .billingDetails(BillingDetails.builder()
          .firstName("John")
          .lastName("Doe")
          .emailAddress("john.doe@example.com")
          .build())
        .build())
      .connectionOptions(connectionOptions)
      .build())
    .call();

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

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
    amount: 4000,
    currency: 'COP',
    country: 'CO',
    paymentMethod: new RedirectPaymentMethodCreate(
      method: 'pse',
      redirectUrl: 'https://example.com/callback'
    ),
    buyer: new TransactionCreateBuyer(
      billingDetails: new BillingDetails(
        firstName: 'John',
        lastName: 'Doe',
        emailAddress: 'john.doe@example.com'
      )
    ),
    connectionOptions: [
      'nuvei-pse' => [
        'userType' => 'N',
        'userFisNumber' => 'CC',
        'fiscalNumber' => '1148217216',
        'bankCode' => '1022'
      ]
    ]
  );
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
    amount=4000,
    currency="COP",
    country="CO",
    payment_method={
      "method": "pse",
      "redirect_url": "https://example.com/callback",
    },
    buyer={
      "billing_details": {
        "first_name": "John",
        "last_name": "Doe",
        "email_address": "john.doe@example.com"
      }
    },
    connection_options={
      "nuvei-pse": {
        "userType": "N",
        "userFisNumber": "CC",
        "fiscalNumber": "1148217216",
        "bankCode": "1022"
      }
    }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
    amount: 4000,
    currency: "COP",
    country: "CO",
    paymentMethod: {
      method: "pse",
      redirectUrl: "https://example.com/callback"
    },
    buyer: {
      billingDetails: {
        firstName: "John",
        lastName: "Doe",
        emailAddress: "john.doe@example.com"
      }
    },
    connectionOptions: {
      "nuvei-pse": {
        userType: "N",
        userFisNumber: "CC",
        fiscalNumber: "1148217216",
        bankCode: "1022"
      }
    }
  })
  ```
</CodeGroup>

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

```json theme={"system"}
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.sandbox.spider.gr4vy.app/connectors/nuvei/apm.html?token=..."
  },
  "method": "pse"
}
```

Redirect the buyer to the `approval_url` so they can complete authentication and approve 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).

## Testing

It is recommended to use `bankCode` 1022 for testing. Nuvei has [instructions](https://docs.nuvei.com/documentation/latin-america-guides/pse/) on how to test PSE.