Utility Payment
Utility payment
Register a payment
Register a payment for the bills of life services
HTTP Request
POST /v1/marketplace/sales/utility
Request Headers
{
"Content-Type": "application/json",
"Authorization": "Bearer {{access_token}}",
"x-api-key": "{{api_key}}"
}
Request Body
{
"idempotencyKey": "280a03fc-2255-11eb-adc1-0242ac120002",
"merchantName":"CFE",
"referenceNumber":"972101002847",
"amount":123,
"countryCode":"MX",
"currency": "MXN",
"paymentType":"PAY_WITH_LINK",
"allowPaymentMethods": [
"BANK_TRANSFER_MX",
"CREDIT_CARD"
],
"targetPhoneNumber": "+5511999999999",
"email": "liquido-test@gmail.com",
"billingAddress": {
"zipCode": "04849333",
"state": "SP",
"city": "sao paulo",
"district": "Jardim Gaivotas",
"street": "Rua 9 de setembro",
"number": "15",
"complement": "casa",
"country": "MX"
},
"callbackUrl": "https://your-domain/callback/",
"redirectUrl": "https://your-domain/checkout-page"
}
Response
Content-Type: application/json
{
"statusCode": 200,
"errorMsg": "",
"idempotencyKey": "7e18e719-0000-0716-a92a-2b4faeb70008",
"transactionId": "20210715-175206-145-0369-0449",
"transactionStatus": "IN_PROGRESS",
"transactionStatusCode": 200,
"transactionErrorMsg": ""
}
HTTP Headers Parameters
Key | Value |
---|---|
Content-Type | application/json |
x-api-key | {{api_key}} |
Request Body Parameters
Parameter | Required | Type | Description |
---|---|---|---|
idempotencyKey | String | Unique key to ensure idempotent requests, no longer than 128 bits | |
merchantName | String | Merchant name | |
referenceNumber | String | Reference number of the bill | |
amount | int | Amount | |
countryCode | String | Country abbreviation, following ISO 3166-1 alpha-2 code standard, 2 bits, eg. BR, MX | |
currency | String | Currency type, eg MXN for Mexico | |
paymentType | String | Payment type, enumeration value: PREPAID, COUPON_CODE、PAY_WITH_LINK, do not fill in the default PREPAID | |
allowPaymentMethods | String | Declare which payment methods are included in the payment page. The default value is CREDIT_CARD. (Only when the payment type is PAY_WITH_LINK may need to be filled in) | |
targetPhoneNumber | String | Mobile phone number (only if the payment type is PAY_WITH_LINK) | |
String | Email (only if the payment type is PAY_WITH_LINK) | ||
billingAddress | String | Billing address. If the merchant pre-collected the user's billing address before the payment process, it can send it to liquido when creating the payment link. This information can be used to pre-fill the Boleto payment form. (Only when the payment type is PAY_WITH_LINK may need to be filled in) | |
callbackUrl | String | When the payment status changes, liquido will send a post request to the callbackUrl. | |
redirectUrl | String | When the redirectUrl is not empty, the payment link will be redirected to the redirectUrl after successful payment. (Only when the payment type is PAY_WITH_LINK may need to be filled in) |
AllowPaymentMethods Object Parameters
Payment Method | Country | Limit |
---|---|---|
CREDIT_CARD | BR, MX, CO | |
PIX | BR | |
BOLETO | BR | > 500BRL |
BANK_TRANSFER_BR | BR | |
BANK_TRANSFER_MX | MX | |
PAY_CASH | MX, CO | |
PSE | CO | >1500COP |
NEQUI | CO | >1500COP |
BillingAddress Object Parameters
Parameter | Required | Type | Description |
---|---|---|---|
zipCode | String | zip code. such as CEP in Brazil | |
state | String | state. should be abbreviation, such as SP in Brazil | |
city | String | city name. | |
district | String | district name. | |
street | String | street name. | |
number | String | street number. | |
complement | String | complement info. | |
country | String | country code. |
Response Body Details
Parameter | Type | Description |
---|---|---|
statusCode | int | Status code, 200 success, 401 access denied, 422 parameter error, 500 internal error |
errorMsg | String | If transaction failed, return error message |
idempotencyKey | String | Unique key to ensure idempotent requests |
transactionId | String | Transaction ID, sometime will be empty when processing |
transactionStatus | String | Transaction status, enumeration as SETTLED, IN_PROGRESS or FAILED |
transactionStatusCode | int | Transaction status code, 200 success or processing, other meaning transaction failed |
transactionErrorMsg | String | Error message of the failed transaction |
Check Transfer Status
Check the status of the bill payment by idempotencyKey.
HTTP Request
GET /v1/marketplace/sales/utility/key/{{idempotencyKey}}
Response
Content-Type: application/json
{
"statusCode": 200,
"errorMsg": "",
"idempotencyKey":"280a03fc-2255-11eb-adc1-0242ac120001",
"transactionId":"09461d96-2252-11eb-adc1-0242ac120002",
"transactionStatus":"SETTLED",
"transactionStatusCode": 200,
"transactionErrorMsg": "",
"merchantName": "CFE",
"price": "10",
"priceInCents": "1000",
"currency": "MXN",
"createTime": "{{Utility_CREATE_TIME}}",
"finalStatusTime": "{{Utility_FINAL_STATUS_TIME}}",
"referenceNumber": "972101002847"
}
HTTP Headers Details
Key | Value |
---|---|
x-api-key | {{api_key}} |
Content-Type | application/json |
PATH and Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
idempotencyKey | String | Unique key to ensure idempotent requests |
Response Body Details
Parameter | Type | Description |
---|---|---|
statusCode | int | Status code, 200 success, 401 access denied, 422 parameter error, 500 internal error |
errorMsg | String | If transaction failed, return error message |
idempotencyKey | String | Unique key to ensure idempotent requests |
transactionId | String | Transaction ID, sometime will be empty when processing |
transactionStatus | String | Transaction status, enumeration as SETTLED, IN_PROGRESS or FAILED |
transactionStatusCode | int | Transaction status code, 200 success or processing, other meaning transaction failed |
transactionErrorMsg | String | Error message of the failed transaction |
merchantName | String | Merchant name |
price | String | Utility services amount |
priceInCents | Long | Gift card amount.The minimum settlement granularity of the current currency, such as 100=1BRL |
currency | String | Utility services currency type, eg BRL for Brazil |
createTime | Time | Utility services purchase request creation time |
finalStatusTime | Time | Utility services purchase request completed time |
referenceNumber | String | Reference number of the bill |
Query Providers
Get available utility services providers.
HTTP Request
GET /v1/marketplace/sales/utility/{{countryCode}}/merchants
Response
Content-Type: application/json
{
"statusCode":200,
"errorMsg": "",
"merchants": [
{
"merchantId": "166",
"merchantName": "CFE",
"iconUrl": "https://gestopago.portalventas.net/sistema/images/gestopago/servicios/166.png",
"description": "Pago de Servicios (Energía)"
},
{
"merchantId": "756",
"merchantName": "ENGIE MAXIGAS",
"iconUrl": "https://gestopago.portalventas.net/sistema/images/gestopago/servicios/756.png",
"description": "Pago de Servicios (Energía)"
}
]
}
HTTP Headers Details
Key | Value |
---|---|
x-api-key | {{api_key}} |
Content-Type | application/json |
PATH and Query Parameters
Parameter | Type | Description |
---|---|---|
countryCode | String | Country abbreviation, following ISO 3166-1 alpha-2 code standard, 2 bits, eg BR, MX |
Response Body Details
Parameter | Type | Description |
---|---|---|
statusCode | int | Status code, 200 success, 401 access denied, 422 parameter error, 500 internal error |
errorMsg | String | Error message if failed |
merchants | JSON Array | List of utility services provider |
merchantId | String | Merchant ID |
merchantName | String | Merchant name |
iconUrl | String | Merchant icon URL |
description | String | Merchant description |