PSE (Colombia)

Localpayment enables merchants to process secure online payments through PSE (Pagos Seguros en Línea), Colombia's official online banking payment system developed by ACH (Automated Clearing House) Colombia. This guide outlines the process for initiating PSE-based payments through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes for seamless integration with Colombia's banking infrastructure.

Before You Begin

Ensure you have:

Valid API credentials(access token).

Step 1. Create PSE Payment

To initiate a PSE payment in Colombia, send a POST request to the Create Payin endpoint with PSE-specific parameters.

Key Request Parameters

The request requires several key objects specific to Colombia PSE payments:

Object	Description	Required
`paymentMethod.type`	Must be `BankTransfer`.	✅
`paymentMethod.code`	Use `1936` for Colombia PSE.	✅
`sender`	Sender information for compliance.	✅
`merchant`	Merchant/business details.	✅
`paymentMethod`	Payment method configuration.	✅
`amount`	Transaction amount.	✅
`currency`	Transaction currency code.	✅
`country`	Must be `COL`.	✅

See all available parameters in the request.

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1936",
    "flow": "REDIRECT"
  },
  "currency": "COP",
  "merchant": {
    "type": "COMPANY",
    "document": {
      "type": "NIT",
      "id": "9012754183"
    },
    "phone": {
      "countryCode": "countryCode",
      "areaCode": "areaCode",
      "number": "number"
    },
    "address": {
      "street": "Street",
      "number": "938",
      "city": "city",
      "state": "state",
      "country": "country",
      "zipCode": "zipCode",
      "comment": "Add any usefull information"
    },
    "name": "Company",
    "userReference": "abc123",
    "birthdate": "2000-01-01",
    "nationality": "nationality"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "document": {
      "id": "9012754183",
      "type": "NIT"
    },
    "phone": {
      "countryCode": "countryCode",
      "areaCode": "areaCode",
      "number": "number"
    },
    "address": {
      "street": "Street",
      "number": "1234",
      "city": "city",
      "state": "state",
      "country": "country",
      "zipCode": "zipCode",
      "comment": "Add any relevant information related to the payer"
    },
    "bank": {
      "account": {
        "type": "C"
      }
    },
    "name": "John",
    "lastname": "Doe",
    "email": "[email protected]",
    "birthdate": "01/01/1990",
    "nationality": "nationality",
    "userReference": "abcdef1"
  },
  "commercialData": {
    "items": [
      {
        "id": "",
        "title": "",
        "description": "",
        "pictureUrl": "",
        "categoryId": "",
        "quantity": "",
        "unitPrice": ""
      }
    ],
    "shipments": [
      {
        "street": "",
        "number": "",
        "city": "",
        "state": "",
        "contry": "",
        "zipCode": "",
        "comment": ""
      }
    ],
    "invoice": ""
  },
  "device": {
    "deviceId": "",
    "ip": "",
    "browser": ""
  },
  "externalId": "5e73dada-522f-429d-a93e-5d5e968943ab",
  "country": "COL",
  "amount": 1000,
  "accountNumber": "170.170.00000011",
  "conceptCode": "0003",
  "comment": "Any relevant information related to the transaction",
  "bank": {
    "name": "{Account holder name}",
    "code": "1022"
  },
  "account": {
    "type": "C",
    "number": "130069085"
  }
}
'

Step 2. Handle the Response

Successful Response

A successful PSE payment creation includes the redirect URL and transaction details:

{
  "transactionType": "PayIn",
  "externalId": "f5d2a6b7-698a-48f4-b886-03649a3c4d99",
  "internalId": "3d010a7f-8826-4cdd-9a1a-976afeb2db5a",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1936",
    "flow": "REDIRECT"
  },
  "country": "COL",
  "currency": "COP",
  "amount": 500,
  "accountNumber": "170.170.00000011",
  "confirmed": {
    "currency": "COP",
    "amount": 500,
    "fxQuote": 1
  },
  "payment": {
    "currency": "COP",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 500
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "COP",
    "fxSource": 4015,
    "fxQuote": 1,
    "amount": 0,
    "account": "170.170.00000011"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "bank": {
      "code": "1007"
    },
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "NIT",
      "id": "9012754183"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "co",
      "areaCode": "57",
      "number": "573165212345"
    },
    "address": {
      "street": "CLL 127 C BIS 7B 60 ",
      "city": "BOGOTA DC",
      "state": "BOGOTA DC",
      "country": "COL",
      "comment": "Test"
    }
  },
  "intermediaries": [],
  "wireInstructions": {
    "referenceCode": "TB7X-UHSD-5JAL"
  },
  "date": {
    "creationDate": "2024-12-05T21:16:07.692+00:00",
    "processedDate": "2024-12-05T21:16:11.1682535",
    "expirationDate": "2024-12-12T21:16:10.6082303"
  },
  "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly9yZWdpc3Ryby5kZXNhcnJvbGxvLnBzZS5jb20uY28vUFNFTkYvaW5kZXguaHRtbD9lbmM9djF3Z0olMmZHd2phN0pwWDRjQ1dTJTJiallDVWVJRW94U3FqcFlROGtBT0tvN0ElM2Q",
  "errors": []
}

