--- title: "Get payment by transaction ID" method: GET path: "/v1/payments/txid/{txId}" tags: ["Payments"] --- # Get payment by transaction ID `GET /v1/payments/txid/{txId}` ## Request - Base URL: `https://api.yuvexpay.com` - URL: `https://api.yuvexpay.com/v1/payments/txid/{txId}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieve a payment using the YuvexPay transaction ID (`txId`) instead of the UUID. ## Path parameters - `txId` string, required ## Response `200` Payment found. - object - `payment` Payment - `id` string, uuid - `txId` string: YuvexPay transaction ID. - `amount` number: Amount in BRL before any fee passed to the payer: `subtotal` minus `discount`. On a hosted payment it changes before the payer picks a method when the payer changes a quantity, ticks the order bump or applies a coupon. `0` on a `FREE` payment. - `feeAmount` number: YuvexPay platform fee, in BRL. When `feePassedToPayer` is true, this equals `payerFeeAmount` and is charged on top of `amount`. When false, this is deducted from `amount` to produce `netAmount`. - `netAmount` number: Merchant's net receivable, in BRL. Equals `amount` when `feePassedToPayer` is true; equals `amount - feeAmount` otherwise. This figure is pre-split: when the payment carries `splits`, the originating company keeps `netAmount` minus the sum of the splits and the rest is credited to the recipients on settlement. - `feePassedToPayer` boolean: Resolved decision (after applying the per-payment override, company default, and sub-R$1 forced passthrough) on whether the fee was added on top for the payer. - `payerFeeAmount` number, nullable: Fee amount added to the payer's total charge. Null when `feePassedToPayer` is false. When true, payer-charged total = `amount + payerFeeAmount`. - `splits` PaymentSplit[]: Splits recorded on this payment, in the order they were sent. `[]` when the payment has none. Only the originating company can read them: a recipient calling `GET /v1/payments/{paymentId}` for this payment gets `404`. - `id` string, uuid, required: Identifier of this split entry. - `recipientCompanyId` string, uuid, required: Company id of the YuvexPay account that receives this share. - `type` 'PERCENTAGE' | 'FIXED', required: Whether `value` is a percentage of `amount` or a fixed BRL amount. - `value` number, required: The percentage or the BRL amount, exactly as it was sent at creation. - `status` 'NEW' | 'PENDING_METHOD_SELECTION' | 'PROCESSING' | 'CONFIRMED' | 'PAID' | 'CANCELLED' | 'EXPIRED' | 'REFUNDED' | 'PARTIAL_REFUND' | 'CHARGEBACK' | 'MED_FROZEN' | 'FREE': Possible payment statuses. `FREE`: a coupon discounted the whole amount and the order completed without a charge; it is terminal and cannot be refunded. - `paymentMethod` 'PIX' | 'CARD' | 'BOLETO': Available public payment methods. - `currency` 'BRL': Supported currencies. - `description` string - `metadata` object - `expiresAt` string, date-time - `createdAt` string, date-time - `methodData` object, nullable: Payment method-specific data (QR code for PIX, masked card data for CARD, barcode for boleto). `null` while the payment has no method data: a boleto payment that is `PROCESSING` after a `502`, a card payment that is `PROCESSING` before the outcome of its charge is known, a payment recorded `CANCELLED` or `EXPIRED` before a charge was created, a hosted payment still in `PENDING_METHOD_SELECTION`, or a `FREE` payment. For CARD, `cardFundingType` is `credit` or `debit`, and `null` when the funding type is not known, including older payments. - `type` 'PIX' | 'CARD' | 'BOLETO': Available public payment methods. - `cardFundingType` 'credit' | 'debit' | 'null', nullable: CARD only. `credit` when the card was charged as a credit card in a single installment, `debit` when it was charged as a debit card. `null` when the funding type is not known, including older payments. - `paidAt` string, date-time, nullable: Timestamp when the payment was confirmed paid. Null until paid, and on a `FREE` payment, which has `completedAt` instead. - `completedAt` string, date-time, nullable: When a `FREE` payment completed. `null` on every other payment. - `payer` object, nullable: Payer (debtor) identity captured from the PIX network once the charge is paid. Before that, `name` and `document` carry what you sent in `customer`, completed with what the payer typed on the hosted checkout. `email` and `phone` carry the payer's contact. `null` when none of the seven fields is known, for example on historical records or open-payer charges. A `payer` that has only `email` or `phone` is possible, so a non-null `payer` does not mean the payment was paid. Webhook `payer` blocks are unchanged and carry no `email` or `phone`. - `name` string, nullable: Payer full name. - `document` string, nullable: Payer CPF or CNPJ, as digits. Some PIX participants report the document masked (for example `***405566**`); when that is all the network gave us, the masked string is what this field carries — a full document wins whenever one is on file. `null` when no document of either kind was captured, which for an open-payer charge is common. Match on `*` before parsing the value as a CPF or CNPJ. - `documentType` 'CPF' | 'CNPJ' | 'null', nullable: Payer document type. `null` when the network did not say which kind of document it reported, which is the usual case alongside a masked `document`. - `institutionName` string, nullable: Payer bank/institution name. - `institutionIspb` string, nullable: Payer bank ISPB (Banco Central participant identifier). - `email` string, nullable: Payer e-mail: the one the payer typed on the hosted checkout, else the one in `customer`, or of the customer named in `customerId`, when the payment was created. `GET /v1/payments/{paymentId}` and `POST /v1/payments/{paymentId}/simulate` also fall back to the current e-mail of the customer linked to the payment; `GET /v1/payments` and `GET /v1/payments/txid/{txId}` do not. `null` when not known. - `phone` string, nullable: Payer phone, with the same sources and fallback as `email`. `null` when not known. - `recoveryKit` object: Recovery kit of this payment. See `recoveryKit` on `POST /v1/payments`. - `enabled` boolean, required: The kit is on for this payment. `false` when the payment was created with the kit off, in sandbox, or before the kit existed, and on a payment-link payment whose payer already has a kit running on that link. - `charged` boolean, required: The kit price was debited from your balance. It is debited once, when the first e-mail of the kit is sent. - `emailsSent` integer, required: Recovery e-mails sent for this payment, including the one sent before a PIX code expires. - `items` PaymentItem[]: Order lines, `[]` when the payment was created with an amount only, until the payer ticks an order bump. - `id` string, uuid, required - `name` string, required - `unitAmount` number, required: Unit price in BRL. - `quantity` integer, required: Quantity. The payer may have changed it on the hosted checkout when the payment was created with `itemsQuantityEditable: true`. - `kind` 'ITEM' | 'ORDER_BUMP' | 'UPSELL', required: `ITEM`: a line you sent in `items`. `ORDER_BUMP`: the order bump the payer ticked. `UPSELL`: the line of a payment created by a post-purchase upsell. - `productId` string, uuid, nullable, required - `sku` string, nullable, required - `subtotal` number: Amount before the coupon, in BRL. - `discount` number: Coupon discount, in BRL. `0` without a coupon. - `coupon` PaymentCoupon, nullable: The coupon applied to the payment, or `null`. - `code` string, required: The coupon code, uppercase. - `parentPaymentId` string, uuid, nullable: On a payment created by a post-purchase upsell, the payment whose upsell the payer accepted. `null` otherwise. ## Other responses - `401`: Missing or invalid authentication token. - `404`: Resource not found. ## Changes - **2026-10-31** `5236ef291a8e`: 1 warning, 6 info - added the new `FREE` enum value to the `payment/status` response property for the response status `200` - added the optional property `payment/completedAt` to the response with the `200` status - added the optional property `payment/coupon` to the response with the `200` status - added the optional property `payment/discount` to the response with the `200` status - …3 more - **2026-10-31** `3cfd7392f4b9`: 3 info - added the optional property `payment/payer/email` to the response with the `200` status - added the optional property `payment/payer/phone` to the response with the `200` status - added the optional property `payment/recoveryKit` to the response with the `200` status - **2026-10-04** `2d3db0d1e23c`: 1 info - added the optional property `payment/methodData/cardFundingType` to the response with the `200` status - **2026-10-04** `f47924880ddf`: 1 warning - removed the optional property `payment/methodData/challengeUrl` from the response with the `200` status - **2026-10-02** `53025d2a4d12`: 1 breaking, 1 info - the response property `payment/methodData` became nullable for the status `200` - added the optional property `payment/methodData/challengeUrl` to the response with the `200` status [Operation history](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/changes/v1/payments/txid/:txId/get.md) --- [API](https://skmtc.dev/yuvexpay/apis/yuvexpay-api.md) - [All operations](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/revisions/57fb2913ed0b?raw)