# Create a v2 payment In this tutorial, we'll step through the API calls required to create a B2B payment. In a B2B payment, you — a business or institution — are the payment originator and you're paying another business or institutional beneficiary. Note While this tutorial focuses on paying a business beneficiary, the process is similar for paying an individual beneficiary. To pay an individual beneficiary, specify their `beneficiaryIdentityId` in the [Create payment](#create-payment) step. There are three main steps for creating a payment where you are the originator: 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 details about the initiated payment. ## Prerequisites You must have the following items to be able to carry out the steps in this tutorial: * An [access token](/products/payments-direct-2/v2025.11/api-docs/tutorials/request-an-access-token) to access secured API endpoints. * Obtain the beneficiary `identityID` using the Get identities v2 operation in the API reference. ## Create a quote collection We'll begin by calling the Create quote collection operation to get a quote for the payment. ## Create payment Now that we have the quote for the payment, it's time to create the payment using the `quoteId`. 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 accept from the [create a quote](#create-quote-collection-response) response. * You must have the `identityId` of the beneficiary. Construct the request body as follows: * `quoteId` : Set this value to the `quoteId` you received in the Create quote collection response. * `beneficiaryIdentityId` : Set this value to the UUID associated with the [beneficiary identity](/products/payments-direct-2/v2025.11/api-docs/tutorials/building-v2-payment-request-body#beneficiaryidentityid). * `internalId` : This example uses `Invoice-123`. This is an optional sender-created reference (maximum 36 characters) for correlating payments with your own records and filtering in other API operations. * `purposeCode` : This example uses `PAYR` to indicate that the purpose of this payment is payroll. * `sourceOfCash` : This example uses `SVGS` to indicate that the source of cash for this payment is savings. ```json { "quoteId": "7ea3399c-1234-5678-8d8f-d320ea406630", "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222", "internalId": "Invoice-123", "purposeCode": "PAYR", "sourceOfCash": "SVGS" } ``` ### Create payment response A success response from the API 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": "PRE_FUNDING" }, "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 payment ID](/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/getpaymentbyid) operation to look up the status of a payment. ### Get payment request Use the `paymentId` path parameter to specify the unique ID of the payment whose status you want to monitor. ### Get payment response Check the `paymentState` field in the response 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": "INITIATED", "originator": { "internalId": "Invoice-123", "sourceCountry": "US", "sourceCurrency": "USD", "sourceAmount": 10000, "payin": "PRE_FUNDING" }, "destination": { "destinationAmount": 203766.88, "destinationCountry": "MX", "destinationCurrency": "MXN", "beneficiaryIdentityId": "22222222-aaaa-2222-bbbb-222222222222", "beneficiaryIdentityVersion": 1, "beneficiaryIdentityNickName": "Successful Beneficiary", "payout": "BANK" }, "fxRate": 20.4052, "fees": [ { "totalFee": 14, "feeCurrency": "USD" } ], "purposeCode": "PAYR", "payoutExecutionDetails": { "paymentRailUsed": "ACH", "payoutStartTime": "2025-02-13T23:25:00.000Z", "payoutEndTime": "2025-02-13T23:34:54.000Z", "trackingReferences": [ { "referenceType": "IMAD", "value": "20250213MMQFMP9N000123", "displayName": "IMAD Number", "description": "Input Message Accountability Data (IMAD) for Fedwire transfer tracking" } ] } } ``` payoutExecutionDetails `payoutExecutionDetails` is an optional field returned only by `GET /v2/payments/{paymentId}`. It provides informational metadata about payout execution: the rail used (`paymentRailUsed`), timing (`payoutStartTime`, `payoutEndTime`), and network-specific tracking references (`trackingReferences`). Coverage varies by corridor and payout partner. Do not build required workflows that depend on its presence. Use the `referenceType` field on each tracking reference to identify what a value represents, for example, `IMAD` and `OMAD` for Fedwire transfers. ## Get state transitions In addition to getting the current state of a payment, you can also use the [get state transitions](/products/payments-direct-2/v2025.11/api-docs/payments-direct-api/payments-direct-2-api/payments/getpaymentstatetransitionsbyid) operation to see when the payment transitioned between states. ### Get state transition response Examine the response to view the state transitions. ```json { "stateTransitions": [ { "updatedFrom": "QUOTED", "updatedTo": "INITIATED", "updatedAt": "2025-02-21T15:32:34.557Z" }, { "updatedFrom": "INITIATED", "updatedTo": "VALIDATING", "updatedAt": "2025-02-21T15:32:38.380Z" }, { "updatedFrom": "VALIDATING", "updatedTo": "TRANSFERRING", "updatedAt": "2025-02-21T15:32:49.552Z" }, { "updatedFrom": "TRANSFERRING", "updatedTo": "COMPLETED", "updatedAt": "2025-02-21T15:34:54.496Z" } ] } ```