# Payments

Use these API operations to manage your payments with **Payment Management v3** (recommended for all new integrations).
| Operation | Method | Description |
|  --- | --- | --- |
| [Search payments](#operation/searchPaymentsV2) | POST | Search for payments based on filtering criteria. |
| [Create a payment](#operation/createPaymentV2) | POST | Create a payment by accepting a quote. |
| [Get payment by payment ID](#operation/getPaymentByIdV2) | GET | Get a specific payment by payment ID. |
| [Get state transitions by payment ID](#operation/getPaymentStateTransitionsByIdV2) | GET | Get the state transitions for a specific payment by payment ID. |
| [Update payment labels](#operation/updatePaymentLabelsV2) | PATCH | Update the labels for a specific payment by payment ID. |

 - [POST /v3/payments/filter](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/searchpaymentsv2.md): Returns a paginated list of payments matching the specified filters. You can filter by status, date range, destination country, currency, or custom labels.
 - [POST /v3/payments](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/createpaymentv2.md): Initiates a new cross-border payment. Payments are processed asynchronously. Use **Get a payment by ID** to poll for status updates, or **Get state transitions** to view the full status history.
 - [GET /v3/payments/{paymentId}](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/getpaymentbyidv2.md): Returns the current status and full details of a payment, including amounts, beneficiary information, and the associated quote.
 - [GET /v3/payments/{paymentId}/states](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/getpaymentstatetransitionsbyidv2.md): Returns the complete state transition history for a payment, including each status change and its timestamp. Use this to audit payment progress or debug processing issues.
 - [PATCH /v3/payments/{paymentId}/labels](https://docs.ripple.com/pt-br/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/paymentsv2/updatepaymentlabelsv2.md): Add or remove labels for grouping and categorizing payments (e.g., campaign IDs, workflow tags, or batch identifiers). Labels are optional and mutable; they can be added or removed over the payment's