API REFERENCE

Iniciar pagamento ou autorização

YabandPay documentation·Atualizado em 26 de out. de 2026

Parâmetros

Parameter	Type	Descrição	Obrigatório
data.pay_method	string	offline	✓
data.sub_pay_method	string	point_of_sales	✓
data.operation	string	1.Sales 2.Authorisation；	✓
data.tid	string	设备的TID	✓
data.order_id	string	订单号全部数字构成，并小于20个字符	✓
data.amount	string	金额数字。例如 € 24.99 应该写成24.99，CNY金额>=1，欧元金额>=0.1	✓
data.tip_amount	string	总金额中包含的小费，金额数字。例如 1.02	—
data.currency	string	货币代码，ISO 4217，例如EUR，CHF	✓
data.description	string	订单描述64字符内	✓
data.demo	string	自定义字段	—
data.notify_url	string	支付完成后异步通知地址	✓
data.request_id	string	请求id需保持唯一，建议24以上位数字+字母	✓

Aplicável a pagamentos presenciais em POS

Esta API envia instruções de pagamento ou autorização para um dispositivo POS através da nuvem.

Antes de chamar esta API, confirme que o dispositivo POS está ligado e disponível, para que as instruções possam ser entregues e processadas com sucesso.

API URL (production): https://mapi.yabandpay.com/Payments

API URL (test): https://acc-mapi.yabandpay.com/Payments

Parâmetro	Tipo	Descrição	Obrigatório
user	String	Device TID	Obrigatório
sign	String	Signature	Obrigatório
method	String	v3.POS	Obrigatório
time	Long	Timestamp	Obrigatório

Parameters

Parâmetro	Tipo	Descrição	Obrigatório
pay_method	String	offline	Obrigatório
sub_pay_method	String	point_of_sales	Obrigatório
operation	String	1.Sales 2.Authorisation；	Obrigatório
tid	string	Device TID	Obrigatório
order_id	string	Número do pedido composto apenas por dígitos e com menos de 20 caracteres	Obrigatório
amount	String	Montante em formato de cadeia numérica. Por exemplo, introduza 24.99 para € 24.99. Montante em CNY >=1; montante em EUR >=0.1.	Obrigatório
tip_amount	String	Gorjeta incluída no montante total, em formato de cadeia numérica; por exemplo, 1.02	Opcional
currency	String	Código de moeda ISO 4217, por exemplo EUR ou CHF	Obrigatório
description	String	Descrição do pedido, com até 64 caracteres	Obrigatório
demo	String	Campo personalizado	Opcional
notify_url	String	URL de notificação assíncrona após o pagamento	Obrigatório
request_id	String	ID de pedido único; recomenda-se uma combinação de letras e números com pelo menos 24 caracteres	Obrigatório

Signature example:

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

 "amount=12.5&currency=EUR&description=YabandPay test&method=v3.POS&notify_url=https://www.yabandpay.com/notify&operation=1&order_id=202586556498441613&pay_method=offline&request_id=a7z1lox4l6z6mdx1udgn5gtezasze1x0&sub_pay_method=point_of_sales&tid=T125119061&time=1555498137&tip_amount=0.5&user=T125119061"

Assine a stringA utilizando secret_key

A assinatura resultante é:

"YOUR_SIGNATURE"

Request example:

 {
  "user": "T125119061",
  "sign": "YOUR_SIGNATURE",
  "method": "v3.POS",
  "time": 1555498137,
  "data": {
    "operation": "1",
    "tid": "T125119061",
    "amount": "12.5",
    "currency": "EUR",
    "tip_amount": "0.5",
    "description": "YabandPay test",
    "notify_url": "https://www.yabandpay.com/notify",
    "order_id": "YOUR_ORDER_ID",
    "pay_method": "offline",
    "sub_pay_method": "point_of_sales",
    "request_id": "a7z1lox4l6z6mdx1udgn5gtezasze1x0"

  }
}

Response example:

{
  "status": true,
  "code": "200",
  "data": {
    "order_id": "YOUR_ORDER_ID",
    "trade_id": "4552eeea-1ae8-1e40-3b4b-802dc2f56458",
    "amount": "12",
    "currency": "EUR",
    "tip_amount": "0.5",
    "state": "processing"
  },
  "message": ""}

Additional information:

Dica

Importante: quando uma notificação assíncrona devolve "state": "paid", o utilizador concluiu o pagamento. Verifique se os dados devolvidos contêm "cvmTypeList": ["SIGNATURE"].

Se a resposta contiver "cvmTypeList": ["SIGNATURE"], o cliente tem de assinar o recibo;

Peça ao operador de caixa que solicite a assinatura do cliente e imprima um recibo com um campo para assinatura;

Depois de o cliente assinar, o operador de caixa seleciona “Confirm signature” ou “Invalid signature”, conforme a assinatura.

Se for selecionado “Confirm signature”, a transação é concluída normalmente;

Se for selecionado “Invalid signature”, chame imediatamente a API de reversão da transação para a reverter;

Em pagamentos sem operador ou de autosserviço, a verificação da assinatura pode ser omitida, uma vez que os montantes são geralmente baixos; no entanto, isso acarreta risco de estorno.

Response result:

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

Recomendamos vivamente utilizar tanto as consultas de pedidos como as notificações assíncronas para sincronizar e atualizar o estado do pagamento e manter as informações corretas em tempo real.

Response codes:

Status	Code	Message
true	200	Success
false	-1000	Internal error
false	-3001	Required field is missing
false	-3002	duplicate request_id
false	-403	The signature Error
false	-4011	Not support the payment method

Iniciar pagamento ou autorização