{"openapi":"3.1.0","info":{"title":"HansaPay Merchant API","version":"1","summary":"Card and wallet payments, refunds and payouts, over signed JSON POSTs.","description":"Every request is a POST with a JSON body, signed with HMAC-SHA256 in four headers. Responses and notifications are signed the same way. Full reference: https://www.hansapay.io/docs (Chinese: https://www.hansapay.io/docs/zh).\n\nResponses share one envelope: `code` 0 means success; anything else is an error, and a failure `msg` usually ends with `|` and a stable key to match on.\n\nError codes:\n\n- 400: Invalid request format\n- 401: Unauthorized\n- 403: Forbidden\n- 422: Business validation error, including duplicate merchant_order_no / merchant_refund_no\n- 500: Internal server error\n- 1001: Merchant account suspended\n- 2002: Order not found\n- 2006: Collection amount does not satisfy channel limits\n- 3003: Payment method not enabled or not currently available\n- 4001: Too many payment requests (HTTP 429); retry shortly\n- 5001: Duplicate payout order\n- 5002: Payout order not found\n- 5004: Insufficient payout balance\n- 5007: Payout method not available\n- 5008: Payout amount does not satisfy channel limits","contact":{"name":"HansaPay support","url":"https://www.hansapay.io/contact","email":"support@hansapay.io"}},"externalDocs":{"description":"Merchant API reference","url":"https://www.hansapay.io/docs"},"servers":[{"url":"https://api-test.hansapay.io","description":"Test"},{"url":"https://api.hansapay.io","description":"Production"}],"tags":[{"name":"Payments","externalDocs":{"url":"https://www.hansapay.io/docs/payments"}},{"name":"Refunds","externalDocs":{"url":"https://www.hansapay.io/docs/refunds"}},{"name":"Payouts","description":"Payouts are available for CASH_APP only. A payout is sent to a Cash App $cashtag, in USD, once payouts are enabled for your account. Until then, and for PAYPAL and PIX, /payouts/create and /payouts/precheck with an amount return code=5007. You can also send a payout from the merchant portal, under Payouts → Send payout.","externalDocs":{"url":"https://www.hansapay.io/docs/payouts"}}],"paths":{"/api/v1/payments/create":{"post":{"operationId":"paymentsCreate","summary":"Create Payment Order (Unified Entry)","description":"Direct payment creation\n\nReference: https://www.hansapay.io/docs/payments#create-payment-order-unified-entry","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"Card payment","type":"object","properties":{"payment_method":{"type":"string","description":"Payment method","enum":["CARD"]},"merchant_order_no":{"type":"string","description":"Merchant order number, max 64 characters, unique across your orders and refunds"},"trans_amount":{"type":"object","properties":{"currency":{"type":"string","description":"3-letter uppercase currency, for example USD. One of the supported currencies (see 1.4)"},"value":{"type":"string","description":"Amount string, for example 99.99: at most 2 decimals, none in JPY, up to 3 in OMR"}},"required":["currency","value"]},"notify_url":{"type":"string","description":"Asynchronous result notification URL"},"return_url":{"type":"string","description":"Frontend return URL after payment"},"trade_info":{"type":"object","properties":{"goods_name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"}},"required":["goods_name"]},"metadata":{"type":"string","description":"Merchant passthrough field, returned unchanged in notifications"},"client_ip":{"type":"string","description":"Client IP recorded by the merchant"},"payer":{"type":"object","properties":{"email":{"type":"string","description":"Payer email"},"mobile":{"type":"string","description":"Payer mobile"},"user_name":{"type":"string","description":"User name"},"user_agent":{"type":"string","description":"Browser UA"},"ext_type":{"type":"string","description":"Channel-specific extra field"},"payer_id":{"type":"string","description":"Wallet-side payer identifier"}}},"card":{"type":"object","properties":{"card_number":{"type":"string","description":"Card number"},"cardholder_name":{"type":"string","description":"Cardholder name"},"exp_month":{"type":"integer","description":"Expiration month, 1-12"},"exp_year":{"type":"integer","description":"Expiration year, 4 digits"},"cvc":{"type":"string","description":"CVV/CVC"}},"required":["card_number","cardholder_name","exp_month","exp_year","cvc"]},"billing_address":{"type":"object","properties":{"country":{"type":"string","description":"2-letter country code, for example US"},"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email"},"phone":{"type":"string","description":"Phone"},"state":{"type":"string","description":"State / province"},"city":{"type":"string","description":"City"},"address":{"type":"string","description":"Address"},"street_number":{"type":"string","description":"Street number"},"postal_code":{"type":"string","description":"Postal code"},"document":{"type":"string","description":"Local document ID if required"}},"required":["country"]},"shipping_address":{"type":"object","properties":{},"additionalProperties":true,"description":"If provided, full shipping address validation applies"},"device_ip":{"type":"string","description":"Public device IP"},"browser":{"type":"object","properties":{"accept":{"type":"string","description":"Browser Accept header"},"user_agent":{"type":"string","description":"Browser UA"},"accept_language":{"type":"string","description":"Language"},"java_enabled":{"type":"boolean","description":"Whether Java is enabled"},"color_depth":{"type":"string","description":"Color depth"},"screen_height":{"type":"string","description":"Screen height"},"screen_width":{"type":"string","description":"Screen width"},"time_zone_offset":{"type":"string","description":"Timezone offset"},"referer":{"type":"string","description":"Referer"}}}},"required":["payment_method","merchant_order_no","trans_amount","notify_url","trade_info","card","billing_address","device_ip"]},{"title":"Wallet payment","type":"object","properties":{"payment_method":{"type":"string","description":"Payment method","enum":["CASH_APP","APPLE_PAY","GOOGLE_PAY","PAYPAL","PIX"]},"merchant_order_no":{"type":"string","description":"Merchant order number, max 64 characters, unique across your orders and refunds"},"trans_amount":{"type":"object","properties":{"currency":{"type":"string","description":"3-letter uppercase currency, for example USD. One of the supported currencies (see 1.4)"},"value":{"type":"string","description":"Amount string, for example 99.99: at most 2 decimals, none in JPY, up to 3 in OMR"}},"required":["currency","value"]},"notify_url":{"type":"string","description":"Asynchronous result notification URL"},"return_url":{"type":"string","description":"Frontend return URL after payment"},"trade_info":{"type":"object","properties":{"goods_name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"}},"required":["goods_name"]},"metadata":{"type":"string","description":"Merchant passthrough field, returned unchanged in notifications"},"client_ip":{"type":"string","description":"Client IP recorded by the merchant"},"payer":{"type":"object","properties":{"email":{"type":"string","description":"Payer email"},"mobile":{"type":"string","description":"Payer mobile"},"user_name":{"type":"string","description":"User name"},"user_agent":{"type":"string","description":"Browser UA"},"ext_type":{"type":"string","description":"Channel-specific extra field"},"payer_id":{"type":"string","description":"Wallet-side payer identifier"},"document":{"type":"string","description":"Payer tax/ID number"}}}},"required":["payment_method","merchant_order_no","trans_amount","notify_url","trade_info"]}]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"oneOf":[{"title":"Card payment","type":"object","properties":{"payment_method":{"type":"string","description":"CARD"},"order_no":{"type":"string","description":"HansaPay order number"},"merchant_order_no":{"type":"string","description":"Merchant order number"},"status":{"type":"string","description":"Order status"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"Amount charged"},"next_action":{"type":"string","enum":["SUCCESS","3DS_VERIFICATION_REQUIRED","PROCESSING","FAILED"],"description":"SUCCESS / 3DS_VERIFICATION_REQUIRED / PROCESSING / FAILED"},"masked_card_number":{"type":"string","description":"Masked card number"},"three_ds_url":{"type":"string","description":"Present when next_action=3DS_VERIFICATION_REQUIRED; redirect the payer to it"},"created_at":{"type":"string","description":"Creation time"}}},{"title":"Wallet payment","type":"object","properties":{"payment_method":{"type":"string","description":"Payment method"},"order_no":{"type":"string","description":"HansaPay order number"},"merchant_order_no":{"type":"string","description":"Merchant order number"},"status":{"type":"string","description":"Order status"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"Amount and currency"},"requested_amount":{"$ref":"#/components/schemas/Amount","description":"The amount you sent, present only when it was rounded to a price point"},"next_action":{"type":"string","enum":["REDIRECT","QRCODE","SUCCESS","FAILED"],"description":"REDIRECT / QRCODE / SUCCESS / FAILED"},"pay_url":{"type":"string","description":"Wallet redirect URL. Present when next_action=REDIRECT"},"qr_code":{"type":"string","description":"Raw QR payment payload. Present when next_action=QRCODE; no available payment method uses it today"},"created_at":{"type":"string","description":"RFC3339 creation time"}}}]}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/payments/checkout":{"post":{"operationId":"paymentsCheckout","summary":"Checkout Payment","description":"Checkout payment creation\n\nReference: https://www.hansapay.io/docs/payments#checkout-payment","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_method":{"type":"string","description":"Payment method","enum":["CARD","APPLE_PAY","GOOGLE_PAY","CASH_APP"]},"merchant_order_no":{"type":"string","description":"Merchant order number, max 64 characters, unique across your orders and refunds"},"trans_amount":{"type":"object","properties":{"currency":{"type":"string","description":"3-letter uppercase currency, for example USD. One of the supported currencies (see 1.4)"},"value":{"type":"string","description":"Amount string, for example 99.99: at most 2 decimals, none in JPY, up to 3 in OMR"}},"required":["currency","value"]},"notify_url":{"type":"string","description":"Asynchronous result notification URL"},"return_url":{"type":"string","description":"Frontend return URL after payment"},"trade_info":{"type":"object","properties":{"goods_name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"}},"required":["goods_name"]},"metadata":{"type":"string","description":"Merchant passthrough field, returned unchanged in notifications"},"client_ip":{"type":"string","description":"Client IP recorded by the merchant"},"payer":{"type":"object","properties":{"email":{"type":"string","description":"Payer email"},"mobile":{"type":"string","description":"Payer mobile"},"user_name":{"type":"string","description":"User name"},"user_agent":{"type":"string","description":"Browser UA"},"ext_type":{"type":"string","description":"Channel-specific extra field"},"payer_id":{"type":"string","description":"Wallet-side payer identifier"},"document":{"type":"string","description":"Payer tax/ID number"}}}},"required":["payment_method","merchant_order_no","trans_amount","notify_url","trade_info"]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"payment_method":{"type":"string","description":"Payment method"},"order_no":{"type":"string","description":"HansaPay order number"},"merchant_order_no":{"type":"string","description":"Merchant order number"},"status":{"type":"string","description":"Order status"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"Amount and currency"},"requested_amount":{"$ref":"#/components/schemas/Amount","description":"The amount you sent, present only when it was rounded to a price point"},"next_action":{"type":"string","description":"Next action"},"token":{"type":"string","description":"Checkout token"},"checkout_url":{"type":"string","description":"Checkout URL"},"created_at":{"type":"string","description":"Creation time"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/payments/query":{"post":{"operationId":"paymentsQuery","summary":"Query Payment Order","description":"Query payment order\n\nReference: https://www.hansapay.io/docs/payments#query-payment-order","tags":["Payments"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order_no":{"type":"string","description":"HansaPay order number"},"merchant_order_no":{"type":"string","description":"Merchant order number"}},"anyOf":[{"required":["order_no"]},{"required":["merchant_order_no"]}]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"payment_method":{"type":"string","description":"Payment method"},"order_no":{"type":"string","description":"HansaPay order number"},"merchant_order_no":{"type":"string","description":"Merchant order number"},"status":{"type":"string","description":"Order status"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"Amount"},"requested_amount":{"$ref":"#/components/schemas/Amount","description":"The amount the merchant originally requested; present only when the amount was rounded down to a supported upstream price point (wallets, and card on some channels), in which case trans_amount is the amount actually charged"},"paid_at":{"type":"string","description":"Payment completion time"},"created_at":{"type":"string","description":"Creation time"},"masked_card_number":{"type":"string","description":"Masked card number, usually empty for wallet payments"},"trade_info":{"$ref":"#/components/schemas/TradeInfo","description":"Product information"},"metadata":{"type":"string","description":"Merchant passthrough field"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/refunds/create":{"post":{"operationId":"refundsCreate","summary":"Create Refund","description":"Create refund\n\nReference: https://www.hansapay.io/docs/refunds#create-refund","tags":["Refunds"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"original_order_no":{"type":"string","description":"HansaPay original order number"},"original_merchant_order_no":{"type":"string","description":"Merchant original order number"},"merchant_refund_no":{"type":"string","description":"Merchant refund order number, max 64 characters"},"refund_amount":{"type":"string","description":"Refund amount, in the original order's currency"},"reason":{"type":"string","description":"Refund reason"},"notify_url":{"type":"string","description":"Refund notification URL. If omitted, no refund notification is sent"},"metadata":{"type":"string","description":"Merchant passthrough field, returned in the refund notification"}},"required":["merchant_refund_no","refund_amount"],"anyOf":[{"required":["original_order_no"]},{"required":["original_merchant_order_no"]}]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"refund_no":{"type":"string","description":"HansaPay refund number"},"merchant_refund_no":{"type":"string","description":"Merchant refund number"},"original_order_no":{"type":"string","description":"Original HansaPay order number"},"original_merchant_order_no":{"type":"string","description":"Original merchant order number"},"status":{"type":"string","description":"Refund status"},"refund_amount":{"$ref":"#/components/schemas/Amount","description":"Refund amount"},"created_at":{"type":"string","description":"Creation time"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/refunds/query":{"post":{"operationId":"refundsQuery","summary":"Query Refund","description":"Query refund\n\nReference: https://www.hansapay.io/docs/refunds#query-refund","tags":["Refunds"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"refund_no":{"type":"string","description":"HansaPay refund number"},"merchant_refund_no":{"type":"string","description":"Merchant refund number"}},"anyOf":[{"required":["refund_no"]},{"required":["merchant_refund_no"]}]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"refund_no":{"type":"string","description":"HansaPay refund number"},"merchant_refund_no":{"type":"string","description":"Merchant refund number"},"original_order_no":{"type":"string","description":"Original HansaPay order number"},"original_merchant_order_no":{"type":"string","description":"Original merchant order number"},"status":{"type":"string","description":"Refund status"},"refund_amount":{"$ref":"#/components/schemas/Amount","description":"Refund amount"},"reason":{"type":"string","description":"Refund reason"},"created_at":{"type":"string","description":"Creation time"},"updated_at":{"type":"string","description":"Update time"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/payouts/create":{"post":{"operationId":"payoutsCreate","summary":"Create Payout","description":"Create payout\n\nPayouts are available for CASH_APP only. A payout is sent to a Cash App $cashtag, in USD, once payouts are enabled for your account. Until then, and for PAYPAL and PIX, /payouts/create and /payouts/precheck with an amount return code=5007. You can also send a payout from the merchant portal, under Payouts → Send payout.\n\nReference: https://www.hansapay.io/docs/payouts#create-payout","tags":["Payouts"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_method":{"type":"string","description":"CASH_APP / PAYPAL / PIX (only CASH_APP is currently available)","enum":["CASH_APP","PAYPAL","PIX"]},"merchant_payout_no":{"type":"string","description":"Merchant payout number, used for idempotency"},"trans_amount":{"type":"object","properties":{"currency":{"type":"string","description":"Currency. PIX requires BRL"},"value":{"type":"string","description":"Amount"}},"required":["currency","value"]},"payee":{"type":"object","properties":{"account_id":{"type":"string","description":"Recipient account. For PIX this is the PIX key value"},"account_type":{"type":"string","description":"EMAIL / MOBILE / CASHTAG / USERID etc. For PIX: CPF / CNPJ / PHONE / EMAIL"},"full_name":{"type":"string","description":"Recipient full name. Required for PIX"},"document":{"type":"string","description":"Recipient tax/ID number. Required for PIX (Brazilian CPF)"},"email":{"type":"string","description":"Recipient email"},"mobile":{"type":"string","description":"Recipient mobile"},"country":{"type":"string","description":"Country code"},"payee_id":{"type":"string","description":"Wallet-side user ID"}}},"memo":{"type":"string","description":"Payout memo"},"notify_url":{"type":"string","description":"Merchant URL for receiving payout result notifications after HansaPay receives the upstream result"},"metadata":{"type":"string","description":"Merchant passthrough field"},"client_ip":{"type":"string","description":"Client IP"}},"required":["payment_method","merchant_payout_no","trans_amount","notify_url"]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"payment_method":{"type":"string","description":"Payment method"},"payout_no":{"type":"string","description":"HansaPay payout number"},"merchant_payout_no":{"type":"string","description":"Merchant payout number"},"status":{"type":"string","enum":["PENDING","PROCESSING","SUCCESS","FAILED"],"description":"PENDING / PROCESSING / SUCCESS / FAILED"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"Payout amount"},"fee":{"$ref":"#/components/schemas/Amount","description":"Fee"},"total_debit":{"$ref":"#/components/schemas/Amount","description":"Total merchant debit"},"next_action":{"type":"string","enum":["WAIT_NOTIFY","SUCCESS","FAILED"],"description":"WAIT_NOTIFY / SUCCESS / FAILED"},"created_at":{"type":"string","description":"Creation time"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/payouts/query":{"post":{"operationId":"payoutsQuery","summary":"Query Payout","description":"Query payout\n\nReference: https://www.hansapay.io/docs/payouts#query-payout","tags":["Payouts"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payout_no":{"type":"string","description":"HansaPay payout number"},"merchant_payout_no":{"type":"string","description":"Merchant payout number"}},"anyOf":[{"required":["payout_no"]},{"required":["merchant_payout_no"]}]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"payment_method":{"type":"string","description":"Payment method"},"payout_no":{"type":"string","description":"HansaPay payout number"},"merchant_payout_no":{"type":"string","description":"Merchant payout number"},"status":{"type":"string","description":"Payout status"},"status_reason":{"type":"string","description":"FAILED: Payout request failed, Recipient not valid or Payout failed; CANCELED: Payout canceled; otherwise absent. Never the provider's message"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"Amount"},"fee":{"$ref":"#/components/schemas/Amount","description":"Fee"},"total_debit":{"$ref":"#/components/schemas/Amount","description":"Total debit"},"payee":{"type":"object","description":"Recipient snapshot"},"metadata":{"type":"string","description":"Merchant passthrough field"},"paid_at":{"type":"string","description":"Completion time"},"created_at":{"type":"string","description":"Creation time"},"updated_at":{"type":"string","description":"Update time"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/payouts/cancel":{"post":{"operationId":"payoutsCancel","summary":"Cancel Payout","description":"Cancel payout\n\nReference: https://www.hansapay.io/docs/payouts#cancel-payout","tags":["Payouts"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payout_no":{"type":"string","description":"HansaPay payout number"},"merchant_payout_no":{"type":"string","description":"Merchant payout number"},"reason":{"type":"string","description":"Cancellation reason"}},"anyOf":[{"required":["payout_no"]},{"required":["merchant_payout_no"]}]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"payout_no":{"type":"string","description":"HansaPay payout number"},"merchant_payout_no":{"type":"string","description":"Merchant payout number"},"status":{"type":"string","description":"Expected to be CANCELED"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}},"/api/v1/payouts/precheck":{"post":{"operationId":"payoutsPrecheck","summary":"Payout Balance Precheck","description":"Payout balance precheck\n\nPayouts are available for CASH_APP only. A payout is sent to a Cash App $cashtag, in USD, once payouts are enabled for your account. Until then, and for PAYPAL and PIX, /payouts/create and /payouts/precheck with an amount return code=5007. You can also send a payout from the merchant portal, under Payouts → Send payout.\n\nReference: https://www.hansapay.io/docs/payouts#payout-balance-precheck","tags":["Payouts"],"parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"payment_method":{"type":"string","enum":["CASH_APP","PAYPAL","PIX"],"description":"CASH_APP / PAYPAL / PIX"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"If provided, the system returns estimated fee and estimated total debit"}},"required":["payment_method"]}}}},"responses":{"200":{"description":"Signed response. Check `code`: errors are HTTP 200 too, with no `data`.","headers":{"X-MerchantID":{"schema":{"type":"string"},"description":"Your merchant ID."},"X-Timestamp":{"schema":{"type":"string"},"description":"Unix time in seconds."},"X-Nonce":{"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"X-Sign":{"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Envelope"},{"type":"object","properties":{"data":{"type":"object","properties":{"payment_method":{"type":"string","description":"Payment method"},"currency":{"type":"string","description":"Currency"},"available_balance":{"$ref":"#/components/schemas/Amount","description":"Available balance"},"unsettled_balance":{"$ref":"#/components/schemas/Amount","description":"Unsettled balance"},"frozen_balance":{"$ref":"#/components/schemas/Amount","description":"Frozen balance"},"spendable_balance":{"$ref":"#/components/schemas/Amount","description":"Payout-eligible balance, equal to available_balance"},"estimated_fee":{"$ref":"#/components/schemas/Amount","description":"Estimated fee, returned only when amount is provided"},"estimated_debit":{"$ref":"#/components/schemas/Amount","description":"Estimated total debit, returned only when amount is provided"},"can_payout":{"type":"boolean","description":"Without trans_amount: whether available_balance is above zero. It does not mean a payout method is available. With trans_amount: whether available_balance covers the estimated total debit"}}}}}]}}}},"401":{"description":"Missing authentication headers, or unknown merchant ID. Not signed."},"403":{"description":"Invalid signature. Not signed."}}}}},"webhooks":{"notification":{"post":{"summary":"How Merchants Receive Asynchronous Notifications","description":"Sent to the notify_url of the request, signed with the same four headers. Reply with the plain-text body `success` within 5 seconds, or it is retried. Reference: https://www.hansapay.io/docs/webhooks","parameters":[{"$ref":"#/components/parameters/XMerchantID"},{"$ref":"#/components/parameters/XTimestamp"},{"$ref":"#/components/parameters/XNonce"},{"$ref":"#/components/parameters/XSign"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","description":"payment.updated / refund.updated / payout.updated"},"order_no":{"type":"string","description":"HansaPay order number"},"merchant_order_no":{"type":"string","description":"Merchant order number"},"payment_method":{"type":"string","description":"Payment method"},"trans_amount":{"$ref":"#/components/schemas/Amount","description":"Payments and refunds: the USD amount charged or refunded, which differs from the API response for orders in another currency. Payouts: the payout amount"},"requested_amount":{"$ref":"#/components/schemas/Amount","description":"The amount the merchant originally requested; present only when the amount was rounded down to a supported upstream price point (wallets, and card on some channels), in which case trans_amount is the amount actually charged"},"trade_info":{"$ref":"#/components/schemas/TradeInfo","description":"Payments: product information. Refunds: goods_name holds the refund reason"},"status":{"type":"string","description":"Current status"},"status_reason":{"type":"string","description":"Payouts only, when failed or canceled: Payout request failed, Recipient not valid, Payout failed or Payout canceled"},"metadata":{"type":"string","description":"Merchant passthrough field"},"original_order_no":{"type":"string","description":"Original HansaPay order number, for refunds"},"original_merchant_order_no":{"type":"string","description":"Original merchant order number, for refunds"},"finished_at":{"type":"string","description":"Completion time. Not sent for refunds or failed payments"},"created_at":{"type":"string","description":"Creation time"}}}}}},"responses":{"200":{"description":"Exactly `success`.","content":{"text/plain":{"schema":{"const":"success"}}}}}}}},"components":{"parameters":{"XMerchantID":{"name":"X-MerchantID","in":"header","required":true,"schema":{"type":"string"},"description":"Your merchant ID."},"XTimestamp":{"name":"X-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix time in seconds."},"XNonce":{"name":"X-Nonce","in":"header","required":true,"schema":{"type":"string"},"description":"Random string, 16 to 32 characters recommended."},"XSign":{"name":"X-Sign","in":"header","required":true,"schema":{"type":"string"},"description":"Lower-case hex HMAC-SHA256, keyed with your secret, of merchantID + \"\\n\" + timestamp + \"\\n\" + nonce + \"\\n\" + rawBody."}},"schemas":{"Envelope":{"type":"object","required":["code","msg"],"properties":{"code":{"type":"integer","description":"0 on success."},"msg":{"type":"string","description":"Reason. Failures usually end with | and a stable key, e.g. Order not found|orderNotFound."}}},"Amount":{"type":"object","required":["currency","value"],"properties":{"currency":{"type":"string","description":"Three-letter upper-case currency code, such as USD."},"value":{"type":"string","description":"Amount as a string with at most 2 decimals, such as 99.99."}}},"TradeInfo":{"type":"object","properties":{"goods_name":{"type":"string"},"description":{"type":"string"}}}}}}