{ "openapi": "3.1.0", "info": { "title": "BRPAY Merchant BRC-wallet API", "version": "1.0.0", "description": "BRC-wallet game recharge and withdrawal. See merchant.md for fee, HMAC, callback and unknown-outcome rules. No real Pix payout." }, "servers": [ { "url": "https://api.example.invalid", "description": "Replace with the deployed BrazilPay origin" } ], "security": [ { "MerchantId": [], "Timestamp": [], "RequestId": [], "Signature": [] } ], "paths": { "/api/merchant/orders/payin": { "post": { "operationId": "payin", "summary": "代收充值", "description": "Create a PAYIN and give the customer the returned checkout URL. Order creation does not move funds. Optional notifyUrl and returnUrl are saved per order. Merchant profiles do not provide a fallback. Omitting notifyUrl disables notifications; omitting returnUrl hides merchant navigation. A browser return is not proof of payment.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "orderAmount": { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)0*(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2}0*)?$", "examples": [ "30.00" ], "description": "Positive decimal string exactly representable in cents, with up to 17 integer digits after leading zeros. Extra fractional trailing zeros are accepted." }, "description": { "type": [ "string", "null" ], "maxLength": 160, "description": "Optional; omitted, null or empty means no description. Nonempty text: at most 160 UTF-16 code units, no ASCII controls.", "x-maxUtf16CodeUnits": 160 }, "notifyUrl": { "anyOf": [ { "type": "string", "format": "uri", "minLength": 1, "maxLength": 512, "pattern": "^(?:https://|http://127\\.0\\.0\\.1(?::[0-9]+)?(?:/|$))[^\\s#]*$" }, { "const": "" }, { "type": "null" } ], "description": "Signed asynchronous result notification endpoint. Omit to disable notifications. Full ASCII HTTPS URL, without credentials, fragments or controls. Percent-encode non-ASCII content. Local verification also permits http://127.0.0.1. Null and empty strings mean omitted." }, "returnUrl": { "anyOf": [ { "type": "string", "format": "uri", "minLength": 1, "maxLength": 512, "pattern": "^(?:https://|http://127\\.0\\.0\\.1(?::[0-9]+)?(?:/|$))[^\\s#]*$" }, { "const": "" }, { "type": "null" } ], "description": "Synchronous merchant return page. Omit to hide the return action; PAYOUT stores this without navigation. Full ASCII HTTPS URL, without credentials, fragments or controls. Percent-encode non-ASCII content. Local verification also permits http://127.0.0.1. Null and empty strings mean omitted." } }, "required": [ "merchantOrderNo", "orderAmount" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success; inspect order status for final payment outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "code": { "const": "OK" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "orderNo": { "type": "string", "pattern": "^(?:RC|PY)(?!0{14}$)[0-9]{14}$", "minLength": 16, "maxLength": 16, "description": "系统单号：RC 为商户代收，PY 为商户代付，后接 14 位共享序号。" }, "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "direction": { "const": "PAYIN" }, "currency": { "const": "BRC" }, "orderAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "BRC quantity as a positive decimal string, with up to 17 integer digits and 2 decimal places." }, "feeAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Nonnegative fee quantity in BRC, expressed as a decimal string." }, "merchantAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Positive BRC quantity: net merchant credit for PAYIN, or total merchant debit including fees for PAYOUT." }, "actualAmount": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ] }, { "type": "null" } ], "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "status": { "enum": [ "PENDING", "SUCCESS", "FAILED" ] }, "walletId": { "type": [ "string", "null" ], "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "PAYIN payer, retained on a corrected failure when known; PAYOUT designated recipient." }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notificationStatus": { "type": [ "string", "null" ], "enum": [ "PENDING", "DELIVERED", "EXHAUSTED", null ] }, "cashierUrl": { "type": "string", "format": "uri", "pattern": "/pay/[A-Za-z0-9_-]{22}$" }, "appUrl": { "type": "string", "pattern": "^brazilpay://cashier/[A-Za-z0-9_-]{22}$" }, "failureCode": { "type": [ "string", "null" ], "pattern": "^[A-Z][A-Z0-9_]{0,63}$", "description": "Required for FAILED orders; ORDER_EXPIRED for expired PAYIN, or the explicit payout failure reason. Null otherwise." }, "orderRevision": { "type": "integer", "minimum": 0, "description": "Increasing result revision; original settlement is revision zero." } }, "required": [ "orderNo", "merchantOrderNo", "direction", "currency", "orderAmount", "feeAmount", "merchantAmount", "actualAmount", "status", "walletId", "createdAt", "expiresAt", "completedAt", "notificationStatus", "failureCode", "orderRevision" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "status": { "const": "SUCCESS" } } }, "then": { "properties": { "actualAmount": { "type": "string", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "status": { "const": "PENDING" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "direction": { "const": "PAYIN" } } }, "then": { "required": [ "cashierUrl", "appUrl" ], "properties": { "expiresAt": { "type": "string" } } }, "else": { "properties": { "expiresAt": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } }, "required": [ "status" ] }, "then": { "required": [ "failureCode", "completedAt" ], "properties": { "failureCode": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "format": "date-time" }, "actualAmount": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYOUT" } }, "required": [ "direction" ] }, "then": { "required": [ "walletId" ], "properties": { "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$" }, "expiresAt": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYIN" }, "status": { "const": "PENDING" } }, "required": [ "direction", "status" ] }, "then": { "properties": { "walletId": { "type": "null" } } } } ] } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true } } } }, "400": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST required; Allow: POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/merchant/orders/payout": { "post": { "operationId": "payout", "summary": "代付提现", "description": "Accept a wallet payout as PENDING and reserve the amount plus fee. Local settlement completes it as SUCCESS or a confirmed FAILED with the hold released. Only terminal orders generate result callbacks. API rejection creates no new order. Timeouts require querying the original merchant order number.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "orderAmount": { "type": "string", "pattern": "^(?!0+(?:\\.0+)?$)0*(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2}0*)?$", "examples": [ "30.00" ], "description": "Positive decimal string exactly representable in cents, with up to 17 integer digits after leading zeros. Extra fractional trailing zeros are accepted." }, "description": { "type": [ "string", "null" ], "maxLength": 160, "description": "Optional; omitted, null or empty means no description. Nonempty text: at most 160 UTF-16 code units, no ASCII controls.", "x-maxUtf16CodeUnits": 160 }, "recipientWalletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" }, "notifyUrl": { "anyOf": [ { "type": "string", "format": "uri", "minLength": 1, "maxLength": 512, "pattern": "^(?:https://|http://127\\.0\\.0\\.1(?::[0-9]+)?(?:/|$))[^\\s#]*$" }, { "const": "" }, { "type": "null" } ], "description": "Signed asynchronous result notification endpoint. Omit to disable notifications. Full ASCII HTTPS URL, without credentials, fragments or controls. Percent-encode non-ASCII content. Local verification also permits http://127.0.0.1. Null and empty strings mean omitted." }, "returnUrl": { "anyOf": [ { "type": "string", "format": "uri", "minLength": 1, "maxLength": 512, "pattern": "^(?:https://|http://127\\.0\\.0\\.1(?::[0-9]+)?(?:/|$))[^\\s#]*$" }, { "const": "" }, { "type": "null" } ], "description": "Synchronous merchant return page. Omit to hide the return action; PAYOUT stores this without navigation. Full ASCII HTTPS URL, without credentials, fragments or controls. Percent-encode non-ASCII content. Local verification also permits http://127.0.0.1. Null and empty strings mean omitted." } }, "required": [ "merchantOrderNo", "orderAmount", "recipientWalletId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success; inspect order status for final payment outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "code": { "const": "OK" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "orderNo": { "type": "string", "pattern": "^(?:RC|PY)(?!0{14}$)[0-9]{14}$", "minLength": 16, "maxLength": 16, "description": "系统单号：RC 为商户代收，PY 为商户代付，后接 14 位共享序号。" }, "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "direction": { "const": "PAYOUT" }, "currency": { "const": "BRC" }, "orderAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "BRC quantity as a positive decimal string, with up to 17 integer digits and 2 decimal places." }, "feeAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Nonnegative fee quantity in BRC, expressed as a decimal string." }, "merchantAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Positive BRC quantity: net merchant credit for PAYIN, or total merchant debit including fees for PAYOUT." }, "actualAmount": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ] }, { "type": "null" } ], "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "status": { "enum": [ "PENDING", "SUCCESS", "FAILED" ] }, "walletId": { "type": [ "string", "null" ], "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "PAYIN payer, retained on a corrected failure when known; PAYOUT designated recipient." }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notificationStatus": { "type": [ "string", "null" ], "enum": [ "PENDING", "DELIVERED", "EXHAUSTED", null ] }, "cashierUrl": { "type": "string", "format": "uri", "pattern": "/pay/[A-Za-z0-9_-]{22}$" }, "appUrl": { "type": "string", "pattern": "^brazilpay://cashier/[A-Za-z0-9_-]{22}$" }, "failureCode": { "type": [ "string", "null" ], "pattern": "^[A-Z][A-Z0-9_]{0,63}$", "description": "Required for FAILED orders; ORDER_EXPIRED for expired PAYIN, or the explicit payout failure reason. Null otherwise." }, "orderRevision": { "type": "integer", "minimum": 0, "description": "Increasing result revision; original settlement is revision zero." } }, "required": [ "orderNo", "merchantOrderNo", "direction", "currency", "orderAmount", "feeAmount", "merchantAmount", "actualAmount", "status", "walletId", "createdAt", "expiresAt", "completedAt", "notificationStatus", "failureCode", "orderRevision" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "status": { "const": "SUCCESS" } } }, "then": { "properties": { "actualAmount": { "type": "string", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "status": { "const": "PENDING" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "direction": { "const": "PAYIN" } } }, "then": { "required": [ "cashierUrl", "appUrl" ], "properties": { "expiresAt": { "type": "string" } } }, "else": { "properties": { "expiresAt": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } }, "required": [ "status" ] }, "then": { "required": [ "failureCode", "completedAt" ], "properties": { "failureCode": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "format": "date-time" }, "actualAmount": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYOUT" } }, "required": [ "direction" ] }, "then": { "required": [ "walletId" ], "properties": { "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$" }, "expiresAt": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYIN" }, "status": { "const": "PENDING" } }, "required": [ "direction", "status" ] }, "then": { "properties": { "walletId": { "type": "null" } } } } ] } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true } } } }, "400": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST required; Allow: POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/merchant/orders/query": { "post": { "operationId": "queryOrder", "summary": "订单查询", "description": "Look up an order for the authenticated merchant. Send exactly one of merchantOrderNo or orderNo. Read status for the payment outcome and notificationStatus for callback delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "orderNo": { "type": "string", "pattern": "^(?:RC|PY)(?!0{14}$)[0-9]{14}$", "minLength": 16, "maxLength": 16, "description": "平台系统单号；与 merchantOrderNo 二选一。" } }, "additionalProperties": false, "oneOf": [ { "required": [ "merchantOrderNo" ] }, { "required": [ "orderNo" ] } ] } } } }, "responses": { "200": { "description": "Success; inspect order status for final payment outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "code": { "const": "OK" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "orderNo": { "type": "string", "pattern": "^(?:RC|PY)(?!0{14}$)[0-9]{14}$", "minLength": 16, "maxLength": 16, "description": "系统单号：RC 为商户代收，PY 为商户代付，后接 14 位共享序号。" }, "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "direction": { "enum": [ "PAYIN", "PAYOUT" ] }, "currency": { "const": "BRC" }, "orderAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "BRC quantity as a positive decimal string, with up to 17 integer digits and 2 decimal places." }, "feeAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Nonnegative fee quantity in BRC, expressed as a decimal string." }, "merchantAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Positive BRC quantity: net merchant credit for PAYIN, or total merchant debit including fees for PAYOUT." }, "actualAmount": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ] }, { "type": "null" } ], "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "status": { "enum": [ "PENDING", "SUCCESS", "FAILED" ] }, "walletId": { "type": [ "string", "null" ], "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "PAYIN payer, retained on a corrected failure when known; PAYOUT designated recipient." }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "notificationStatus": { "type": [ "string", "null" ], "enum": [ "PENDING", "DELIVERED", "EXHAUSTED", null ] }, "cashierUrl": { "type": "string", "format": "uri", "pattern": "/pay/[A-Za-z0-9_-]{22}$" }, "appUrl": { "type": "string", "pattern": "^brazilpay://cashier/[A-Za-z0-9_-]{22}$" }, "failureCode": { "type": [ "string", "null" ], "pattern": "^[A-Z][A-Z0-9_]{0,63}$", "description": "Required for FAILED orders; ORDER_EXPIRED for expired PAYIN, or the explicit payout failure reason. Null otherwise." }, "orderRevision": { "type": "integer", "minimum": 0, "description": "Increasing result revision; original settlement is revision zero." } }, "required": [ "orderNo", "merchantOrderNo", "direction", "currency", "orderAmount", "feeAmount", "merchantAmount", "actualAmount", "status", "walletId", "createdAt", "expiresAt", "completedAt", "notificationStatus", "failureCode", "orderRevision" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "status": { "const": "SUCCESS" } } }, "then": { "properties": { "actualAmount": { "type": "string", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "status": { "const": "PENDING" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "direction": { "const": "PAYIN" } } }, "then": { "required": [ "cashierUrl", "appUrl" ], "properties": { "expiresAt": { "type": "string" } } }, "else": { "properties": { "expiresAt": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } }, "required": [ "status" ] }, "then": { "required": [ "failureCode", "completedAt" ], "properties": { "failureCode": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "format": "date-time" }, "actualAmount": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYOUT" } }, "required": [ "direction" ] }, "then": { "required": [ "walletId" ], "properties": { "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$" }, "expiresAt": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYIN" }, "status": { "const": "PENDING" } }, "required": [ "direction", "status" ] }, "then": { "properties": { "walletId": { "type": "null" } } } } ] } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true } } } }, "400": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST required; Allow: POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/merchant/orders/availability": { "post": { "operationId": "queryAvailability", "summary": "接单状态查询", "description": "Send an empty object to query both directions, or specify PAYIN or PAYOUT. The inclusive BRC quantity range intersects fee and storage requirements, the merchant's single-order limits, and its remaining daily quota. Daily quota counts gross accepted orders in the America/Sao_Paulo calendar day. acceptingOrders is false during maintenance, when the merchant direction is disabled, or when no valid range remains. The query reserves no quota or balance; order creation checks the current rules again.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "enum": [ "PAYIN", "PAYOUT" ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success; inspect order status for final payment outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "code": { "const": "OK" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "payin": { "$ref": "#/components/schemas/Availability" }, "payout": { "$ref": "#/components/schemas/Availability" } }, "required": [], "additionalProperties": true } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true } } } }, "400": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST required; Allow: POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/merchant/account/balance": { "post": { "operationId": "queryBalance", "summary": "商户余额查询", "description": "Read one BRC wallet snapshot. balance = heldBalance + availableBalance. heldBalance is generic occupied funds, not limited to payouts. Payout acceptance reserves principal plus fee; success settles and failure releases the hold.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success; inspect order status for final payment outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "code": { "const": "OK" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "currency": { "const": "BRC" }, "balance": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Total booked BRC balance including held funds." }, "availableBalance": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Available BRC balance: balance minus heldBalance. Principal plus fee must fit at payout acceptance." }, "asOf": { "type": "string", "format": "date-time" }, "heldBalance": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "5.30" ], "description": "Generic occupied BRC balance, temporarily unavailable for new business." } }, "required": [ "currency", "balance", "heldBalance", "availableBalance", "asOf" ], "additionalProperties": true } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true } } } }, "400": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST required; Allow: POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/merchant/account/transactions": { "post": { "operationId": "queryTransactions", "summary": "商户资金流水", "description": "List posted BRC balance changes, up to 50 per page, starting at page 0. Use the ledger id to recognize entries that recur across pages as the live list changes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 0 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success; inspect order status for final payment outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "code": { "const": "OK" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "page": { "type": "integer" }, "hasMore": { "type": "boolean" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderNo": { "type": "string", "pattern": "^(?:RC|PY)(?!0{14}$)[0-9]{14}$", "minLength": 16, "maxLength": 16, "description": "系统单号：RC 为商户代收，PY 为商户代付，后接 14 位共享序号。" }, "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "direction": { "enum": [ "PAYIN", "PAYOUT" ] }, "amount": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "description": "Signed BRC quantity in this merchant ledger entry." }, "feeAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Nonnegative fee quantity in BRC, expressed as a decimal string." }, "balanceAfter": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Merchant BRC balance after this entry, expressed as a decimal quantity string." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "orderNo", "merchantOrderNo", "direction", "amount", "feeAmount", "balanceAfter", "createdAt" ], "additionalProperties": true } } }, "required": [ "page", "hasMore", "rows" ], "additionalProperties": true } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true } } } }, "400": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST required; Allow: POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/merchant/wallets/query": { "post": { "operationId": "queryWallet", "summary": "钱包校验", "description": "Look up a W account before a payout. An unknown wallet returns HTTP 200 with exists=false. If exists and canReceive are true, pass walletId as recipientWalletId after confirming the intended recipient.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" } }, "required": [ "account" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success; inspect order status for final payment outcome", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "code": { "const": "OK" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "exists": { "type": "boolean" }, "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" }, "account": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" }, "canReceive": { "type": "boolean" } }, "required": [ "exists" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "exists": { "const": true } } }, "then": { "required": [ "account", "walletId", "canReceive" ] } } ] } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true } } } }, "400": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "POST required; Allow: POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Merchant error envelope. 5xx leaves a write outcome unconfirmed; query the original merchantOrderNo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "MerchantId": { "type": "apiKey", "in": "header", "name": "X-Merchant-Id", "schema": { "type": "string", "pattern": "^M(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "平台分配的商户号。" } }, "Timestamp": { "type": "apiKey", "in": "header", "name": "X-Timestamp" }, "RequestId": { "type": "apiKey", "in": "header", "name": "X-Request-Id" }, "Signature": { "type": "apiKey", "in": "header", "name": "X-Signature" } }, "schemas": { "Availability": { "type": "object", "properties": { "acceptingOrders": { "type": "boolean" }, "minimumAmount": { "type": [ "string", "null" ], "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Inclusive minimum BRC quantity; null if no valid quantity range exists." }, "maximumAmount": { "type": [ "string", "null" ], "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Inclusive maximum BRC quantity; null if no valid quantity range exists." }, "feeRate": { "type": "string", "pattern": "^(?:0(?:\\.[0-9]{1,6})?|1(?:\\.0{1,6})?)$" }, "feeFixed": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Nonnegative fixed fee quantity in BRC, expressed as a decimal string." }, "feeMin": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "description": "Minimum per-order fee in BRC, applied after rounding the percentage plus fixed fee." } }, "required": [ "acceptingOrders", "minimumAmount", "maximumAmount", "feeRate", "feeFixed", "feeMin" ], "additionalProperties": true, "description": "Fee-adjusted inclusive quantity range, intersected with merchant limits and remaining daily quota. Both bounds are null if no valid quantity. The daily quota counts gross accepted orders in the Sao Paulo business day. Availability does not reserve quota or balance. During maintenance acceptingOrders is false.", "allOf": [ { "if": { "properties": { "minimumAmount": { "type": "null", "description": "Inclusive minimum BRC quantity; null if no valid quantity range exists." } } }, "then": { "properties": { "maximumAmount": { "type": "null", "description": "Inclusive maximum BRC quantity; null if no valid quantity range exists." }, "acceptingOrders": { "const": false } } }, "else": { "properties": { "maximumAmount": { "type": "string", "description": "Inclusive maximum BRC quantity; null if no valid quantity range exists." } } } } ] }, "Error": { "type": "object", "properties": { "success": { "const": false }, "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": [ "string", "null" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "null" } }, "required": [ "success", "code", "message", "requestId", "timestamp", "data" ], "additionalProperties": true }, "CallbackOrder": { "type": "object", "properties": { "orderNo": { "type": "string", "pattern": "^(?:RC|PY)(?!0{14}$)[0-9]{14}$", "minLength": 16, "maxLength": 16, "description": "系统单号：RC 为商户代收，PY 为商户代付，后接 14 位共享序号。" }, "merchantOrderNo": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, "direction": { "enum": [ "PAYIN", "PAYOUT" ] }, "currency": { "const": "BRC" }, "orderAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "BRC quantity as a positive decimal string, with up to 17 integer digits and 2 decimal places." }, "feeAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Nonnegative fee quantity in BRC, expressed as a decimal string." }, "merchantAmount": { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ], "description": "Positive BRC quantity: net merchant credit for PAYIN, or total merchant debit including fees for PAYOUT." }, "actualAmount": { "anyOf": [ { "type": "string", "pattern": "^(?:0|[1-9][0-9]{0,16})(?:\\.[0-9]{1,2})?$", "examples": [ "30.00" ] }, { "type": "null" } ], "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "status": { "enum": [ "SUCCESS", "FAILED" ] }, "walletId": { "type": [ "string", "null" ], "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "PAYIN payer, retained on a corrected failure when known; PAYOUT designated recipient." }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureCode": { "type": [ "string", "null" ], "pattern": "^[A-Z][A-Z0-9_]{0,63}$", "description": "Required for FAILED orders; ORDER_EXPIRED for expired PAYIN, or the explicit payout failure reason. Null otherwise." }, "orderRevision": { "type": "integer", "minimum": 0, "description": "Increasing result revision; original settlement is revision zero." } }, "required": [ "orderNo", "merchantOrderNo", "direction", "currency", "orderAmount", "feeAmount", "merchantAmount", "actualAmount", "status", "walletId", "createdAt", "expiresAt", "completedAt" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "status": { "const": "SUCCESS" } } }, "then": { "properties": { "actualAmount": { "type": "string", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$", "minLength": 9, "maxLength": 9, "description": "稳定钱包账号：W 加 8 位大写字母或数字，不使用手机号、邮箱或内部 UUID。" }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "status": { "const": "PENDING" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "null" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } } }, "then": { "properties": { "actualAmount": { "type": "null", "description": "BRC quantity actually debited or credited to the user on SUCCESS; null otherwise." }, "completedAt": { "type": "string" } } } }, { "if": { "properties": { "status": { "const": "FAILED" } }, "required": [ "status" ] }, "then": { "required": [ "failureCode", "completedAt" ], "properties": { "failureCode": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "format": "date-time" }, "actualAmount": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYOUT" } }, "required": [ "direction" ] }, "then": { "required": [ "walletId" ], "properties": { "walletId": { "type": "string", "pattern": "^W(?!0{8}$)[0-9A-Z]{8}$" }, "expiresAt": { "type": "null" } } } }, { "if": { "properties": { "direction": { "const": "PAYIN" }, "status": { "const": "PENDING" } }, "required": [ "direction", "status" ] }, "then": { "properties": { "walletId": { "type": "null" } } } } ] }, "CallbackEvent": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "eventType": { "enum": [ "ORDER_SUCCEEDED", "ORDER_FAILED", "ORDER_CORRECTED" ] }, "occurredAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "data": { "$ref": "#/components/schemas/CallbackOrder" }, "correctionId": { "type": "string", "format": "uuid" }, "previousStatus": { "enum": [ "PENDING", "SUCCESS", "FAILED" ] } }, "required": [ "eventId", "eventType", "occurredAt", "data" ], "additionalProperties": true, "allOf": [ { "if": { "properties": { "eventType": { "const": "ORDER_SUCCEEDED" } } }, "then": { "properties": { "data": { "properties": { "status": { "const": "SUCCESS" } } } } } }, { "if": { "properties": { "eventType": { "const": "ORDER_FAILED" } } }, "then": { "properties": { "data": { "properties": { "status": { "const": "FAILED" } } } } } }, { "if": { "properties": { "eventType": { "const": "ORDER_CORRECTED" } } }, "then": { "required": [ "correctionId", "previousStatus" ], "properties": { "data": { "required": [ "orderRevision" ], "properties": { "orderRevision": { "type": "integer", "minimum": 1 } } } } } } ] } } }, "webhooks": { "merchantResult": { "post": { "operationId": "merchantResult", "summary": "Signed terminal order event sent to the order notifyUrl", "description": "BRPAY sends the event to notifyUrl saved on this order at creation. Merchant profiles do not supply or override this address. Omitting notifyUrl creates no notification. Verify HMAC-SHA256 of timestamp + LF + eventId + LF + raw UTF-8 JSON. Return 2xx after persisting your result. Retries reuse eventId and body; timestamp and signature change.", "security": [], "parameters": [ { "in": "header", "name": "X-BrazilPay-Event-Id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "X-BrazilPay-Timestamp", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "Z$" } }, { "in": "header", "name": "X-BrazilPay-Signature", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackEvent" } } } }, "responses": { "204": { "description": "Durably accepted; response body ignored" }, "default": { "description": "Non-2xx or transport timeout leaves delivery unconfirmed; funds are never reversed" } } } } }, "x-order-correction": { "eventType": "ORDER_CORRECTED", "correctionId": "UUID", "previousStatus": [ "PENDING", "SUCCESS", "FAILED" ], "orderRevision": "Positive increasing integer in data; compare per order; normal events use revision zero", "failedPayinWallet": "Original payer may remain populated after correction" } }