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 Peru, 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

RequestResponse

Request Headers

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

Request Body

{
    "idempotencyKey": "06c28bb9-9bbe-4e8b-9064-2a23daff914d",
    "paymentMethod": "PAY_CASH",
    "country": "PE",
    "currency": "PEN",
    "amount": 0,
    "expirationDate": "2025-02-21",
    "description": "this is a test reference",
    "callbackUrl": "https://api.client.com/callback/"
}

Content-Type: application/json

{
    "transferStatusCode": 200,
    "idempotencyKey": "06c28bb9-9bbe-4e8b-9064-2a23daff914d",
    "country": "PE",
    "currency": "PEN",
    "createTime": "2025-02-19 19:38:02 UTC",
    "status": "ACTIVE",
    "description": "this is a test reference",
    "callbackUrl": "https://api.client.com/callback/",
    "transferDetails": {
        "payCash": {
            "amount": 0,
            "expirationDate": "2025-02-21",
            "reference": "7041740022683866"
        }
    }
}

Notification / Callback

Content-Type: application/json

{
    "eventType":"CHARGE_SUCCEEDED",
    "data":{
        "chargeDetails":{
            "transferStatusCode":200,
            "transferErrorMsg":null,
            "idempotencyKey":"06c28bb9-9bbe-4e8b-9064-2a23daff914d",
            "referenceId":"06c28bb9-9bbe-4e8b-9064-2a23daff914d",
            "paymentMethod":"PAY_CASH",
            "amount":1000,
            "currency":"PEN",
            "country":"PE",
            "finalAmount": 1000,
            "finalCurrency": "PEN",
            "createTime": "2025-02-19 19:38:02 UTC",
            "finalStatusTime":"2025-02-20 00:30:55 UTC",
            "payer":{},
            "transferStatus":"SETTLED",
            "description":"this is a test pay",
            "callbackUrl":"https://api.client.com/callback/",
            "transferDetails":{
                "payCash":{
                    "referenceNumber":"7041740022683866",
                    "expirationDate":"2025-02-21",
                    "recurring":true,
                    "paymentTime": "2025-02-19 19:29:20"
                }
            }
        }
    }
}

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.
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=1PEN. 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 100PEN for the first time and pay 200PEN for the second time. If the amount is not ‘0’, eg. it’s ‘50000’, meaning that end customers can only pay fixed amount for 500PEN 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 Peru 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

Collection Points	Agreement Code	Remark
Caja Trujillo	Don't need an agreement code.	Provide a full 16-digit reference
Caja Los Andes	Don't need an agreement code.	Provide a full 16-digit reference
Financiera QAPAQ	Don't need an agreement code.	Provide a full 16-digit reference
Edpyme Alternativa	Don't need an agreement code.	Provide a full 16-digit reference
Caja Paita	Don't need an agreement code.	Provide a full 16-digit reference
Caja Municipal Del Santa	Don't need an agreement code.	Provide a full 16-digit reference
Western Union	Don't need an agreement code.	Provide a full 16-digit reference
Banco Pichincha	Don't need an agreement code.	Provide a full 16-digit reference
Kasnet	220114	Provide a full 16-digit reference
Banco BCP	24162	Provide the last 13 digits of the reference
Yape	Don't need an agreement code.	Provide the last 13 digits of the reference
Agente Cash	Don't need an agreement code.	Provide a full 16-digit reference
BBVA Perú	Don't need an agreement code.	Provide a full 16-digit reference
Interbank	0319901	Provide a full 16-digit reference
IZIPAY	Don't need an agreement code.	Provide a full 16-digit reference
Banco del comercio	Don't need an agreement code.	Provide a full 16-digit reference
Megapunto	Don't need an agreement code.	Provide a full 16-digit reference
Red digital	Don't need an agreement code.	Provide a full 16-digit reference
Niubiz	Don't need an agreement code.	Provide a full 16-digit reference
Caja Arequipa	Don't need an agreement code.	Provide a full 16-digit reference
Banbif	Don't need an agreement code.	Provide the last 14 digits of the reference
FULL CARGA	Don't need an agreement code.	Provide the last 14 digits of the reference
PREXPE	Don't need an agreement code.	Provide the last 14 digits of the reference
ASTROPAY	Don't need an agreement code.	Provide the last 14 digits of the reference
Floid	Don't need an agreement code.	Provide a full 16-digit reference