# 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`.
  * Note : This is a required sender-created ID to use with 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": "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 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": "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,
  "fees": [
    {
      "totalFee": 14,
      "feeCurrency": "USD"
    }
  ],
  "purposeCode": "PAYR"
}
```

## 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"
    }
  ]
}
```