Key Response Fields

Parameter	Description	Use Case
`redirectUrl`	URL to redirect customer to PSE banking portal.	Direct customer to bank authentication and payment processing.
`wireInstructions.referenceCode`	Unique payment reference code.	Display to customer for payment tracking.
`externalId`	Your original reference number.	Internal reconciliation and order matching.
`status.code`	Current transaction state (`100` = `INPROGRESS`)	Determine next steps in payment flow.
`date.creationDate`	When transaction was created.	Analytics and performance tracking.

Error Response

When PSE payment creation fails for Colombia, you'll receive specific error information:

{
  "externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
  "status": {
    "code": "812",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "812",
      "detail": "External Id already used - duplication"
    }
  ]
}

Step 3. Handle PSE Payment Flow

Payment Initiation: Redirect customer to PSE payment url.
Bank Authentication: Customer logs into their online banking environment.
Payment Authorization: Customer confirms payment within their banking interface.
Real-time Confirmation: Localpayment receives payment notification.
Status Update: Your system receives webhook with payment confirmation.

Step 4. Track Transaction Status

Monitor PSE payment progress through these methods:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Status Codes

The Localpayment API provides various status codes to indicate the progress and outcome of the payment in the response.

Code	Status	Description
`103`	`APPROVED`	The payin was confirmed but not credited yet.
`200`	Completed	The payin was completed.
`811`	Rejected	Requested amount is higher or lower than allowed max/min values.

📝
Note: For complete status code reference, see the Transaction Status Documentation.

Country-Specific Requirements

Supported Colombian Banks (PSE)

PSE payments are supported for the following financial institutions:

Bank list

BANCO DE BOGOTA
BANCO POPULAR
BANCO ITAU
BANCOLOMBIA
CITIBANK
BANCO GNB SUDAMERIS
BANCO BBVA COLOMBIA S.A.
SCOTIABANK COLPATRIA
BANCO DE OCCIDENTE
BANCO CAJA SOCIAL
BANCO AGRARIO
BANCO MUNDO MUJER
BANCO DAVIVIENDA
BANCO AV VILLAS
BANCAMIA S.A.
BANCO PICHINCHA S.A.
BANCOOMEVA S.A.
BANCO FALABELLA
BANCO FINANDINA S.A. BIC
BANCO SANTANDER COLOMBIA
BANCO COOPERATIVO COOPCENTRAL
BANCO SERFINANZA
LULO BANK
J.P. MORGAN COLOMBIA S.A
DALE
CFA COOPERATIVA FINANCIERA
JFK COOPERATIVA FINANCIERA
COTRAFA CONFIAR COOPERATIVA FINANCIERA
BANCO UNION (formerly GIROS COLTEFINANCIERA)
NEQUI
AVIPLATA
BAN100
IRIS
MOVII S.A.
UALÁ
NU
RAPPIPAY
ALIANZA FIDUCIARIA S.A.
CREZCAMOS
BOLD CF
DING

Testing Your Integration

Sandbox Environment

Use the staging environment for testing:

https://api.stage.localpayment.com/api/payin/

Test Scenarios for Colombia

Verify your integration handles these scenarios:

Successful Payment: Complete PSE payment flow with bank simulation.
Bank Authentication: Test different bank authentication flows.
Payment Expiration: Handle payment session expiration gracefully.
Authentication Failure: Test failed bank login scenarios.
Status Updates: Webhook handling and status polling.

Next Steps

After implementing PSE payments, consider these additional capabilities:

Refund the transaction

If necessary, you can refund the payment to the customer. Refer to the documentation for details.

Review transaction details

You can retrieve transaction information using the Localpayment API for detailed insights.

Before You Begin

Step 1. Create PSE Payment

Key Request Parameters

Example Request

Step 2. Handle the Response

Successful Response

Key Response Fields

Error Response

Step 3. Handle PSE Payment Flow

Step 4. Track Transaction Status

Common Status Codes

Note: For complete status code reference, see the Transaction Status Documentation.

Country-Specific Requirements

Supported Colombian Banks (PSE)

Testing Your Integration

Sandbox Environment

Test Scenarios for Colombia

Next Steps