Skip to content

PayCash

Payment Instructions

For cash payments at offline points in Colombia, the payer is required to provide the generated reference number(referencia) and a fixed agreement code(convenio) 112766 to the cashier to make payments.

HTTP Request

POST /v1/payments/charges/paycash

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "co-20221001-0001",
    "amount": 50000,
    "currency": "COP",
    "country": "CO",
    "paymentMethod": "PAY_CASH",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "billingAddress": {  
            "zipCode": "03400",
            "state": "CDMX",
            "city": "Álamos",
            "street": "Simón Bolívar",
            "number": "12121"
        }
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",   
            "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": "zip code, postal code",
                "country": "CO"
            }
        }
    },
    "riskData": {
        "ipAddress":"192.0.0.130",
        "customProperties": {
            "merchantId":"1527558812935028000",
            "merchantName":"LIQUIDO PTE. LTD."
      }
    },
    "callbackUrl":"https://api.client.com/callback/",
    "description": "this is a test pay",
    "expirationDate": "2022-10-31",
    "recurring": false
}

Response

Content-Type: application/json
{
    "transferStatusCode": 200,
    "idempotencyKey": "co-20221001-0001",
    "referenceId": "co-20221001-0001",
    "paymentMethod": "PAY_CASH",
    "amount": 50000,
    "currency": "COP",
    "finalAmount": 50000,
    "finalCurrency": "COP",
    "country": "CO",
    "createTime": "2022-10-01 09:44:29 UTC",
    "scheduledTime": "2022-10-01 09:44:33 UTC",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "billingAddress": {
            "street": "Simón Bolívar",
            "number": "12121",
            "city": "Álamos",
            "state": "CDMX",
            "zipCode": "03400"
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/",
    "transferDetails": {
        "payCash": {
            "referenceNumber": "2701665308673817",
            "expirationDate": "2022-10-31",
            "recurring": false
        }
    }
}

Notification / Callback

Content-Type: application/json
{
    "eventType":"CHARGE_SUCCEEDED",
    "data":{
        "chargeDetails":{
                "transferStatusCode": 200,
                "idempotencyKey": "co-20221001-0001",
                "referenceId": "co-20221001-0001",
                "paymentMethod": "PAY_CASH",
                "amount": 50000,
                "currency": "COP",
                "finalAmount": 50000,
                "finalCurrency": "COP",
                "country": "CO",
                "createTime": "2022-10-01 09:44:29 UTC",
                "scheduledTime": "2022-10-01 09:44:33 UTC",
                "payer": {
                    "name": "username",
                    "email": "username@liquido.com",
                    "billingAddress": {
                        "street": "Simón Bolívar",
                        "number": "12121",
                        "city": "Álamos",
                        "state": "CDMX",
                        "zipCode": "03400"
                    }
                },
                "transferStatus":"SETTLED",
                "description": "this is a test pay",
                "callbackUrl": "https://api.client.com/callback/",
                "transferDetails": {
                    "payCash": {
                        "referenceNumber": "2701665308673817",
                        "expirationDate": "2022-10-31",
                        "recurring": false,
                        "paymentTime": "2022-10-06 00:21:20"
                    }
                }
        }
    }
}

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
country String country code
currency String The currency code of the transferred fund
paymentMethod String payment method, enum value as PAY_CASH
paymentFlow String payment flow, enum value as DIRECT or REDIRECT
payer JSON payer info
orderInfo JSON order info
riskData JSON risk control info, if PSP, please add sub-merchant here, example as "customProperties":{"merchantId":"1527558812935028000","merchantName":"LIQUIDO PTE. LTD."}
description String description of payment
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.
expirationDate String payment expire date(yyyy-MM-dd)
recurring Boolean Multiple times to pay or single,only support single currently,fixed value：false
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).
email String email.
phone String Mobile Phone number.
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.
OrderInfo Object Parameters
Parameter Required Type Description
orderId String order identity number
shippingInfo JSON shipping info
ShippingInfo Object Parameters
Parameter Required Type Description
name String shipping name
phone String phone number
email String email address
address JSON the same as billingAddress
RiskData Object Parameters
Parameter Required Type Description
ipAddress String Payer's IP address
customProperties JSON Key/value pairs used to store additional custom metadata

Response Body Parameters

Parameter Type Description
transferStatus String Transfer status, SETTLED, IN_PROGRESS, FAILED
transferStatusCode int 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 String 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 BANK_TRANSFER, PAY_CASH
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
TransferDetails Object Parameters
Parameter Type Description
payCash JSON The payCash details
PayCash Object Parameters
Parameter Type Description
referenceNumber String The payer is required to provide this reference number and a fixed agreement number 112766 to make a cash payment
expirationDate String Expire date in Colombia time,format "yyyy-MM-dd"
recurring Boolean Multiple times to pay or single
paymentTime String Actual payment time in Colombia time,format "yyyy-MM-dd HH:mm:ss"

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.
EXPIRED The transaction of this payment has been expired.
CANCELLED The transaction of this payment has been cancelled.
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