PayCash single payment generates references that can be used for only one time, while a Recurring Payment allows you to get a reference that can be used for multiple times.
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 difference offline collection points, please check the details in Agreement Codes.
{"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"},"callbackUrl":"https://api.client.com/callback/","description":"this is a test pay","expirationDate":"2022-10-31","recurring":false,"subMerchantId":"UUID"}
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}},"subMerchantId":"UUID"}
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"}},"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
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
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
subMerchantId
String
The sub merchant ID. Required for PSPs.
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
subMerchantId
String
The sub merchant ID.
Object Parameters
Payer
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. Should include “+57” as a prefix.
billingAddress
JSON
Billing address info.
BillingAddress
Parameter
Required
Type
Description
zipCode
String
zip code.
state
String
state.
city
String
city name.
street
String
street name.
number
String
street number.
OrderInfo
Parameter
Required
Type
Description
orderId
String
order identity number
shippingInfo
JSON
shipping info
ShippingInfo
Parameter
Required
Type
Description
name
String
shipping name
phone
String
Mobile phone number. Should include “+57” as a prefix.
email
String
email address
address
JSON
the same as billingAddress
RiskData
Parameter
Required
Type
Description
ipAddress
String
Payer's IP address
TransferDetails
Parameter
Type
Description
payCash
JSON
The payCash details
PayCash
Parameter
Type
Description
referenceNumber
String
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.
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.