Skip to content

Nequi

Integration Guide

Nequi payment process can be different due to the "phone" request parameter. When the "phone" request parameter is with value in it, payment notification will be sent to Nequi APP where customer should go to the APP notification center to finish payment. When the "phone" request parameter is null or there's no "phone" request parameter being sent, "paymentUrl" will be included in the response and customer can fill in related information within this url, then a QR code will be generated. Customer should go to Nequi APP and scan this QR code to finish payment.

HTTP Request

POST /v1/payments/charges/nequi

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": "NEQUI",
    "paymentFlow": "DIRECT",
    "nequi": {
        "phone": "+573991111111"
    },
    "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",  
            "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"
            }
        }
    },
    "riskData": {
        "ipAddress": "192.0.0.130"
    },
    "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": "NEQUI",
    "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": {
        "nequi": {
            "phone": "+573991111111"
        }
    },
    "transferStatus": "SETTLED",
    "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": "NEQUI",
    "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": {
        "nequi": {
            "expiresAt": 1695272400,
            "paymentUrl": "https://secure.payzen.lat/t/iagftbij"
        }
    },
    "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": "NEQUI",
                "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": {
                "nequi": {
                    "phone": "+573983956309"
                }
            },
            "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 Required 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 2000COP
country String country code, enum value as CO
currency String The currency code of the transferred fund
paymentMethod String payment method, enum value as NEQUI
paymentFlow String payment flow, enum value as DIRECT or REDIRECT
payer JSON payer info
orderInfo JSON order info
riskData JSON risk control 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.
nequi JSON Customized info for this payment method
subMerchantId String The sub merchant ID. Required for PSPs.

Payer Object Parameters

Parameter Required 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). Required when Nequi phone number is not being sent or sent with null.
email String email.
document JSON Document info. Required when Nequi phone number is not being sent or sent with null.
phone String Mobile phone number. Should include “+57” as a prefix. Required when Nequi phone number is not being sent or sent with null.
billingAddress JSON Billing address info.

BillingAddress Object Parameters

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

Nequi Object Parameters

Parameter Required Type Description
phone String Mobile phone number registered with the Nequi account. Should include “+57” as a prefix.
When this field is sent with value in it, customer should finish the payment by Nequi APP in the notification center.
When this field is not being sent or sent with null, customer should finish the payment by using Nequi APP to scan a QR code.

Document Object Parameters

Parameter Required Type Description
documentId String document number.
(Required only when object is provided)
type String document type, enum value as CC, CE, NIT or TI
(Required only when object is provided)

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 Required 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 Required 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)

RiskData Object Parameters

Parameter Required Type Description
ipAddress String Payer's IP address

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 PHONE_PAY
payer JSON payer 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
nequi JSON Nequi detail info

Nequi TransferDetails Object Parameters

Parameter Type Description
phone String Mobile phone number registered with the Nequi account.
Included in the response only when “phone” is sent with value in the request parameter.
expiresAt Long Timestamp for payment expiration time. Included in the response only when “phone” is sent without value or is sent with null in the request parameter.
paymentUrl String The URL where you must redirect your customer to generate QR code for the payment. Included in the response only when “phone” is sent without value or is sent with null in the request parameter.

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;
Back to top