PseClient

Overview

The PseClient provides utilities for PSE (Pagos Seguros en Línea) payments, including:

Listing available Colombian banks for PSE
Creating PSE swap orders with automatic payment execution

Access it via bloque.swap.pse.

Constructor

The PseClient is automatically initialized as part of the SwapClient.

import { Bloque } from '@bloque/sdk';

const bloque = new Bloque({ apiKey: 'your-api-key' });
const pseClient = bloque.swap.pse;

Methods

banks()

Retrieves the list of financial institutions available for PSE payments.

async banks(): Promise<ListBanksResult>

Returns

ListBanksResult

object

Show ListBanksResult properties

banks

Bank[]

Array of available banks

Show Bank properties

code

string

Financial institution code (use this when creating PSE orders)

name

string

Financial institution name

Example

const result = await bloque.swap.pse.banks();

for (const bank of result.banks) {
  console.log(`${bank.code}: ${bank.name}`);
}

// Output:
// 1: Banco de Bogotá
// 2: Banco Popular
// 3: Bancolombia
// ...

create()

Creates a PSE swap order with optional automatic payment execution.

async create(params: CreatePseOrderParams): Promise<CreatePseOrderResult>

Parameters

params

CreatePseOrderParams

required

PSE order parameters

Show CreatePseOrderParams properties

rateSig

string

required

Rate signature obtained from findRates()

toMedium

string

required

Destination medium (e.g., 'kusama', 'bloque')

depositInformation

DepositInformation

required

Account where funds will be deposited

Show DepositInformation properties

urn

string

required

Account URN where funds will be depositedExample: "did:bloque:account:card:usr-xxx:crd-xxx"

args

PsePaymentArgs

required

PSE payment arguments for auto-execution

Show PsePaymentArgs properties

bankCode

string

required

Bank code from PSE banks list (obtained via banks())

userType

0 | 1

required

User type:

0: Natural person
1: Legal entity

customerEmail

string

required

Customer email address

userLegalIdType

'CC' | 'NIT' | 'CE'

required

User legal ID type:

CC: Cédula de Ciudadanía
NIT: Número de Identificación Tributaria
CE: Cédula de Extranjería

userLegalId

string

required

User legal ID number

customerData

PseCustomerData

required

Additional customer data

Show PseCustomerData properties

fullName

string

required

Customer’s full name

phoneNumber

string

required

Customer’s phone number

amountSrc

string

Source amount as bigint string (required if type is 'src')Example: "1000000" represents 10000.00 for COP/2

amountDst

string

Destination amount as bigint string (required if type is 'dst')

type

'src' | 'dst'

default:"src"

Order type:

'src': Taker specifies exact source amount to pay
'dst': Taker specifies exact destination amount to receive

webhookUrl

string

Optional webhook URL for order status notifications

nodeId

string

Specific node ID to execute (defaults to first node)

metadata

Record<string, unknown>

Additional metadata for the order

Returns

CreatePseOrderResult

object

Show CreatePseOrderResult properties

order

SwapOrder

The created swap order

Show SwapOrder properties

string

Unique order identifier

orderSig

string

Order signature

rateSig

string

Rate signature used for this order

swapSig

string

Swap signature

taker

string

Taker URN

maker

string

Maker URN

fromAsset

string

Source asset

toAsset

string

Destination asset

fromMedium

string

Source medium (always "pse" for PSE orders)

toMedium

string

Destination medium

fromAmount

string

Source amount

toAmount

string

Destination amount

string

Timestamp when the order was created

graphId

string

Instruction graph ID for tracking execution

status

string

Order status

metadata

Record<string, unknown>

Additional metadata

createdAt

string

Creation timestamp

updatedAt

string

Last update timestamp

execution

ExecutionResult

Execution result (if args were provided for auto-execution)

Show ExecutionResult properties

nodeId

string

Node ID that was executed

result

object

Execution result details

Show result properties

status

string

Execution status (e.g., "paused" when waiting for user to complete PSE payment)

name

string

Name of the current step

description

string

Description of what the user needs to do

how

ExecutionHow

Instructions for completing this step

Show ExecutionHow properties

type

string

Type of action required (e.g., "REDIRECT")

url

string

URL to redirect the user to complete the payment (PSE checkout URL)

callbackToken

string

Callback token for tracking

requestId

string

