/proof/link Get Proof Link

Background

Availability: this API is an external contract published for upcoming integration; the actual availability date is subject to the release confirmation.

Using the merchant order number merchantOrderNo, the partner obtains an access link linkUrl to the proof page of a payout order belonging to one of its merchants. The proof type is specified by proofType; currently only APS (payout order) is supported.

The query scope is limited to the primary merchant ID in the X-Merchant-Id request header; subMerchantNo is not required. The subMerchantNo in the response is the merchant ID that owns the payout order found, so the partner can distribute the proof link to the corresponding merchant.

Endpoint

Item	Value
Method	GET
Path	/proof/link
Content-Type	application/json
Purpose	Get the payment proof access link

Access Requirements

• Common specifications

Request Fields

Field	Location	Type	Length	Required	Description
X-Merchant-Id	Header	string	64	Yes	Primary merchant ID, read from the request header; isolates the order data of different partners.
X-Timestamp	Header	int	19	Yes	Unix request timestamp in seconds, used to validate request freshness.
X-Nonce	Header	string	64	Yes	Anti-replay random string for the request.
Digest	Header	string	52	Yes	Request digest in the format SHA-256=<Base64 digest>; this API has no request body, so it is computed over an empty byte string.
Authorization	Header	string	Variable	Yes	ES256 request signature information, where keyId is the partner key version.
merchantOrderNo	Query	string	64	Yes	Merchant order number used when placing the payout order; must not be blank and must not exceed 64 bytes.
proofType	Query	string	16	Yes	Proof type; currently only APS (payout order).

Retrieval Rules

• Only orders of merchants under the currently authenticated partner may be queried; merchantOrderNo must match the merchant order number used in Create PIX Out, and proofType must match the order's actual type.
• The payment proof must already exist. This API only generates an access link; it does not create the proof or change the order status.
• If the order or proof does not exist, no usable link is returned. Failing to get the proof does not mean the payment failed; confirm the transaction result through Query PIX Out.
• Use the complete linkUrl as-is and keep its key query parameter. Treat the link as access to the proof and share it only with intended recipients; the example domain and key are for illustration only — the actually returned full URL prevails.

Request Example

GET /proof/link?merchantOrderNo=CASHOUT202608160001&proofType=APS HTTP/1.1
Content-Type: application/json
X-Merchant-Id: 92315566000120
X-Timestamp: 1786845600
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

A GET request carries no body. For an actual call, use the current timestamp and a fresh random string, and compute the signature over the actual request path and the full query string; see Request Signing.

Response Fields

The API uses the standard status, msg, and data response structure. The proof link is obtained successfully only when status = 200 and data.linkUrl is non-empty.

Field	Type	Length	Returned	Description
status	int	4	Yes	Response code; 200 means the request was processed successfully.
msg	string	128	Yes	Message corresponding to status; "sucesso" on success.
data	object	N/A	No	Proof link result; may be omitted or null when the request fails.
data.subMerchantNo	string	64	On success	Merchant ID that owns this payout order, identical to the subMerchantNo used in the original payout order placement.
data.merchantOrderNo	string	64	On success	Merchant order number.
data.platOrderNo	string	64	On success	Platform order number.
data.linkUrl	string	128	On success	Complete access link to the payment proof page, including the key query parameter; non-empty on success. It is not proof JSON or file content.

When business processing fails, status is a value other than 200 and the reason is in msg; the link fields must not be used in that case. Failures before business processing, such as signature verification or protocol parsing, may return no data.

Response Example

{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "subMerchantNo": "SUBMERCHANT0001",
    "merchantOrderNo": "CASHOUT202608160001",
    "platOrderNo": "APS202608160000000001",
    "linkUrl": "https://proof.example.com/payment?key=PROOF_KEY"
  }
}

Response Error Codes

• Response Status