🇨🇴 PSE

Overview

PSE (Pagos Seguros en Línea) is Colombia’s national online payment gateway that allows users to make real-time bank account debits directly to merchants.
Operated by ACH Colombia, it is the most popular A2A payment method in the country for e-commerce and service payments.

Through Orkestra, you can create a PSE payment by specifying PSE as the payment method in the order transaction.

📝 Minimum Required Fields for PSE

When creating an Order for PSE, the following fields are mandatory:

Field	Type	Description
charges[].customer.firstName	String	Customer’s first name.
charges[].customer.lastName	String	Customer’s last name.
charges[].customer.phoneNumber	String	Customer’s phone number (international format preferred).
charges[].customer.emailAddress	String	Customer’s email address.
charges[].customer.documentType	Enum	Document type: CC (Cédula de Ciudadanía), NIT(Número de Identificación Tributaria), TI(Tarjeta de Identificación), or CE(Cedula de Extranjeria).
charges[].customer.document	String	Valid document number matching the document type.
charges[].transactions[].paymentMethod	Enum	Must be set to PSE.

⚡ Optional PSE-specific Fields

You can enhance the payment experience with the following optional field:

Field	Type	Description
charges[].customer.bankAccount.bankCode	String	Bank code identifying the customer’s bank. If omitted, the customer will choose manually from the list.

📦 Example: PSE Order Request

json

{
  "merchantOrderId": "b95e8d4c-8920-4cdd-805e-d4b9c21b619a",  
  "softDescriptor": "Piano Strings",  
  "amount": 150000,
  "currency": "COP",
  "charges": [
    {
      "customer": {
        "firstName": "Frédéric",  
        "lastName": "Chopin",  
        "phoneNumber": "[phone]",
        "emailAddress": "[email protected]",
        "documentType": "CC",
        "document": "1020304050",
        "bankAccount": {
          "bankCode": "051"
        }
      },
      "transactions": [
        {
          "paymentMethod": "PSE"
        }
      ]
    }
  ]
}

🔁 Payment Flow Overview

• You create an order with the payment method set to PSE.
• Orkestra initiates the PSE gateway session.
• The customer is redirected to their online banking environment to complete the payment.
• Payment status is updated and can be tracked via API or Webhooks.

📦 Example: PSE Order response

json

{
  "id": 10123,
  "merchantOrderId": "b95e8d4c-8920-4cdd-805e-d4b9c21b619a",
  "softDescriptor": "Music Sheets",
  "amount": 150000,
  "allowsThirdPartyPayments": false,
  "currency": "COP",
  "status": "PENDING",
  "charges": [
    {
      "id": 10123,
      "amount": 150000,
      "status": "PENDING",
      "customer": {
        "firstName": "Frédéric",
        "lastName": "Chopin",
        "phoneNumber": "[phone]",
        "emailAddress": "[email protected]",
        "documentType": "CC",
        "document": "1020304050",
        "bankAccount": {
          "bankCode": "051"
        }
      },
      "transactions": [
        {
          "id": 10123,
          "amount": 150000,
          "paymentMethod": "PSE",
          "status": "PENDING",
          "transactionPageUrl": "https://paywall.orkestrapay.io/payment/abcd1234-5678-efgh-9101-ijklmnopqrst"
        }
      ]
    }
  ]
}

🛡️ Relevant Fields in the Response

Field	Type	Description
charges[].transactions[].transactionPageUrl	String (URL)	Hosted payment page URL (optional use — iframe or redirect).
status	Enum	Order status: PENDING, FAILED.

✅ Summary

To integrate PSE:

• Provide full customer contact and document information.
• Set paymentMethod to PSE.
• Optionally, pre-fill the customer’s bank code to streamline the experience.
• Redirect the customer to their banking environment to complete the payment.
• Monitor payment status via API or Webhooks.

Orkestra enables seamless PSE integration, offering direct and secure bank payments for your customers in Colombia.