Request ID for tracking

Example

// Step 1: Find available rates
const rates = await bloque.swap.findRates({
  fromAsset: 'COP/2',
  toAsset: 'DUSD/6',
  fromMediums: ['pse'],
  toMediums: ['kusama'],
  amountSrc: '10000000' // 100,000.00 COP
});

// Step 2: Get available banks
const { banks } = await bloque.swap.pse.banks();
const bancolombia = banks.find(b => b.name.includes('Bancolombia'));

// Step 3: Create order with auto-execution
const result = await bloque.swap.pse.create({
  rateSig: rates.rates[0].sig,
  toMedium: 'kusama',
  amountSrc: '10000000',
  depositInformation: {
    urn: 'did:bloque:account:card:usr-xxx:crd-xxx'
  },
  args: {
    bankCode: bancolombia.code,
    userType: 0, // Natural person
    customerEmail: '[email protected]',
    userLegalIdType: 'CC',
    userLegalId: '1234567890',
    customerData: {
      fullName: 'Juan Pérez',
      phoneNumber: '+573001234567'
    }
  }
});

// Step 4: Redirect user to PSE checkout
if (result.execution?.result.how?.url) {
  window.location.href = result.execution.result.how.url;
}

console.log('Order ID:', result.order.id);
console.log('Status:', result.order.status);

PSE Payment Flow

The PSE payment flow involves the following steps:

Find rates: Use swap.findRates() to get available exchange rates
List banks: Use pse.banks() to get available banks
Create order: Use pse.create() with payment args to create and auto-execute the order
Redirect: Redirect the user to the PSE checkout URL returned in execution.result.how.url
Complete payment: User completes payment on the PSE platform
Callback: PSE notifies Bloque of payment completion via webhook
Funds deposited: Funds are deposited to the specified account URN

Fee Structure for PSE

PSE orders include multiple fee components:

const rate = rates.rates[0];

// Example fee breakdown:
for (const component of rate.fee.components) {
  switch (component.name) {
    case 'pse_fee':
      console.log('PSE transaction fee:', component.amount);
      break;
    case 'take_rate':
      console.log('Platform fee:', component.percentage, '%');
      break;
    case 'exchange_rate':
      console.log('Exchange rate:', component.pair);
      break;
  }
}

console.log('Total fee:', rate.fee.value);
console.log('Formula:', rate.fee.formula);

Webhook Notifications

You can specify a webhookUrl to receive order status updates:

const result = await bloque.swap.pse.create({
  rateSig: rates.rates[0].sig,
  toMedium: 'kusama',
  amountSrc: '10000000',
  webhookUrl: 'https://your-app.com/webhooks/pse',
  // ... other params
});

Webhook payload will include:

Order ID
Status updates
Transaction details

Error Handling

import { BloqueConfigError, BloqueValidationError } from '@bloque/sdk-core';

try {
  const result = await bloque.swap.pse.create(params);
} catch (error) {
  if (error instanceof BloqueConfigError) {
    console.error('Not connected to a session');
  } else if (error instanceof BloqueValidationError) {
    console.error('Invalid parameters:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Bank - PSE bank details
ListBanksResult - Result of listing banks
CreatePseOrderParams - Parameters for creating PSE orders
CreatePseOrderResult - Result of creating PSE order
PsePaymentArgs - PSE payment arguments
PseCustomerData - Customer data for PSE
DepositInformation - Deposit account details
SwapOrder - Swap order details
ExecutionResult - Auto-execution result

SDK

Accounts

Swap

Identity

Compliance

Organizations

Core

Overview

Constructor

Methods

banks()

Returns

Example

create()

Parameters

Returns

Example

PSE Payment Flow

Fee Structure for PSE

Webhook Notifications

Error Handling

Build docs developers (and LLMs) love

SDK

Accounts

Swap

Identity

Compliance

Organizations

Core

​Overview

​Constructor

​Methods

​banks()

​Returns

​Example

​create()

​Parameters

​Returns

​Example

​PSE Payment Flow

​Fee Structure for PSE

​Webhook Notifications

​Error Handling

​Related Types

Build docs developers (and LLMs) love

Overview

Constructor

Methods

banks()

Returns

Example

create()

Parameters

Returns

Example

PSE Payment Flow

Fee Structure for PSE

Webhook Notifications

Error Handling

Related Types