PSE

Integration Guide

When creating the transaction, you must query it continuously (long polling) until it contains a field called ‘paymentUrl’ inside an object ‘pse’, which will be inside the property ‘transferDetails’. Once you get it, you must redirect your client to this URL to complete the payment at the respective financial institution.

HTTP Request

POST /v1/payments/charges/pse

RequestResponse

Request Headers

{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

Request Body

 {
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "amount": 200000,
    "currency": "COP",
    "country": "CO",
    "paymentMethod": "PSE",
    "paymentFlow": "DIRECT",
    "pse": {
        "personType": "NATURAL",
        "financialInstitutionCode": "1"
    },
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "42243309114",
            "type": "CC"
        },
        "phone": "+57 3123456789",
        "billingAddress": {
            "zipCode": "111111",
            "state": "Cundinamarca",
            "city": "Bogotá",
            "street": "Apartamento 502, Torre I",
            "number": "Calle 34 # 56 - 78"
        }
    },
    "orderInfo": {
        "orderId": "test-order-id",
        "shippingInfo": {
            "name": "shipping test name",
            "phone": "+57 3123456789",
            "email": "thiago@example.com",
            "address": {
                "street": "street name",
                "number": "building number",
                "complement": "unit, apt, etc.",
                "district": "district, neighborhood, etc.",
                "city": "city name",
                "state": "state, state code",
                "zipCode": "111111",
                "country": "CO"
            }
        }
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "subMerchantId": "UUID"
}

Content-Type: application/json

