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.

Request

curl --location --request POST 'https://uat.app.payvyne.com/api/oauth/token' 
--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.

Request

curl --request GET
'https://uat.app.payvyne.com/api/v2/banks/availability?country=<country>&page=<page>&size=<pageSize>'
--header 'Authorization: <payment_token>'

Parameter

Description

country

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

page

Specifies the start page. Value starts at 0.

pageSize

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

Response

{
  "size": "25" ,
  "total": "25",
  "hasNext": "false",
  "elements": [
     {
         "id": "<id>",
         "name": "Example Bank",
         "logoUrl": "<logo_url>"
         "paymentMethods": [
             "FASTER_PAYMENTS",
             "SEPA_INSTANT"
         ]
     },
    ...
    ]
}

Parameter

Description

size

The number of banks on the page.

total

The total number of banks retrieved for the specified country.

hasNext

Indicates if a next page is available. If true, the next page should be retrieved (e.g. using the request URL
https://uat.app.payvyne.com/api/v1/banks/availability?country=<country>&page=1, otherwise false.

elements

Array of banks.

id

The ID of the bank.

name

The name of the bank.

logoUrl

The URL of the bank logo/icon.

paymentMethods

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.

Request

curl --location --request POST 'https://uat.app.payvyne.com/api/v2/payments'
--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": "yoursite.com/payment-outcome-page",
  "mediaType": "URL",
  "country": "GB",
  "customerReference": "P739570946",
  "bankId": "<bank_id>",
  "consentAt": "2021-01-01T12:32:00Z",
  "payerInformationDto": [
    {
      "payerIdType": "IBAN",
      "payerId": "<payer_id>"

    }
  ]
}

Parameter

Description

amount

Amount to be paid by the payer.

currency

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

destinationAccount

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

description

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

callbackURL

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

mediaType

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

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

customerReference

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

serviceType

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

bankId

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

consentAt

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

payerInformationDto

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

payerIdType

Specifies the type of identification. Possible values:

  • IBAN
  • EMAIL

payerId

The identification value.

Response

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?