Skip to content

Gift Cards

Purchase Gift Cards

HTTP Request

POST /sales/gift_cards

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "280a03fc-2255-11eb-adc1-0242ac120002",
    "sku": "NETFLI300",
    "currency": "MXN",
    "countryCode": "MX",
    "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":"280a03fc-2255-11eb-adc1-0242ac120002",
    "transactionId":"20200721-184332-824-3257-1404",
    "transactionStatus": "IN_PROGRESS",
    "transactionStatusCode": 200,
    "transactionErrorMsg": ""
}

HTTP Headers Details

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
sku String gift card SKU
currency String Monetary unit, 3 bytes in length, such as BRL, MXN
countryCode String Country code, 2 bytes in length, such as BR, MX, without default MX
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 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 Order Status

Check for gift card order status

HTTP Request

GET /sales/gift_cards/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": "",
    "sku": "NETFLI300",
    "price": "300",
    "priceInCents": "30000",
    "currency": "MXN",
    "createTime": "{{GIFTCARD_CREATE_TIME}}",
    "finalStatusTime": "{{GIFTCARD_FINAL_STATUS_TIME}}",
    "activationCode": "{{activationCode}}",
    "activationMessage": "{{activationMessage}}"
}

HTTP Headers Details

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

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
sku String Gift card SKU
price String Gift card amount
priceInCents Long Gift card amount.The minimum settlement granularity of the current currency, such as 100=1BRL
currency String Gift card currency type, eg BRL for Brazil
createTime Time Gift card purchase request creation time
finalStatusTime Time Gift card purchase request completed time
activationCode String Gift card activation code
activationMessage String Gift card activation message

Gift Cards Providers

Check for available gift card providers of the designated country.

HTTP Request

GET /sales/gift_cards/{{countryCode}}/merchants

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

Response

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "merchants": [
        {
            "merchantId": "Netflix",
            "merchantName": "Netflix",
            "iconUrl": "https://aws.s3.some.url/netflix.jpeg",
            "description": null
        },
        {
            "merchantId": "Spotify",
            "merchantName": "Spotify",
            "iconUrl": "https://aws.s3.some.url/Spotify.jpeg",
            "description": null
        },
        ......
    ]
}

HTTP Headers Details

Key Value
Content-Type application/json
x-api-key {{api_key}}

PATH and Query Parameters

Parameter Required 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 gift card provider
merchantId String Merchant ID
merchantName String Merchant name
iconUrl String Merchant icon URL
description String Merchant description

Gift Cards Skus List

Get available gift cards skus of the designated country

HTTP Request

GET /sales/giftcards/{{countryCode}}/skus

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

Response

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "sku": "NETFLI150",
            "price": "150",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 150"
        },
        {
            "sku": "NETFLI300",
            "price": "300",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 300"
        },
        ......
        ]
}

HTTP Headers Details

Key Value
Content-Type application/json
x-api-key {{api_key}}

PATH and Query Parameters

Parameter Required 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
skus JSON Array Skus list

sku Object Details

Parameter Type Description
name String Gift card package name
description String Gift card package description
price String Gift card package price. The minimum settlement granularity of the current currency, such as 100=1BRL
currency String Gift card currency type
merchantId String Gift card merchant ID

Get gift card skus of designated merchant

HTTP Request

GET /sales/gift_cards/{{countryCode}}/{{merchantId}}/skus

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

Response

Content-Type: application/json
{
    "statusCode":200,
    "errorMsg": "",
    "skus": [
        {
            "sku": "NETFLI150",
            "price": "150",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 150"
        },
        {
            "sku": "NETFLI300",
            "price": "300",
            "currency": "MXN",
            "merchantId": "Netflix",
            "description": "Netflix 300"
        },
        ......
    ]
}

HTTP Headers Details

Key Value
Content-Type application/json
x-api-key {{api_key}}

PATH and Query Parameters

Parameter Required Type Description
countryCode String Country abbreviation, following ISO 3166-1 alpha-2 code standard, 2 bits, eg BR, MX
merchantId String Gift card merchant ID

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
skus JSON Array Skus list

sku Object Details

Parameter Type Description
name String Gift card package name
description String Gift card package description
price String Gift card package price. The minimum settlement granularity of the current currency, such as 100=1BRL
currency String Gift card currency type
merchantId String Gift card merchant ID
Back to top