{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "PSE",
    "amount": 200000,
    "currency": "COP",
    "country": "CO",
    "finalAmount": 200000,
    "finalCurrency": "COP",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    "finalStatusTime": "2022-03-01 17:53:18 GMT-08:00",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "42243309114",
            "type": "CC"
        },
        "phone": "+57 3123456789",
        "billingAddress": {  
            "zipCode": "111111",
            "state": "Cundinamarca",
            "city": "Bogotá",
            "street": "Apartamento 502, Torre I",
            "number": "Calle 34 # 56 - 78"
        }
    },
    "transferDetails": {
        "pse": {
            "paymentUrl": "https://registro.pse.com.co/PSENF/index.html?enc=DyGVt9V2EEGQ0%2bJZib7Itj8aNzDWHkvmPFJFVKZhOtQ%3d"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "subMerchantId": "UUID"
}

Notification / Callback

Content-Type: application/json

{
    "eventType": "CHARGE_SUCCEEDED",
        "data":  {
            "chargeDetails": {
                "transferStatusCode": 200,
                "transferErrorMsg": null,
                "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
                "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
                "paymentMethod": "PSE",
                "amount": 200000,
                "currency": "COP",
                "country": "CO",
                "finalAmount": 200000,
                "finalCurrency": "COP",
                "createTime": "2022-03-01 17:53:18 GMT-08:00",
                "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
                "finalStatusTime": "2022-03-01 17:53:18 GMT-08:00",
                "payer": {
                    "name": "username",
                    "email": "username@liquido.com",
                    "document": {
                        "documentId": "42243309114",
                        "type": "CC"
                    },
                    "phone": "+57 3123456789",
                    "billingAddress": {  
                        "zipCode": "111111",
                        "state": "Cundinamarca",
                        "city": "Bogotá",
                        "street": "Apartamento 502, Torre I",
                        "number": "Calle 34 # 56 - 78"
                    }
                },
            "transferStatus": "SETTLED",
            "transferDetails": {
                "pse": {
                    "paymentUrl": "https://registro.pse.com.co/PSENF/index.html?enc=DyGVt9V2EEGQ0%2bJZib7Itj8aNzDWHkvmPFJFVKZhOtQ%3d"
                }
            },
            "description": "this is a test pay",
            "callbackUrl": "https://api.client.com/callback/",
            "subMerchantId": "UUID"
        }
    }
}

Request Headers Parameters

Key	Value
Authorization	"bearer" + " " + {{access_token}}
x-api-key	{{api_key}}

Request Body Parameters

Parameter	Type	Description
idempotencyKey	String	Unique key to ensure idempotent requests. given by the merchant in their system.
amount	Long	The transfer amount, the minimum settlement granularity of the current currency, such as 100=1COP. The minimum amount is 1000COP
country	String	country code, value as CO
currency	String	The currency code of the transferred fund
paymentMethod	String	payment method, enum value as PSE
paymentFlow	String	payment flow, enum value as DIRECT
payer	JSON	payer info
orderInfo	JSON	order info
description	String	Specify a name of what is being paid for
callbackUrl	String	URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
pse	JSON	Customized info for this payment method
subMerchantId	String	The sub merchant ID. Required for PSPs.
riskData	JSON	The risk data of the payment. MERCHANT_APP_NAME or MERCHANT_WEBSITE must be provided in risk Data. Please see here for further details.

Create A Payment With Risk Data

Please see here for further details.

Payer Object Parameters

Parameter	Type	Description
name	String	fullname(Input specification: Only a combination of uppercase and lowercase letters, numbers and spaces is allowed. Spanish and Portuguese letters, and other special characters are not allowed).
email	String	email.
document	JSON	document info
phone	String	Mobile phone number. Should include “+57” as a prefix.
billingAddress	JSON	Billing address info.

BillingAddress Object Parameters

Parameter	Type	Description
zipCode	String	zip code.
state	String	state.
city	String	city name.
street	String	street name.
number	String	street number.

PSE Object Parameters

Parameter	Type	Description
financialInstitutionCode	String	Code for the financial institution in which the payer wants to make the payment. (You can see here to get the institution list.)
personType	String	Specify what kind of the payer is, enum value as NATURAL or LEGAL
redirectUrl	String	URL where Liquido will redirect to after the payment is finished

Document Object Parameters

Parameter	Required	Type	Description
documentId		String	document number.
type		String	document type, enum value as CC, CE, NIT or COLOMBIA_PASSPORT_ID

OrderInfo Object Parameters

Parameter	Required	Type	Description
orderId		String	order identity number (Required only when object is provided)
shippingInfo		JSON	shipping info

ShippingInfo Object Parameters

Parameter	Type	Description
name	String	shipping name
phone	String	Mobile phone number. Should include “+57” as a prefix. (Required only when object is provided)
email	String	email address
address	JSON	shipping address info (Required only when object is provided)

ShippingAddress Object Parameters

Parameter	Type	Description
zipCode	String	zip code
state	String	state (Required only when object is provided)
city	String	city name. (Required only when object is provided)
street	String	street name. (Required only when object is provided)
number	String	street number. (Required only when object is provided)

Response Body Parameters

Parameter	Type	Description
transferStatus	String	Transfer status, SETTLED, IN_PROGRESS, FAILED
transferStatusCode	Integer	Transfer status code, 200 transaction SETTLED or IN_PROGRESS, other FAILED
transferErrorMsg	String	Transfer error message if failed
referenceId	String	Unique key to payment ticket, generated by Liquido.
idempotencyKey	String	Unique key to ensure idempotent requests. given by the merchant in their system
amount	Long	The transfer amount
country	String	country code
currency	String	The currency code of the transferred fund
finalAmount	Long	The final amount that is used for creating the charge order. EX: for charge orders with FX conversion, this field represents the converted amount from the original requested amount.
finalCurrency	String	The currency code of the finalAmount.
paymentMethod	String	payment method, enum value as PSE
payer	JSON	payer info
transferDetails	JSON	transaction details info
description	String	description of payment
callbackUrl	String	URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
createTime	String	Payment ticket created time
scheduledTime	String	Payment ticket scheduled time
finalStatusTime	String	Transfer final status update time, final status include SETTLED, FAILED
subMerchantId	String	The sub merchant ID.

TransferDetails Object Parameters

Parameter	Type	Description
pse	JSON	PSE detail info

PSE TransferDetails Object Parameters

Parameter	Type	Description
paymentUrl	String	url for payment

Transfer Status

Parameter	Description
IN_PROGRESS	The transaction of this method has started, but no transactions have been processed yet.
SETTLED	The funds of the transaction of this payment have been transferred to the store.
REFUNDING	The transaction of this payment is refunding.
REFUNDED	The transaction of this payment method has been refunded.
CHARGED_BACK	The transaction of this payment has been reported as chargeback.
FAILED	There was an error while processing the transaction of this payment. This status is followed by a message with more details about the error.

Notification Event Type

CHARGE_SUCCEEDED,
CHARGE_FAILED,
CHARGE_CHARGED_BACK,
CHARGE_REFUND_SUCCEEDED,
CHARGE_REFUND_FAILED;