Skip to content

Create A Payment

Create A Credit Card Payment

When the user pays with a credit card for the first time, the user needs to provide the credit card information in the request. The response will return a card ID. When paying with the same card in the future, the user can use the card ID to initiate a request.

HTTP Request

POST /v1/payments/charges/card

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

create a card payment with card info

Request Body
{
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "amount": 100,
    "currency": "BRL",
    "country": "BR",
    "paymentMethod": "CREDIT_CARD",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "53023315540",
            "type": "CPF"
        },
        "phone": "12345678901",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "card": {
        "cardHolderName": "card_holder_name",
        "cardNumber": "4581243338680000",
        "expirationMonth": 9,
        "expirationYear": 2024,
        "cvc": "123"
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "shipping phone",  
            "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": "BR"
            }
        }
    },
    "riskData": {
        "ipAddress":"192.0.0.130",
        "customProperties": {
            "merchantId":"1527558812935028000",
            "merchantName":"LIQUIDO PTE. LTD."
      }
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/"
}

create a card payment with card id

Request Body
{
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "amount": 100,
    "currency": "BRL",
    "country": "BR",
    "paymentMethod": "CREDIT_CARD",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "53023315540",
            "type": "CPF"
        },
        "phone": "12345678901",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237",
    "riskData": {
        "ipAddress":"192.0.0.130",
        "customProperties": {
            "merchantId":"1527558812935028000",
            "merchantName":"LIQUIDO PTE. LTD."
      }
    },
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/"
}

Response

Content-Type: application/json
{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
    "paymentMethod": "CREDIT_CARD",
    "amount": 100,
    "currency": "BRL",
    "country": "BR",
    "finalAmount": 100,
    "finalCurrency": "BRL",
    "createTime": "2022-03-01 17:53:18 GMT-08:00",
    "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
    "finalStatusTime": "2022-03-01 17:53:18 GMT-08:00",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "document": {
            "documentId": "53033315550",
            "type": "CPF"
        },
        "phone": "12345678901",
        "billingAddress": {  
            "zipCode": "04849333",
            "state": "SP",
            "city": "sao paulo",
            "district": "Jardim Gaivotas",
            "street": "Rua 9 de setembro",
            "number": "15",
            "complement": "casa",
            "country": "BR"
        }
    },
    "transferDetails": {
        "card": {
            "cardInfo": {
                "cardHolderName": "card_holder_name",
                "expirationMonth": 9,
                "expirationYear": 2024,
                "brand": "VISA",
                "bin": "458124",
                "last4": "0000"
            },
            "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
        }
    },
    "transferStatus": "SETTLED",
    "description": "this is a test pay",
    "callbackUrl": "https://api.client.com/callback/"
}

Notification / Callback

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
        "data":  {
            "chargeDetails": {
                "transferStatusCode": 200,
                "transferErrorMsg": null,
                "idempotencyKey": "1ec983fa-1a37-679b-809b-067861d87ab0",
                "referenceId": "1ec983fa-1a37-679b-809b-067861d87ab0",
                "paymentMethod": "CREDIT_CARD",
                "amount": 100,
                "currency": "BRL",
                "country": "BR",
                "finalAmount": 100,
                "finalCurrency": "BRL",
                "createTime": "2022-03-01 17:53:18 GMT-08:00",
                "scheduledTime": "2022-03-01 17:53:18 GMT-08:00",
                "finalStatusTime": null,
                "payer": {
                    "name": "username",
                    "email": "username@liquido.com",
                    "document": {
                        "documentId": "53033315550",
                        "type": "CPF"
                    },
                    "phone": "12345678901",
                    "billingAddress": {  
                        "zipCode": "04849333",
                        "state": "SP",
                        "city": "sao paulo",
                        "district": "Jardim Gaivotas",
                        "street": "Rua 9 de setembro",
                        "number": "15",
                        "complement": "casa",
                        "country": "BR"
                    }
                },
            "transferStatus": "SETTLED",
            "transferDetails": {
                "card": {
                    "cardInfo": {
                        "cardHolderName": "card_holder_name",
                        "expirationMonth": 9,
                        "expirationYear": 2024,
                        "brand": "VISA",
                        "bin": "458124",
                        "last4": "0000"
                    },
                    "cardId": "8736453a-dad0-4f26-85f0-95e8787d0237"
                }
            },
            "description": "this is a test pay",
            "callbackUrl": "https://api.client.com/callback/"
        }
    }
}

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=1BRL
country String country code
currency String The currency code of the transferred fund
paymentMethod String payment method, enum value as CREDIT_CARD
paymentFlow String payment flow, enum value as DIRECT or REDIRECT
payer JSON payer info
card JSON credit card info. required if card id is empty.
cardId String card id. required if card info is empty.
capture Boolean set to false to create an authorization
installments Integer number of installments
orderInfo JSON order info
riskData JSON risk control info, if PSP, please add sub-merchant here, example as "customProperties":{"merchantId":"1527558812935028000","merchantName":"LIQUIDO PTE. LTD."}
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
transferStatus String Transfer status, SETTLED, IN_PROGRESS, AUTHORIZED, FAILED
transferStatusCode int Transfer status code, 200 transaction SETTLED, IN_PROGRESS or AUTHORIZED, 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 Long 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 CREDIT_CARD, PIX_STATIC_QR
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.
createdTime String Payment ticket created time
scheduledTime String Payment ticket scheduled time
finalStatusTime String Transfer final status update time, final status include SETTLED, FAILED

Create A Credit Card Payment With Card Id

Please see here for further details.

Create A Credit Card Authorization

Please see here for further details.

Create A Credit Card Payment With Installments

Please see here for further details.

Create A Credit Card Redirect Payment

Please see here for further details.


Object Parameters

Payer Object Parameters

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.
document JSON Wallet holder identity proof, such as CPF for Brazil.
billingAddress JSON Billing address info.

document Object Parameters

Parameter Required Type Description
documentId String identity number
type String enum of CPF or CNPJ

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.

orderInfo Object Parameters

Parameter Required Type Description
orderId String order identity number
shippingInfo JSON shipping info

shippingInfo Object Parameters

Parameter Required Type Description
name String shipping name
phone String phone number
email String email address
address JSON the same as billingAddress

Card Object Parameters

Parameter Required Type Description
cardHolderName String Cardholder's full name.
cardNumber String 16 digit number of the card, as a string without any separators.
cvc String Credit card verification code.
expirationMonth Integer Two digit number representing the card's expiration month.
expirationYear Integer Four digit number representing the card's expiration year.

RiskData Object Parameters

Parameter Required Type Description
ipAddress String Payer's IP address
customProperties JSON Key/value pairs used to store additional custom metadata

transferDetails Object Parameters

Parameter Type Description
card JSON card detail info

card Object in transferDetails Parameters

Parameter Type Description
cardInfo JSON card detail info
cardId String card id, can use it to create a card payment instead of card info
installments Integer number of installments

CardInfo Object in response Parameters

Parameter Type Description
cardHolderName String Cardholder's full name.
bin String first 6 digit number of the card
last4 String last 4 digit number of the card
brand String Credit card brand. such as VISA, MASTERCARD
expirationMonth Integer Two digit number representing the card's expiration month.
expirationYear Integer Four digit number representing the card's expiration year.

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.
REFUNDING The transaction of this payment is refunding.
REFUNDED The transaction of this payment method has been refunded.
CHARGED_BACK The transaction of this payment has been reported as chargeback.
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;
Back to top