PSE (Colombia)

PSE (Pagos Seguros en Línea) is the electronic payment network operated by ACH Colombia. It connects over 1,000 entities — banks, financial institutions, and payment processors — enabling real-time electronic fund transfers in Colombian pesos (COP).

mcp2p exposes PSE as three MCP tools. Enable the rail by including "pse" in your rails array when calling createMcp2pServer.

Overview

  • Settlement time: Typically seconds to a few minutes during banking hours.
  • Operating hours: Business hours (ACH Colombia schedule). Not 24/7.
  • Currency: Colombian peso (COP). Amounts in centavos (minor units).
  • Routing: Via NIT or Cédula de Ciudadanía plus a bank code.
  • Network: ACH Colombia connects 1,000+ financial entities.

Available tools

pse_send_payment

2FA required

Initiate a PSE electronic payment through ACH Colombia. Requires 2FA authorization.

ParameterTypeRequiredDescription
recipientIdstringYesRecipient identifier. Format: "NIT:123456789" or "CC:12345678"
bankCodestringYesPSE bank code for the receiving institution (3-digit ACH Colombia code)
amountnumberYesAmount in centavos de peso (minor units). E.g. 100000 = COP 1,000.00
descriptionstringYesPayment description (max 60 chars)
verificationCodestringNo6-digit OTP from Twilio Verify. Omit on first call to trigger SMS.

pse_check_status

No 2FA

Check the current status of a PSE transaction by its reference number.

ParameterTypeRequiredDescription
referenceNumberstringYesPSE reference number returned by pse_send_payment

pse_request_refund

2FA required

Request a refund for a completed PSE payment. Requires 2FA authorization.

ParameterTypeRequiredDescription
referenceNumberstringYesReference number of the original transaction
reasonstringYesReason for the refund request
verificationCodestringNo6-digit OTP. Omit on first call to trigger SMS.

Recipient validation

PSE requires the recipient to be identified by either a NIT or a Cédula de Ciudadanía. Pass these as a prefixed string in the recipientId field:

NIT (Número de Identificación Tributaria)

  • Used for companies, legal entities, and self-employed individuals.
  • Format: 9 to 10 digits followed by a hyphen and a 1-digit check digit.
  • Pass as: NIT:900123456 (without the check digit — the SDK computes it).
  • Validation: Modulus-11 algorithm with weights [3, 7, 13, 17, 19, 23, 29, 37, 41, 43, 47].

CC (Cédula de Ciudadanía)

  • Used for natural persons (Colombian citizens).
  • Format: 6 to 10 digits.
  • Pass as: CC:1234567890
  • Validation: Length and numeric-only check. No check digit for CC numbers.
The SDK validates the identifier prefix and format before making any network request. An invalid format returns PSE_INVALID_IDENTIFIER immediately without sending an SMS.

Code example

// User: "Pay COP 100,000 to NIT 900123456 at Bancolombia"

// ── Turn 1: AI calls tool without verification code ──────────────────────────
// Tool call: pse_send_payment
// {
//   recipientId: "NIT:900123456",
//   bankCode: "001",           // Bancolombia ACH code
//   amount: 10000000,          // COP 100,000.00 in centavos
//   description: "Supplier payment"
// }
//
// SDK response:
// {
//   status: "2fa_required",
//   message: "Verification code sent via SMS."
// }

// ── Turn 2: User provides code ────────────────────────────────────────────────
// Tool call: pse_send_payment (same params + verificationCode)
// {
//   recipientId: "NIT:900123456",
//   bankCode: "001",
//   amount: 10000000,
//   description: "Supplier payment",
//   verificationCode: "391847"
// }
//
// SDK response:
// {
//   status: "success",
//   referenceNumber: "PSE-2024012614574900012345",
//   amount: 10000000,
//   currency: "COP",
//   settledAt: "2024-01-26T14:58:03Z"
// }

Error codes

CodeDescription
PSE_INVALID_IDENTIFIERRecipient ID fails format or check-digit validation
PSE_UNKNOWN_BANKBank code is not a recognized ACH Colombia member
PSE_LIMIT_EXCEEDEDAmount exceeds the allowed limit for this license tier
PSE_INSUFFICIENT_FUNDSSource account has insufficient balance
PSE_BANK_UNAVAILABLEThe receiving bank is temporarily unavailable in the PSE network
PSE_TIMEOUTPayment timed out waiting for ACH Colombia confirmation

See the Error Codes page for the complete reference including license and 2FA errors.

Next steps