Make an immediate payment

Learn how to make an immediate payment using the Vitesse API, including a base example and variations for different payment methods, recipient options, and custom metadata.

Before you begin

• Authenticate requests using a valid access_token.
  For more information, see Requesting dynamic authorization tokens.
• Include the ID of the source account (SendAccountId) in the payment request.
  You can retrieve this ID by calling GET /merchantAccounts, for example.
• Use the correct base URL for your environment.
• Use webhooks to track payment status. For more information, see Webhooks.

Base example: Make an immediate payment

This example shows the default immediate payment flow: sending a local-currency payment to a recipient’s bank account.

Create the payment request

The structure of a payment request depends on the selected payment method, currency, and country combination. These factors determine which fields must be included in the request. Including fields that are not required for the selected combination will cause the request to fail. For more information, see Rules.

Specify both the SendCurrency and ReceiveCurrency in the request, even if the payment is local.

Set the payment amount using one of the following fields, but not both:

• SendValue – controls the amount debited from the source account
• ReceiveValue – controls the amount delivered to the recipient

For a complete list of fields, see Create a Payment Request.

{
  "SendAccountId": "3761",
  "SendCurrency": "GBP",
  "ReceiveCurrency": "GBP",
  "SendValue": 100.50,
  "Recipient": {
    "Type": "Person",
    "Name": "Janet Williams",
    "Country": "GB",
    "BankAccount": {
      "AccountNumber": "12345678",
      "SortCode": "123456"
    }
  },
  "PaymentMethod": "BankAccount",
  "PaymentDescription": "ID 53124",
  "RecipientReference": "Ref 123"
}

Send the request

Send:
POST /paymentRequests

If the request passes validation and sufficient funds are available in the account, the system processes the payment immediately.

📘

If funds are insufficient, the payment is queued indefinitely with a Pending status, and retried as soon as there are sufficient funds. Alternatively, you can cancel a queued payment request.

Check the response

If the request is successful, you’ll receive a response like this:

{
  "PaymentRequestId": "f8c1baf3-4e2f-4676-8e5c-29a04dce9cf4",
  "Status": "Initiated",
  "CreatedAt": "2026-01-29T10:15:00Z",
  "PaymentMethod": "BankAccount",
  "SendAccountId": 3761,
  "SendValue": 100.50,
  "SendCurrency": "GBP",
  "ReceiveCurrency": "GBP",
  "PaymentDescription": "ID 53124",
  "RecipientReference": "Ref 123",
  "Recipient": {
    "Type": "Person",
    "Name": "Janet Williams",
    "Country": "GB",
    "BankAccount": {
      "AccountNumber": "12345678",
      "SortCode": "123456"
    }
  }
}

📘

The response will contain additional fields. For the full response schema, see Retrieve a payment request.

The initial status depends on validation and balance checks. For more information, see Understand payment request statuses.

Monitor the payment

You can monitor progress by:

• Receiving webhook updates (recommended)
• Polling GET /paymentRequests/{id}

Payment method variations

Use the following variations to change how the payment is delivered to the recipient. All examples assume the base flow above.

SEPA payment via IBAN

Use this variation to send an immediate SEPA payment to a recipient in the EU. This example uses ReceiveValue to ensure the recipient receives a fixed EUR amount. The debited amount is calculated using FX rates at submission time.

 {
  "SendAccountId": 3761,
  "SendCurrency": "GBP",
  "ReceiveCurrency": "EUR",
  "ReceiveValue": 100.50,
  "Recipient": {
    "Type": "Person",
    "Name": "Janet Williams",
    "Country": "NL",
    "BankAccount": {
      "Iban": "NL91ABNA0417164300"
    }
  },
  "PaymentMethod": "BankAccount"
}

Postal cheque payment (US only)

Use this variation to send an immediate payment by postal cheque to a recipient's address in the United States.

{
  "SendAccountId": 3761,
  "SendCurrency": "USD",
  "ReceiveCurrency": "USD",
  "SendValue": 250.00,
  "Recipient": {
    "Type": "Person",
    "Name": "Jody Hausmann",
    "Country": "US",
    "Address": {
      "StreetName": "Main Street",
      "BuildingNumber": "123",
      "TownName": "New York",
      "PostCode": "10001",
      "CountrySubDivision": "NY",
      "Country": "US"
    }
  },
  "PaymentMethod": "PostalCheque"
}

eCheck payment (US only)

Use this variation to send an immediate eCheck payment to a recipient in the United States.

{
  "SendAccountId": 3761,
  "SendCurrency": "USD",
  "ReceiveCurrency": "USD",
  "SendValue": 150.75,
  "Recipient": {
    "Type": "Business",
    "Name": "AutoRepairs Ltd",
    "Email": "[email protected]",
    "Country": "US",
    "Address": {
      "StreetName": "Industrial Way",
      "BuildingNumber": "450",
      "TownName": "Chicago",
      "PostCode": "60601",
      "CountrySubDivision": "IL",
      "Country": "US"
    }
  },
  "PaymentMethod": "Echeck"
}

Provide recipient details

You can either enter recipient details or use a previously stored recipient.

To send a payment using a stored recipient, use one of the following identifiers:

• StoredRecipient.StoredRecipientId – assigned by Vitesse

• StoredRecipient.ExternalStoredRecipientId – your organisation's recipient reference

{
  "SendAccountId": 3761,
  "SendCurrency": "GBP",
  "ReceiveCurrency": "GBP",
  "SendValue": 100.50,
  "PaymentMethod": "BankAccount",
  "StoredRecipient": {
    "StoredRecipientId": "376184d2-d92d-49d0-8b99-fd7906885813"
  },
  "PaymentDescription": "Claim settlement",
  "RecipientReference": "CLAIM-456"
}

Add custom metadata

You can attach custom metadata to your payment using ExternalReference1, ExternalReference2, ExternalReference3, and the Extra object.

Use these parameters and the object to pass internal metadata, such as IDs or case references, for reconciliation and tracking purposes, or to link to internal systems.

{
  "ExternalReference1": "POLICY-998877",
  "ExternalReference2": "CLAIM-123456",
  "ExternalReference3": "CASE-ABC",
  "Extra": {
    "adjuster": "George Jackson",
    "priority": "high"
  }
}