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	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)
email	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	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}}

Request Headers

{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

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

Request Headers

{
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

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