# Create a v2 third-party payment In this tutorial, we'll step through the API calls required to create a third-party payment with the legacy Payments v2 and Identity Management v2. In a third-party payment, you process payments on behalf of a third-party business or institution which is paying a business or individual beneficiary. Note While this tutorial focuses on creating a payment on behalf of a business to pay another business beneficiary, the process is similar for making a payment to an individual beneficiary. To pay an individual beneficiary, specify their `beneficiaryIdentityId` in the [Create payment](#create-payment) step. There are four main steps for creating a third-party payment where you are the intermediary: 1. [Create a quote collection](#create-a-quote-collection) for a proposed payment. 2. [Create payment](#create-payment) to begin the payment process. 3. [Get a payment](#get-a-payment) to view your completed payment. For instructions on creating a payment where you — a business or institution — are the originator, see [Create a v2 payment](/products/payments-direct-2/v2025.11/api-docs/tutorials/create-a-v2-payment). ## Prerequisites The following items must be addressed before you can carry out the instructions in this tutorial: * An [access token](/products/payments-direct-2/v2025.11/api-docs/tutorials/request-an-access-token) to access secured API endpoints. * Have obtained the necessary `identityIDs`. Work with your Ripple liaison to get them. * A `beneficiaryIdentityId` identifies the beneficiary of your payment and is required for all payments. * An `originatorIdentityId` is required when performing third-party payments. Base URL for the UAT environment The API calls in this tutorial use the **UAT** environment with `https://api.test.ripple.com/v2` as the base URL. ## Create a quote collection In this step, we call the **Create quote collection** operation, which fetches a collection of quotes containing one or more quotes for a payment using the chosen payout method. ### Create quote collection request In our payment scenario, a third-party is sending 10,000 USD to a beneficiary in Mexico, who will receive it in MXN. So now we can construct the request body to fetch a quote. This example shows how to construct the request body. * `quoteAmount` : Set this value to `10000`. * `sourceCurrency` : Set this value to `USD`. * `quoteAmountType` : Set this value to `SOURCE_AMOUNT`. * Setting this value returns a quote for the amount you want to send and not the amount the beneficiary receives. * For more information, see the quoteAmountType parameter in the Create quote collection operation. * `destinationCurrency` : Set this value to `MXN`. * `sourceCountry` : Set this value to `US`. * `destinationCountry` : Set this value to `MX`. * `payoutCategory` : Set this value to `BANK`. * `payinCategory` : Set this value to `FUNDED`. #### Example quote collection request payload ```json { "quoteAmount": 10000, "quoteAmountType": "SOURCE_AMOUNT", "sourceCurrency": "USD", "destinationCurrency": "MXN", "sourceCountry": "US", "destinationCountry": "MX", "payoutCategory": "BANK", "payinCategory": "FUNDED" } ``` ### Create quote collection response The response contains an array of one or more quote objects as a collection. Each quote object has a unique `quoteId`, and each quote contains quote elements that correspond to each step of the payment transaction and include account addresses, amounts, foreign exchange (FX) rates, and fees for each step. Quotes have an expiration date Each quote includes an `expiresAt` field that indicates the expiration date and time of the quote. You must create a payment using the `quoteId` prior to expiration. ```json { "quoteCollectionId": "11111111-aaaa-2222-bbbb-222222222222", "quotes": [ { "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "quoteStatus": "ACTIVE", "quoteAmountType": "SOURCE_AMOUNT", "sourceAmount": 10000, "destinationAmount": 204533.3, "sourceCurrency": "USD", "destinationCurrency": "MXN", "sourceCountry": "US", "destinationCountry": "MX", "payoutCategory": "BANK", "payinCategory": "FUNDED", "adjustedExchangeRate": { "adjustedRate": 20.4136 }, "fees": [ { "totalFee": 14, "feeCurrency": "USD", "feeBreakdown": [ { "calculatedFee": 3, "feeName": "Example flat service fee", "feeDescription": "Fees with unit 3$ FLAT" }, { "calculatedFee": 11, "feeName": "Example BPS service fee", "feeDescription": "Fees with unit BPS" } ] } ], "createdAt": "2025-02-13T22:44:34.711Z", "expiresAt": "2025-02-13T22:59:34.767Z" } ] } ``` ## Create payment Now that we have the quote for the payment, it's time to create a payment using the `quoteId` and the `identityId` values. To do this, we'll call the Create payment operation. ### Create payment request Prerequisites * You must have the `quoteId` of the quote you want to use from the [create a quote](#create-quote-collection-response) response. * You must have the identity IDs. Construct the request body as follows: * `quoteId` : Set this value to the `quoteId` you received in the Create quote collection response. * `originatorIdentityId` : Set this value to the UUID associated with the [originator identity](/products/payments-direct-2/v2025.11/api-docs/building-payment-request-body#originatoridentityid). * `beneficiaryIdentityId` : Set this value to the UUID associated with the [beneficiary identity](/products/payments-direct-2/v2025.11/api-docs/building-payment-request-body#beneficiaryidentityid). * `internalId` : This example uses `Invoice number 123`. * `purposeCode` : This example uses `PAYR` to indicate that the [Purpose](/products/payments-direct-2/v2025.11/api-docs/building-payment-request-body#purposecode) is payroll. * `SourceOfCash` : This example uses `SVGS` to indicate that the [Source of Cash](/products/payments-direct-2/v2025.11/api-docs/building-payment-request-body#sourceofcash) is savings. ```json { "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "originatorIdentityId": "11111111-abcd-2222-efgh-333333333333", "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222", "internalId": "Invoice-123", "purposeCode": "PAYR", "sourceOfCash": "SVGS" } ``` ### Create payment response The payment creation response contains the `paymentId` and other information you can use to monitor the status of the payment. ```json { "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630", "initiatedAt": "2025-02-13T23:24:15.770Z", "expiresAt": "2025-04-14T23:24:15.770Z", "lastStateUpdatedAt": "2025-02-13T23:24:15.770Z", "paymentState": "TRANSFERRING", "originator": { "internalId": "Invoice-123", "sourceCountry": "US", "sourceCurrency": "USD", "sourceAmount": 10000, "payin": "FUNDED" }, "destination": { "destinationAmount": 203766.88, "destinationCountry": "MX", "destinationCurrency": "MXN", "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222", "beneficiaryIdentityVersion": 1, "beneficiaryIdentityNickName": "Successful Beneficiary", "payout": "BANK" }, "fxRate": 20.4052, "adjustedExchangeRate": { "adjustedRate": 20.3422 }, "fees": [ { "totalFee": 14, "feeCurrency": "USD" } ], "purposeCode": "PAYR", "transactionDetails": { "paymentProduct": "PAYMENTS_DIRECT", "flowType": "B2B", "thirdPartyPayment": false, "businessUseCase": "FIAT_TRANSFER" } } ``` ## Get a payment Use the Get payment by ID operation to view the details of your completed payment. ### Get payment request ### Get payment response Check the `paymentState` field in the response output for the current payment state. ```json { "paymentId": "7ea3399c-1234-5678-8d8f-d320ea406630", "initiatedAt": "2025-02-13T23:24:15.770Z", "expiresAt": "2025-04-14T23:24:15.770Z", "lastStateUpdatedAt": "2025-02-13T23:24:15.770Z", "paymentState": "TRANSFERRING", "originator": { "internalId": "Invoice-123", "sourceCountry": "US", "sourceCurrency": "USD", "sourceAmount": 10000, "payin": "FUNDED" }, "destination": { "destinationAmount": 203766.88, "destinationCountry": "MX", "destinationCurrency": "MXN", "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222", "beneficiaryIdentityVersion": 1, "beneficiaryIdentityNickName": "Successful Beneficiary", "payout": "BANK" }, "fxRate": 20.4052, "adjustedExchangeRate": { "adjustedRate": 20.3422 }, "fees": [ { "totalFee": 14, "feeCurrency": "USD" } ], "purposeCode": "PAYR", "transactionDetails": { "paymentProduct": "PAYMENTS_DIRECT", "flowType": "B2B", "thirdPartyPayment": false, "businessUseCase": "FIAT_TRANSFER" } } ```