Using an integrated checkout

Learn how to build your own checkout experience using the Payments API

1. Get payment token


Be aware

Integrated checkout is currently only available on v2 of the Payments API.

Start by generating a payment token. Make a HTTP POST request to the relevant endpoint + /api/oauth/token/ using the access token you generated.


curl --location --request POST '' 
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'grant_type=client_credentials' 
--data-urlencode 'client_id=<payment_key>'
--data-urlencode 'client_secret=<payment_secret>’


Try it out

If your request was successful you will receive a payment token like this in the response eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoxLCJzY29wZSI6WyJwYXkiXSwiaXNzIjoiaHR0cDovL2FwcC5kZXYucGF5dnluZS5zeXN0ZW1zIiwiZXhwIjoxNTg2MzY5NzExLCJpYXQiOjE1ODYzNjYxMTEsImF1dGhvcml0aWVzIjpbIlJPTEVfUEFZIl0sImp0aSI6ImExY2UzZjdmLTE3MzItNDhmNC04NTI3LTA5NWQ5NjlhNjkzNSIsImNsaWVudF9pZCI6IllNUFE2aDZQYTNaYmpEMXplbkQ0eXcifQ.g3XSXftyHvlCL1z1tlW6khboY7hzbiZVZgIzKHF2Rdc

2. Get banks

To return a paged list with the currently available banks and supported payment methods, make a HTTP GET request to the relevant endpoint + /api/v2/banks/availability/ including the headers Authorization: Bearer <payment_token>. You can use the same payment token generated in the first step.


curl --request GET
--header 'Authorization: <payment_token>'




Specifies the countries of which banks are returned. Values specified in two digit country codes. Contact support for supported countries. Default is GB


Specifies the start page. Value starts at 0.


Specifies the number of banks returned on each page. The page size must be 100 to 500. Default value is 150.


  "size": "25" ,
  "total": "25",
  "hasNext": "false",
  "elements": [
         "id": "<id>",
         "name": "Example Bank",
         "logoUrl": "<logo_url>"
         "paymentMethods": [




The number of banks on the page.


The total number of banks retrieved for the specified country.


Indicates if a next page is available. If true, the next page should be retrieved (e.g. using the request URL<country>&page=1, otherwise false.


Array of banks.


The ID of the bank.


The name of the bank.


The URL of the bank logo/icon.


List of the payment types supported by the bank. Possible values:

  • FASTER_PAYMENTS (GBP interbank)
  • SEPA_INSTANT (EUR interbank)

3. Present banks

In order to display the correct banks to the consumer its recommended to filter banks once obtained:

  1. Get all the pages from the get banks request until hasNext parameter is false.
  2. Filter out the banks based on payment methods they support. For example,
    • For GBP payments show only banks which support FASTER_PAYMENTS
    • For EUR payments show only banks which support SEPA_INSTANT or SEPA.

Read our checkout considerations when using the integrated checkout.


Be aware

Because the bank list and supported transaction types are only periodically updated, caching the banks from the get banks request is recommend, with an expiration time of 15-20 minutes. Note that banks or payment methods can still be added or removed if a bank is experiencing an issue.

4. Create payment request

Once the consumer has selected a bank, initiating a payment request is done in the standard way, with some additional parameters to specify the bank and consent details. Requesting with the bankId ensures the redirectUrl returned will be for the bank, rather than the hosted checkout

Send an HTTP POST request to the relevant endpoint + /api/v2/payments/ including the headers Authorization: Bearer <payment_token>. You can use the same payment token generated in the first step.


curl --location --request POST ''
--header 'Authorization: Bearer <payment_token>'
--header 'Content-Type: application/json'
--data 'payment-request.json'
  "amount": "5.95",
  "currency": "GBP",
  "destinationAccount": "GBP1",
  "description": "Web payment",
  "callbackUrl": "",
  "mediaType": "URL",
  "country": "GB",
  "customerReference": "P739570946",
  "bankId": "<bank_id>",
  "consentAt": "2021-01-01T12:32:00Z",
  "payerInformationDto": [
      "payerIdType": "IBAN",
      "payerId": "<payer_id>"





Amount to be paid by the payer.


The three-character payment currency using ISO 4217. Vyne supports GBP and EUR.


Specifies the ID of the merchant's destination bank account with Vyne (e.g. GBP1). More on bank accounts here.


A description that can be added to the transaction for merchant reference. This can be up to 250 characters and alphanumeric.


The URL the payer will be redirected back to after the authorisation is completed.


Specifies if the response should contain a URL to the payment page or a QR code. Accepted values are QR and URL. This field is optional and the default value is URL.


Country code of the payer bank. This is the same country code used in the get banks request.


Used to populate a merchant customer reference used in reconciliation. This can be up to 128 characters and alphanumeric.


Distinguishes between EUR connections supporting SCT (standard) and SCT Inst (enhanced) payments. Not required for GBP.


Specifies the ID of the payer's bank. It must be a valid bankId from get banks response.


A UTC timestamp indicating the date and time the payer accepted the consent. Format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'


Additional identification required for some European banks. This field is optional - contact support for specific requirements.


Specifies the type of identification. Possible values:

  • IBAN


The identification value.


The redirectURL in the response will contain a deeplink to the payer's bank. Redirect the user to this URL to allow them to authorise the payment.

  "redirectUrl": "<redirect_url>",
  "requestId": "adca2b6a077de1f5",
  "mediaType": "URL"

What’s Next

Once you've build your checkout, learn how to test your integration.

Did this page help you?