Skip to main content
Use rail: "PSE" when you want the payer to authenticate the payment with a supported Colombian bank through the PSE flow. Before implementing this rail:
  • Review How to create your first payin for the shared request fields and lifecycle.
  • Configure webhooks to receive the final payin outcome asynchronously.
  • Treat callbackUrl as the payer return URL, not as the source of truth for payment confirmation.

​
How the PSE flow works

  1. Create the payin with rail: "PSE" and include the selected bank in pse.bank.
  2. HelloPay starts the payin in PROCESSING.
  3. Right after creation, sourceData.pseUrl is null.
  4. Poll the payin until HelloPay updates sourceData.pseUrl with the redirect URL for the payer.
  5. The payer completes the authorization through the PSE bank flow.
  6. HelloPay sends webhook events such as payin.confirmed, payin.canceled, or payin.declined.
  7. After the payer finishes the flow, HelloPay redirects them to your callbackUrl.

​
Request example

This flow is asynchronous. After creating the payin, sourceData.pseUrl is initially null, so you must poll the transaction until the redirect URL is available. 
curl --location 'https://api.stg.hellopay.com.co/payins' \
--header 'Content-Type: application/json' \
--header 'x-api-key: ••••••' \
--data-raw '{
  "amountInCents": 10000,
  "currency": "COP",
  "rail": "PSE",
  "reference": "1001122",
  "inlineCustomer": {
    "name": "John Doe",
    "idType": "CO_CC",
    "idNumber": "1000000001",
    "email": "john.doe@doe.com",
    "phone": "+573131111111"
  },
  "pse": {
    "bank": "CO_BANCOLOMBIA",
    "personType": "INDIVIDUAL"
  },
  "callbackUrl": "https://portal.hellopay.com.co"
}'

​
Request fields

  • amountInCents: amount to collect, expressed in cents.
  • currency: currently COP.
  • rail: must be PSE.
  • reference: your internal identifier for this payin.
  • inlineCustomer: customer information used during the payment flow. Supported document types are listed in How to create your first payin.
  • pse.bank: bank selected by the payer from the supported PSE bank list.
  • pse.personType: payer type. Supported values are INDIVIDUAL and BUSINESS.
  • callbackUrl: URL where the payer is redirected after leaving the PSE flow.

​
Supported banks

Use one of the following values in pse.bank:
CodeBank Name
CO_ACCION_FIDUCIARIAAccion Fiduciaria
CO_ADDI_CFAddi CF
CO_ALIANZA_FIDUCIARIAAlianza Fiduciaria
CO_BAN100Ban100
CO_BANCAMIABancamia
CO_AGRARIOBanco Agrario
CO_CAJA_SOCIALBanco Caja Social
CO_AV_VILLASBanco AV Villas
CO_COOMEVABanco Coomeva
CO_COOPCENTRALBanco Coopcentral
CO_COOPCENTRAL_DIGITALBanco Coopcentral Digital
CO_DAVIVIENDABanco Davivienda
CO_BOGOTABanco de Bogota
CO_OCCIDENTEBanco de Occidente
CO_FALABELLABanco Falabella
CO_FINANDINABanco Finandina
CO_GNB_SUDAMERISBanco GNB Sudameris
CO_JP_MORGANBanco JP Morgan
CO_MUNDO_MUJERBanco Mundo Mujer
CO_PICHINCHABanco Pichincha
CO_POPULARBanco Popular
CO_SANTANDERBanco Santander
CO_SERFINANZABanco Serfinanza
CO_UNIONBanco Union
CO_BANCOLOMBIABancolombia
CO_BANKABanka
CO_BBVABBVA
CO_BOLD_CFBold CF
CO_CITIBANKCitibank
CO_COINKCoink
CO_COLTEFINANCIERAColtefinanciera
CO_CONFIARConfiar
CO_COOFINEPCoofinep
CO_COTRAFACotrafa
CO_CFACFA
CO_CREZCAMOSCrezcamos
CO_DALEDale
CO_DAVIPLATADaviplata
CO_DINGDing
CO_FINANCIERA_JURISCOOPFinanciera Juriscoop
CO_GLOBAL66Global66
CO_IRISIris
CO_ITAUItau
CO_JFKJFK
CO_LULO_BANKLulo Bank
CO_MOVIIMovii
CO_NEQUINequi
CO_NUNu
CO_PAYCASHPaycash
CO_POWWIPowwi
CO_RAPPIPAYRappiPay
CO_SANTANDER_CONSUMERSantander Consumer
CO_SCOTIABANK_COLPATRIAScotiabank Colpatria
CO_UALAUala
CO_SUPERDIGITALSuperdigital

​
Supported person types

Use one of the following values in pse.personType:
ValueDescription
INDIVIDUALIndividual person paying with a personal bank account.
BUSINESSCompany or legal entity paying with a business bank account.

​
Response example

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 10000,
  "currency": "COP",
  "status": "PROCESSING",
  "rail": "PSE",
  "reference": "1001122",
  "inlineCustomer": {
    "name": "John Doe",
    "idType": "CO_CC",
    "idNumber": "1000000001",
    "email": "john.doe@doe.com",
    "phone": "+573131111111"
  },
  "errorCode": null,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "resultAt": null,
  "organizationId": "123e4567-e89b-12d3-a456-426614174000",
  "sourceData": {
    "pseUrl": null
  },
  "callbackUrl": "https://portal.hellopay.com.co"
}

​
What the response means

  • status: "PROCESSING" means the payin was created and is waiting for the payer to complete the PSE flow.
  • sourceData.pseUrl is null in the creation response and is filled later when you poll the payin again.
  • sourceData also includes the PSE-specific data associated with the payin, such as the selected bank and person type.
  • The final outcome is delivered asynchronously through webhooks, so do not treat the creation response as the final payment result.