Skip to main content
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 to get set up with Nuvei. After setting up your Nuvei account, make sure PSE is enabled as a payment method on your account.

Capabilities

Supported countries

Supported currencies

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:
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 4000,
    Currency = "COP",
    Country = "CO",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "pse",
          Country = "CO",
          Currency = "COP",
          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"
      }
    }
  }
);
amount := int64(4000)
currency := "COP"
country := "CO"
method := components.RedirectPaymentMethodCreateMethodPse
redirectUrl := "https://example.com/callback"
firstName := "John"
lastName := "Doe"
emailAddress := "john.doe@example.com"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
  Method: method,
  Country: country,
  Currency: currency,
  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, nil)
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(RedirectPaymentMethodCreateMethod.PSE)
      .country("CO")
      .currency("COP")
      .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);
$transactionCreate = new TransactionCreate(
  amount: 4000,
  currency: 'COP',
  country: 'CO',
  paymentMethod: new RedirectPaymentMethodCreate(
    method: 'pse',
    country: 'CO',
    currency: 'COP',
    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;
transaction: models.Transaction = client.transactions.create(
  amount=4000,
  currency="COP",
  country="CO",
  payment_method={
    "method": "pse",
    "country": "CO",
    "currency": "COP",
    "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"
    }
  }
)
const transaction = await gr4vy.transactions.create({
  amount: 4000,
  currency: "COP",
  country: "CO",
  paymentMethod: {
    method: "pse",
    country: "CO",
    currency: "COP",
    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"
    }
  }
})
After the transaction is created, the API response includes payment_method.approval_url and the buyer_approval_pending status.
{
  "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 on how to test PSE.