Make a payment

Make a payment using recipient details. Supply those details in the request or reference a stored recipient.

Vitesse processes the payment without waiting for a scheduled payment run. If sufficient funds are unavailable, the request remains queued until funding becomes available.

Endpoints

EnvironmentMethod and URL
StagingPOST https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests
Production – UK HubPOST https://api.vitesse.io/v1/payment-initiation/paymentRequests
Production – US HubPOST https://api.us.vitesse.io/v1/payment-initiation/paymentRequests

For help choosing an environment, see Environment.

Access requirements

Configure the following access:

OAuth scopeIdentity client role
payment-requestspayment-requests.manager

For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.

Before you begin

  • Identify the account the payment should come from.
    Use List accounts to find the account and its AccountId.
  • Gather the recipient details required for the payment method, destination country and currency, or choose a stored recipient that contains them.
    Use Manage stored recipients to create or find a stored recipient.

Prepare the payment

Use the account and recipient information you gathered to build the request.

  1. Set SendAccountId to the source account’s AccountId.
  2. Set SendCurrency and ReceiveCurrency using three-letter currency codes, such as GBP.
    Specify both currencies even when they match.
  3. Supply either SendValue or ReceiveValue, but not both:
    • Use SendValue to specify the amount to send from the source account in the SendCurrency.
    • Use ReceiveValue to specify the amount the recipient should receive in the ReceiveCurrency.
  4. Set PaymentMethod to one of the following: BankAccount, Echeck or PostalCheque.
    See Payment methods for more information.
  5. Supply the recipient details in Recipient, or reference a stored recipient in StoredRecipient.
    For more information, see Manage stored recipients.

    📘

    The recipient details must meet the requirements for the chosen PaymentMethod, destination country and currency.

  6. Set RecipientReference to the payment reference intended for the recipient.
  7. If needed, add PaymentDescription and any internal references. For more information, see Add custom metadata below.
    These values help you match the payment to your records for tracking and reconciliation, for example:

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

Add custom metadata

Set RecipientReference to the payment reference you want the recipient to see.

Use ExternalReference1, ExternalReference2 and ExternalReference3 to record identifiers from your systems, such as invoice, policy, claim or case references. Use Extra to attach additional key-value pairs.

These fields help you match each payment request to your records for tracking and reconciliation.

Send the request

This example uses Staging to send 183.47 GBP from account 3761 to a recipient’s UK bank account:

curl --request POST \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "SendAccountId": 3761,
    "SendCurrency": "GBP",
    "ReceiveCurrency": "GBP",
    "SendValue": 183.47,
    "PaymentMethod": "BankAccount",
    "Recipient": {
      "Type": "Person",
      "Name": "Emily Carter",
      "Country": "GB",
      "BankAccount": {
        "SortCode": "123456",
        "AccountNumber": "12345678"
      }
    },
    "PaymentDescription": "Claim settlement",
    "RecipientReference": "CLM-5838386"
  }'

Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.

This example uses an existing stored recipient identified by its Vitesse-assigned StoredRecipientId:

curl --request POST \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "SendAccountId": 3761,
    "SendCurrency": "GBP",
    "ReceiveCurrency": "GBP",
    "SendValue": 183.47,
    "PaymentMethod": "BankAccount",
    "StoredRecipient": {
      "StoredRecipientId": "d872b36a-8e54-4c19-a627-9f03b1256e48"
    },
    "PaymentDescription": "Claim settlement",
    "RecipientReference": "CLM-5838386"
  }'

The required recipient fields depend on the payment method, destination country and currency.

Expected response

A successful request returns 200 OK with the payment details, confirming that Vitesse created the request. It does not confirm that the recipient has received the payment.

Vitesse automatically sends the payment after checking the request and confirming that sufficient funds are available. If funding is insufficient, Vitesse queues the request.

Retain PaymentRequestId to track the payment or request cancellation.

Monitor the payment

Subscribe to webhook events or retrieve the payment using its PaymentRequestId to track its progress. Check its status to determine the outcome rather than submitting another payment.

For notifications, see Webhooks. For statuses and their meanings, see Payment lifecycle.

Troubleshoot the request

If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.

Check that:

  • You supplied the required account, payment and recipient details.
  • You supplied either SendValue or ReceiveValue, rather than both.
  • The recipient details meet the requirements for the payment method, destination country and currency.
    For more information, see Rules​.
  • The access token contains the required scope and the identity client has the required role.

For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.

Handle a timeout

A timeout or lost connection does not confirm that Vitesse failed to receive the request. To make a payment request safe to retry, include an Idempotency-Key header in the original request and save the key with the request.

Retry a time-out request

In this example, the original request used the body and key shown below, but timed out before a response arrived. The curl command shows the retry: resend the same request to the same endpoint with the same Idempotency-Key and unchanged body.

curl --request POST \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: b1f2f3a4-65db-46f7-b890-2d42e91f8c77' \
  --data '{
    "SendAccountId": 3761,
    "SendCurrency": "GBP",
    "ReceiveCurrency": "GBP",
    "SendValue": 183.47,
    "PaymentMethod": "BankAccount",
    "Recipient": {
      "Type": "Person",
      "Name": "Emily Carter",
      "Country": "GB",
      "BankAccount": {
        "SortCode": "123456",
        "AccountNumber": "12345678"
      }
    },
    "PaymentDescription": "Claim settlement",
    "RecipientReference": "CLM-5838386"
  }'

When you receive a response, use its PaymentRequestId to track the request. Reuse the same key and body for retries of this payment request. If you change the request parameters while reusing the key, Vitesse returns 400 Bad Request with DuplicateIdempotencyKey. Use a new key for a new payment request.

If the original request did not include an Idempotency-Key, adding one to a retry will not prevent a duplicate. Check whether Vitesse created the request before submitting it again.

Next steps

Continue monitoring the payment until you know its outcome. If you no longer want to proceed, see Cancel a payment for the conditions and procedure for cancellation.