Skip to content

Recurring Payment

The reference number generated by Paycash recurring payment can be paid multiple times, and will be recorded as multiple payin orders in Liquido's backend.

For cash payments at offline collection points in Colombia, the payer is required to provide two numbers to the cashier to finish payments. One is the generated reference number(referencia) and the other is the agreement code(convenio). Reference number is included in the response which locates in ‘referenceNumber’ response field. Agreement code may differ with different offline collection points, please check the details in Agreement Codes.

HTTP Request

POST /v1/payments/charges/references

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "9d9537a8-2d5a-756b-0545-c2a341396476",
    "paymentMethod": "PAY_CASH",
    "country": "CO",
    "currency": "COP",
    "amount": 0,
    "expirationDate": "2024-09-30",
    "description": "this is a test reference",
    "callbackUrl": "https://api.client.com/callback/"
}
Content-Type: application/json
{
    "transferStatusCode": 200,
    "idempotencyKey": "9d9537a8-2d5a-756b-0545-c2a341396476",
    "country": "CO",
    "currency": "COP",
    "createTime": "2023-09-22 09:23:27 UTC",
    "status": "ACTIVE",
    "description": "this is a test reference",
    "callbackUrl": "https://api.client.com/callback/",
    "transferDetails": {
        "payCash": {
            "amount": 0,
            "expirationDate": "2024-09-30",
            "reference": "2701695338912816"
        }
    }
}

Notification / Callback

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data": {
        "chargeDetails": {
            "transferStatusCode": 200,
            "idempotencyKey": "ref_LuqLYcYWnlrNBUfqyxwRmwA6W",
            "referenceId": "9d9537a8-2d5a-756b-0545-c2a341396476",
            "paymentFlow": "DIRECT",
            "paymentMethod": "PAY_CASH",
            "amount": 2000000,
            "currency": "COP",
            "finalAmount": 2000000,
            "finalCurrency": "COP",
            "country": "CO",
            "createTime": "2023-09-22 09:32:00 UTC",
            "finalStatusTime": "2023-09-22 09:32:00 UTC",
            "payer": {},
            "transferStatus": "SETTLED",
            "description": "this is a test reference",
            "callbackUrl": "https://api.client.com/callback/",
            "transferDetails": {
                "payCash": {
                    "referenceNumber": "2701695338912816",
                    "expirationDate": "2024-09-30",
                    "recurring": true,
                    "paymentTime": "2023-09-23 09:30:59"
                }
            }
        }
    }
}

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.
paymentMethod String Payment method, enum value as PAY_CASH.
country String country code
currency String The currency code of the transferred fund
amount Long The transaction amount. The minimum settlement granularity of the current currency, such as 100=1COP. It’ll be ‘0’ by default.
If the amount is ‘0’, end customers can pay at offline collection points by any amount they want with the reference number, eg. end customer can pay 100COP for the first time and pay 200COP for the second time.
If the amount is not ‘0’, eg. it’s ‘50000’, meaning that end customers can only pay fixed amount for 500COP each time.
expirationDate String Payment’s expiration date(yyyy-MM-dd).
description String description of payment
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.

Response Body Parameters

Parameter Type Description
transferStatusCode Integer Transfer status code, 200 transaction SETTLED or IN_PROGRESS, other FAILED
idempotencyKey String Unique key to ensure idempotent requests. given by the merchant in their system
country String country code
currency String The currency code of the transferred fund
createTime String Payment ticket created time
status String Transfer status
description String description of payment
transferDetails JSON transaction details info
callbackUrl String URL where Liquido will send notifications associated to changes to this payment. will receive a post request.

Object Parameters

TransferDetails
Parameter Type Description
payCash JSON The payCash details
PayCash
Parameter Type Description
amount Long The transaction amount.
expirationDate String Expire date in Colombia time,format "yyyy-MM-dd"
reference String This is a reference that can be used for more than one time.
The payer is required to provide two numbers to the cashier to finish payment. One is this reference number and the other is an agreement number.

Status

Parameter Description
ACTIVE The transaction has been created successfully, and it’s active for processing.
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;

Agreement Codes

Offline Collection Points Agreement Code
Efecty 112766
Refacil Don't need an agreement code.
Acciones y valores Don't need an agreement code.
Banco de Bogotá Don't need an agreement code.
APUESTAS NACIONALES (Corresponsal Banco de Bogotá) 22506
BEMOVIL (Corresponsal Banco de Bogotá) 22506
CB CLARO (Corresponsal Banco de Bogotá) 22506
COMERCIAL CARD (Corresponsal Banco de Bogotá) 22506
CONSUERTE (Corresponsal Banco de Bogotá) 22506
COOPENESA (Corresponsal Banco de Bogotá) 22506
EDEQ (Corresponsal Banco de Bogotá) 22506
FULLCARGA (Corresponsal Banco de Bogotá) 22506
JER (Corresponsal Banco de Bogotá) 22506
MAFEPHONE (Corresponsal Banco de Bogotá) 22506
MAXI SERVICIOS (Corresponsal Banco de Bogotá) 22506
MOVIL RED (Corresponsal Banco de Bogotá) 22506
PEQUEÑAS SUPERFICIES CREDIBANCO (Corresponsal Banco de Bogotá) 22506
PEQUEÑAS SUPERFICIES REDEBAN (Corresponsal Banco de Bogotá) 22506
PRACTISISTEMAS (Corresponsal Banco de Bogotá) 22506
PUNTO DE PAGO (Corresponsal Banco de Bogotá) 22506
PUNTORED (Corresponsal Banco de Bogotá) 22506
SEAPTO (Corresponsal Banco de Bogotá) 22506
SU CHANCE (Corresponsal Banco de Bogotá) 22506
SUPERPAGOS (Corresponsal Banco de Bogotá) 22506
Back to top