Make a payment using Payee Choice

Use Payee Choice when the recipient needs to choose how to receive a payment and provide their payment details. Create the request through the standard payment request endpoint and include a Recipient.Capture object that references an active programme.

This topic describes the API flow. For the general payment request fields and payment details, see Make a payment​.

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

Use the following endpoints and your own records to collect the values you need to make a Payee Choice payment:

  • Identify an active programme for the Payee Choice flow and note its ProgrammeId.
    Use List programmes​​ to find programmes.
    For information about programmes, see Programmes​.
  • Choose the source account and payment methods for the request.
    Use Search programme accounts to find eligible accounts. Select one and note its AccountId.
    Use List payment methods permitted for a programme to choose which payment methods to offer the recipient.
  • If you have configured Vitesse to email the recipient, obtain any trust information required by the programme, such as a claim or policy number.

Prepare the payment request

  1. Use the steps in Make a payment to build each request, including references and custom metadata.
  2. For Payee Choice, add a Capture object under Recipient and set its ProgrammeId.
  3. Set Capture.AllowedPaymentMethods if you want to offer only some of the payment methods enabled for the programme.
    The request can narrow the programme's set of methods, but it cannot add methods the programme does not support.
  4. If the programme sends the recipient a call-to-action email, include any trust method values required by that programme in Capture.TrustMethods.
    If the programme is configured not to send that email, your integration must deliver the secure link to the recipient. The RecipientCaptureInitiated webhook includes the link. See Recipient capture events​.

Send the request

This example uses Staging to request a payment of 183.47 GBP from account 3761. It assumes the programme supports bank account payments and requires a claim number in its call-to-action email.

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,
    "Recipient": {
      "Type": "Person",
      "Name": "Emily Carter",
      "Email": "[email protected]",
      "PhoneNumber": "+447700900123",
      "Country": "GB",
      "Capture": {
        "ProgrammeId": "42ea67d3-30d9-4143-848a-15cd59878ccd",
        "AllowedPaymentMethods": [
          "BankAccount"
        ],
        "TrustMethods": [
          {
            "TrustMethodId": "claim-number",
            "Value": "CLM-5838386"
          }
        ]
      }
    },
    "PaymentDescription": "Claim settlement",
    "RecipientReference": "CLM-5838386",
    "ExternalReference1": "POLICY-998877"
  }'

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

Include the required recipient contact details for the payment type.

Expected response

A successful request returns 200 OK with the payment request details, including its PaymentRequestId. This confirms that Vitesse created the payment request. It does not confirm that the recipient has provided payment details or that the payment has been sent.

Retain the PaymentRequestId to track the request, match it to your records or request cancellation.

Deliver the secure link

If the programme sends a call-to-action email, Vitesse sends the recipient a link to provide their details.

If the programme does not send that email, subscribe to the RecipientCaptureInitiated webhook and use the secure link in its Data.Link field to contact the recipient. For webhook setup and event payloads, see Webhook subscription event reference.

Monitor the payment

Subscribe to webhook events or retrieve the payment request using its PaymentRequestId to track its progress.

The recipient capture flow can generate events such as:

  • RecipientCaptureInitiated – the recipient capture process has started.
  • RecipientCaptureCompleted – the recipient has selected a payment method and provided the required details.
  • RecipientCaptureExpired, RecipientCaptureDeclined or RecipientCaptureVerificationAttemptFailed – the recipient did not complete the capture flow successfully.

After the recipient provides their details, Vitesse can create and process the payment. If funds are insufficient, the request may remain queued until funds become available. Track the payment request through its final outcome. Do not assume that capture completion means the payment has succeeded.

For status meanings, see Payment lifecycle. For webhook setup, see Webhooks.

Recipient capture

For Payee Choice, the recipient uses the secure capture link to provide the payment details needed for the payment. These states show what has happened in that process.

While capture is active, the payment request has status InputNeeded. The webhook reports the capture event. The payment request status shows how the request proceeds. After the recipient submits valid details, track the request through Payment lifecycle.

Capture stateWhat causes itWebhook eventPayment request status
ActiveVitesse starts recipient capture and makes the secure link available.RecipientCaptureInitiatedInputNeeded
CompletedThe recipient submits valid payment details.RecipientCaptureCompletedPending or a later lifecycle status
CancelledSomeone either cancels capture or the payment request.RecipientCaptureCancelledCancelled
ExpiredThe link expires before the recipient submits valid details.RecipientCaptureExpiredUnsuccessfulInput
DeclinedThe recipient declines to provide their details.RecipientCaptureDeclinedUnsuccessfulInput
BlockedThe recipient enters an incorrect passphrase five times.RecipientCaptureBlockedUnsuccessfulInput

Troubleshoot the request

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

Check that:

  • ProgrammeId identifies an active programme.
  • The source account is eligible for that programme.
  • Any AllowedPaymentMethods in the request are supported by the programme.
  • The recipient details and any required trust information match the programme's configuration.
  • The access token contains the required scope and the identity client has the required role.

If the recipient has not completed the capture flow, check the capture events and the request status before taking further action.

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

Next steps

Continue monitoring the payment request until you know its outcome. If you need to stop the request, see Cancel a payment.