Skip to content

Wallet

Integration Guide

When receiving the 'qrCode' fields are retrieved from the response, follow the process below to complete the payment.

  1. Select the wallet you want to pay for.

  2. Scan the QR code from your wallet.

  3. Check the amount and confirm payment.

We support the following wallet: Plin, Yape, Interbank, BBVA, Scotiabank, Izipay, Agora, Sodexo, Ligo, Bim, MobileCard, Diners Club, Tarjeta W, Kontigo.

HTTP Request

POST /v1/payments/charges/wallet

Request Headers
{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}
Request Body
{
    "idempotencyKey": "ca756fd1-3c43-4dc2-af11-6a8770ff7e35",
    "amount": 500,
    "currency": "PEN",
    "country": "PE",
    "paymentMethod": "WALLET",
    "paymentFlow": "DIRECT",
    "payer": {
        "name": "username",
        "email": "username@liquido.com",
        "phone": "+51 1234567890",
        "document": {
            "documentId": "700123456",
            "type": "DNI"
        },
        "billingAddress": {
            "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": "PE"
        }
    },
    "orderInfo": {  
        "orderId": "test-order-id",  
        "shippingInfo": { 
            "name": "shipping test name",  
            "phone": "shipping phone",  
            "email": "shipping@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": "PE"
            }
        }
    },
    "description": "this is a test payment",
    "callbackUrl": "https://api.client.com/callback/",
    "subMerchantId": "UUID"
}
Content-Type: application/json
{
    "transferStatusCode": 200,
    "transferErrorMsg": null,
    "idempotencyKey": "ca756fd1-3c43-4dc2-af11-6a8770ff7e35",
    "referenceId": "ca756fd1-3c43-4dc2-af11-6a8770ff7e35",
    "paymentMethod": "WALLET",
    "amount": 500,
    "currency": "PEN",
    "country": "PE",
    "finalAmount": 500,
    "finalCurrency": "PEN",
    "createTime": "2025-02-01 22:29:40 GMT-07:00",
    "scheduledTime": "2025-02-01 22:29:40 GMT-07:00",
    "payer": {
        "name": "username",
        "email": "username@example.com",
        "phone": "+51 1234567890",
        "document": {
            "documentId": "700123456",
            "type": "DNI"
        },
        "billingAddress": {
            "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": "PE"
        }
    },
    "transferStatus": "IN_PROGRESS",
    "description": "this is a test payment",
    "callbackUrl": "https://api.client.com/callback/",
    "transferDetails": {
        "wallet": {
            "expiresAt": 1739677220,
            "referenceNumber": "57180404",
            "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACSklEQVR4XmP4jwp+MIwKjAqQLHAgST86c5qBPFzgflSYwpf87ffhAhdLV8VK3zCJRwgEfusu3bYFSaBOM0B+O5LA/fAn03P0yxFmHAgFgQB5uMD/VwvCrQ7NB7EgAgcZjy2oNVq1Hy7w94NxsO6D2wgtR2xMuV4YOtfDBR6uVorpvfAXIXDAwJj5hZEWiAkR+Pr20byVn+7FwwWuRv8+XcDNZA8XeH9x6mz2A2cRZlzgvLA0c9kmhBlnN+lHZj66Jw8XOBG4/M8nVieElsfvdsUKH5iDEDjBu/jQW/Vd9nCBY33n1Oy/3UWYcZxP6HOOvSuICXX6E3/Vz9fmIrSc5Tq2m0Vp13yEluOLwwM/3UeYcYfVYwKPNmM9XODr1dvPuUPuxsMFboZzbE3ZJQJiQgSeXiufnvvhDsKME9IXFpT4I5lx/cH/T/0PmhFmXNAJ2Jr5zWc/XODgvvVRmY+bEGZ81LrnWab8GmHGxT/7goRvdiEE7tekT/+y/gtC4FyL5q3Yhafi4QInU5/01xj/kIcL3PxucWn1pcUILS/9F+z9u+kXiAkROLKvPEhz03mElivp5jF1+rYILXf3pYlL329GCHxgvFxTuynmPlzg2JdFs3Q/IaWxa6U3X5fk1yO0HFy7/Nq8Be32cIH//BcWVD47cB8hcGN9uM5ipDA94PnH1HjRlXq4wP28/9O5T8TEwwUuBi4+ULrvoD1CwO2eyu+FaxFaLnoJ/X5jfhrJjEC/HZ8uv0QIHHB6sJt18aX9cAEkMCowKkCaAADtjgBGQclv0AAAAABJRU5ErkJggg=="
        }
    },
    "subMerchantId": "UUID"
}

Notification / Callback

