API REFERENCE

Cartão-presente

YabandPay documentation·Atualizado em 26 de out. de 2026

Parâmetros

Parameter	Type	Descrição	Obrigatório
data.pay_method	string	online	✓
data.sub_pay_method	string	Voucher	✓
data.order_id	string	商户的订单ID	✓
data.amount	string	金额数字。例如 € 24.99 应该写成24.99，欧元金额>=1	✓
data.currency	string	EUR	✓
data.description	string	订单描述	✓
data.demo	string	自定义字段	—
data.timeout	string	过期时间单位分钟(0-1440)	✓
data.redirect_url	string	如果使用托管页面，支付完成后跳转地址	—
data.notify_url	string	支付完成后异步通知地址	✓
data.cardnumber	string	礼品卡卡号（如使用页面跳转托管方式非必填）	—
data.pincode	string	礼品卡密码（如传cardnumber该字段必填）	—

Aplicável a: cartões-presente

Este método de pagamento utiliza o saldo de um cartão-presente para pagar um pedido. Os cartões-presente têm de ser ativados no ponto de venda.

Parâmetro	Tipo	Descrição	Obrigatório
user	String	Conta do operador de caixa UID	Obrigatório
sign	String	Signature	Obrigatório
method	String	v3.CreatePaymentsVoucher	Obrigatório
time	Long	Timestamp	Obrigatório

Parameters

Parâmetro	Tipo	Descrição	Obrigatório
pay_method	String	online	Obrigatório
sub_pay_method	String	Voucher	Obrigatório
order_id	String	ID do pedido do comerciante	Obrigatório
amount	String	Montante numérico. Por exemplo, € 24.99 deve ser indicado como 24.99; montante em euros >=1	Obrigatório
currency	String	EUR	Obrigatório
description	String	Descrição do pedido	Obrigatório
demo	String	Campo personalizado	Opcional
timeout	String	Tempo de expiração em minutos (0-1440)	Obrigatório
redirect_url	String	URL de redirecionamento após a conclusão do pagamento, ao utilizar a página alojada	Opcional
notify_url	String	URL de notificação assíncrona após o pagamento	Obrigatório
cardnumber	String	Número do cartão-presente (não obrigatório ao redirecionar para a página alojada)	Opcional
pincode	String	PIN do cartão-presente (obrigatório se cardnumber for fornecido)	Opcional

Signature example:

Parâmetros ordenados e concatenados numa cadeia de consulta no formato de URL

"amount=0.01&cardnumber=6064364245787814896&currency=EUR&demo=test&description=YabandPay test VVV&method=v3.CreatePaymentsVoucher&notify_url=https://www.yabandpay.com/notify&order_id=202405110140188881&pay_method=online&pincode=568971&redirect_url=https://www.yabandpay.com&sub_pay_method=Voucher&time=1546588959&timeout=0&user=YOUR_CASHIER_UID"

Assine a stringA utilizando secret_key

A assinatura resultante é:

"YOUR_SIGNATURE"

Request example:

{
    "user": "YOUR_CASHIER_UID",
    "sign": "YOUR_SIGNATURE",
    "method": "v3.CreatePaymentsVoucher",
    "time": 1546588959,
    "data": {
        "description": "YabandPay test VVV",
        "timeout": "0",
        "pay_method": "online",
        "sub_pay_method": "Voucher",
        "order_id": "YOUR_ORDER_ID",
        "amount": "0.01",
        "currency": "EUR",
        "redirect_url": "https://www.yabandpay.com",
        "notify_url": "https://www.yabandpay.com/notify",
        "demo": "test",
        "cardnumber": "6064364245787814896",
        "pincode": "568971"
    }
}

Response example:

{
    "status": true,
    "code": "200",
    "data": {
        "order_id": "YOUR_ORDER_ID",
        "trade_id": "535ea4a1-917a-bc14-58e2-d1565720af90",
        "amount": "0.01",
        "currency": "EUR",
        "settlement_amount": "0.01",
        "settlement_currency": "EUR",
        "exchange_rate": "1",
        "url": "",
        "state": "processing"
    },
    "message": ""
}

Integração da página alojada:

Utilize este método para validar o número e o PIN do cartão-presente na página alojada pela YabandPay. Neste caso, não envie cardnumber nem pincode. Após a chamada da API, redirecione para o url devolvido para continuar o fluxo de pagamento.

Request example:

{
    "user": "YOUR_CASHIER_UID",
    "sign": "YOUR_SIGNATURE",
    "method": "v3.CreatePaymentsVoucher",
    "time": 1546588959,
    "data": {
        "description": "YabandPay test VVV",
        "timeout": "0",
        "pay_method": "online",
        "sub_pay_method": "Voucher",
        "order_id": "YOUR_ORDER_ID",
        "amount": "0.01",
        "currency": "EUR",
        "redirect_url": "https://www.yabandpay.com",
        "notify_url": "https://www.yabandpay.com/notify",
        "demo": "test"
    }
}

Response example:

{
    "status": true,
    "code": "200",
    "data": {
        "order_id": "YOUR_ORDER_ID",
        "trade_id": "c0d9c0bb-0b40-1cb6-7373-fd1a97c7124e",
        "amount": "0.01",
        "currency": "EUR",
        "url": "https://pay.yabandpay.com/payments/callback/order/YzBkOWMwYmItMGI0MC0xY2I2LTczNzMtZmQxYTk3YzcxMjRl",
        "state": "processing"
    },
    "message": ""
}

Additional information:

Response result:

Um pedido bem-sucedido devolve "status": true.
Um pedido mal-sucedido devolve "status": false.

Recomendamos vivamente utilizar Query Order e Asynchronous Notifications para manter os estados dos pagamentos corretos e atualizados.

Response codes:

Status	Code	Message
true	200
false	-1000	Internal error
false	-104000	You have entered an invalid amount
false	-104221	The voucher has insufficient funds
false	-104222	Invaild PinCode
false	-104223	This is an invalid giftcard, we are unable to find the giftcard brand

Cartão-presente