Content-Type: application/json
{
    "eventType": "CHARGE_SUCCEEDED",
    "data": {
        "chargeDetails": {
            "transferStatusCode": 200,
            "transferErrorMsg": null,
            "idempotencyKey": "ca756fd1-3c43-4dc2-af11-6a8770ff7e35",
            "referenceId": "ca756fd1-3c43-4dc2-af11-6a8770ff7e35",
            "paymentMethod": "WALLET",
            "amount": 500,
            "currency": "PEN",
            "country": "PE",
            "finalAmount": 500,
            "finalCurrency": "PEN",
            "createTime": "2025-02-01 22:29:40 GMT-07:00",
            "scheduledTime": "2025-02-01 22:29:40 GMT-07:00",
            "finalStatusTime": "2025-02-01 23:00:34 GMT-07:00",
            "payer": {
                "name": "username",
                "email": "username@example.com",
                "phone": "+51 1234567890",
                "document": {
                    "documentId": "700123456",
                    "type": "DNI"
                },
                "billingAddress": {
                    "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": "PE"
                }
            },
            "transferStatus": "SETTLED",
            "description": "this is a test payment",
            "callbackUrl": "https://api.client.com/callback/",
            "transferDetails": {
                "wallet": {
                    "expiresAt": 1739677220,
                    "referenceNumber": "57180404",
                    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAH0AAAB9AQAAAACn+1GIAAACSklEQVR4XmP4jwp+MIwKjAqQLHAgST86c5qBPFzgflSYwpf87ffhAhdLV8VK3zCJRwgEfusu3bYFSaBOM0B+O5LA/fAn03P0yxFmHAgFgQB5uMD/VwvCrQ7NB7EgAgcZjy2oNVq1Hy7w94NxsO6D2wgtR2xMuV4YOtfDBR6uVorpvfAXIXDAwJj5hZEWiAkR+Pr20byVn+7FwwWuRv8+XcDNZA8XeH9x6mz2A2cRZlzgvLA0c9kmhBlnN+lHZj66Jw8XOBG4/M8nVieElsfvdsUKH5iDEDjBu/jQW/Vd9nCBY33n1Oy/3UWYcZxP6HOOvSuICXX6E3/Vz9fmIrSc5Tq2m0Vp13yEluOLwwM/3UeYcYfVYwKPNmM9XODr1dvPuUPuxsMFboZzbE3ZJQJiQgSeXiufnvvhDsKME9IXFpT4I5lx/cH/T/0PmhFmXNAJ2Jr5zWc/XODgvvVRmY+bEGZ81LrnWab8GmHGxT/7goRvdiEE7tekT/+y/gtC4FyL5q3Yhafi4QInU5/01xj/kIcL3PxucWn1pcUILS/9F+z9u+kXiAkROLKvPEhz03mElivp5jF1+rYILXf3pYlL329GCHxgvFxTuynmPlzg2JdFs3Q/IaWxa6U3X5fk1yO0HFy7/Nq8Be32cIH//BcWVD47cB8hcGN9uM5ipDA94PnH1HjRlXq4wP28/9O5T8TEwwUuBi4+ULrvoD1CwO2eyu+FaxFaLnoJ/X5jfhrJjEC/HZ8uv0QIHHB6sJt18aX9cAEkMCowKkCaAADtjgBGQclv0AAAAABJRU5ErkJggg=="
                }
            },
            "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=1PEN
country String country code
currency String The currency code of the transferred fund
paymentMethod String payment method, enum value as WALLET
paymentFlow String payment flow, DIRECT
payer JSON payer info
orderInfo JSON order 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.
subMerchantId String The sub merchant ID. Required for PSPs.
riskData JSON The risk data of the payment. MERCHANT_APP_NAME or MERCHANT_WEBSITE must be provided in risk Data. Please see here for further details.

Create A Payment With Risk Data

Please see here for further details.

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.
document JSON document info
phone String Mobile phone number. Should include “+51” as a prefix.
billingAddress JSON Billing address info.

Document Object Parameters

Parameter Required Type Description
documentId String document number.
type String document type, enum value as DNI, RUC, PERU_CE, PERU_PASSPORT_ID
BillingAddress Object Parameters
Parameter Required Type Description
zipCode String zip code.
state String state.
city String city name.
street String street name.
number String street number.
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 Mobile phone number. Should include “+51” as a prefix.
email String email address
address JSON the same as billingAddress

Response Body Parameters

Parameter Type Description
transferStatus String Transfer status, SETTLED, IN_PROGRESS, FAILED
transferStatusCode Integer 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 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 WALLET
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.
TransferDetails Object Parameters
Parameter Type Description
wallet JSON The e-wallet payment details

BankTransfer Object Parameters

Parameter Type Description
expirationAt Long The timestamp of payment expiration
referenceNumber String The reference number of the payment
qrCode String The Base64-encoded QR code image URI

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