GuidesAPI ReferenceSDKsSandbox

Preset Deep Linking

Suggest Edits

Veem supports the ability to preset key information on our main transaction flows through the means of the URL. This can be relevant when attempting to be paid by your clients, or for generating invoices to you.

Providing preset specifiers on the URL allows Veem to digest this data internally and provide a seamless experience to your clients on our platform. Below are steps to customize external links to our application.

What to expect - from an integration perspective

Integrating to this system, you can expect to be able to provide predefined field values for any of your clients accessing Veem through this link. If this information is known by you when proving a link to Veem to your clients, it may be advantageous to provide these in order to expedite their experience in our application.

🚧

Be aware of limitations

If creating preset deep link URL paths for your clients in a marketplace model, please note that you will not receive direct updates on the funds transfer given that you are neither the send nor receiver of those funds.

However, if you would like to receive a reference key to the created transaction in order to track its status progression (such as with webhooks), you can read more on Veem Web SDK.

What to expect - from a user's perspective

For your clients utilizing your generated deep link URLs, they will see a streamlined experience in our application, as many of the core fields can be autofilled.

If your client is not logged into Veem when accessing this link, they will be prompted to login in order to access this URL. If your clients do not have a Veem account, they will be invited to register for an account. Once onboarded, they will be redirected back to your original URL.

🚧

Preset context is not locked

Your clients will still be able to modify these fields, if they deem them to be inaccurate.

Interface - Supported properties

Authenticated User

Below are the currently supported keys that can be passed through the URL in order to define preset values:

  • accountId
  • referenceId
  • payeeAmount (should be coupled with payeeCurrencyCode)
  • payeeCurrencyCode (should be coupled with payeeAmount)
  • payerAmount (should be coupled with payerCurrencyCode)
  • payerCurrencyCode (should be coupled with payerAmount)
  • purposeOfPayment (it's important that these resolve to Veem-supported POP values)
  • purposeOfPaymentDescription (Only used if purposeOfPayment is specified)
  • invoiceNumber
  • payeeDisplayName
  • payerDisplayName
  • liteInvoice (only applicable to send invoice flow)

📘

Presets are experience enhancers

No preset key/value pair is required in order for your clients to initiate a transaction; they are specified in order to streamline their experience in Veem by autofilling key fields of our payment and invoice creation forms. So only specify values that you think are accurate and valuable to your client.

Guest User

There is the option for the user to send a payment as a guest where they do not need to be authenticated but only require an email.

Below are the currently supported keys that can be pass through the URL in order to define preset values:

  • referenceId
  • payerAmount (should be coupled with payerCurrencyCode)
  • payerCurrencyCode (should be coupled with payerAmount)
  • payerFirstName
  • payerLastName
  • payerMiddleName
  • payerExtraName
  • payerBusinessCountryDialCode
  • payerBusinessPhoneNumber
  • payerBusinessName
  • payerBusinessCity
  • payerBusinessCountryCode
  • payerBusinessPostalCode
  • payerBusinessStateProvince
  • payerBusinessStreet
  • payerBusinessStreetSecondary
  • payerTaxId
  • purposeOfPayment (it's important that these resolve to Veem-supported POP values)
  • purposeOfPaymentDescription (Only used if purposeOfPayment is specified)

🚧

Required preset

For the guest to send a payment, the referenceId preset is required to ensure that there is a payee available to receive the payment. Currently, your guest client won't be able to select a payee inside the guest send payment experience.

📘

Directionality is important

The payer* and payee* specifiers are to be contextually accurate to the type of transaction your client is to complete.

For example, if declaring funds to be sent from a payment, you should specify payerAmount and payerCurrencyCode. If declaring funds to be received from a payment, you should specify payeeAmount and payeeCurrencyCode.

The inverse applies for invoices and payment requests; to declare funds to be received by your client, specify payeeAmount and payeeCurrencyCode. To declare funds to be sent to your client, specify payerAmount and payerCurrencyCode.

Building your custom URL

It's important to navigate your clients to the correct route within the Veem application. The current routes supporting these preset values are as follows, with their corresponding base path:

To these URLs, you will incorporate your custom preset values, by adding an URL-encoded value under the ?preset query parameter.

The ?preset query parameter value should be an URL-encoded string of key:value pairs separated by semi colons. Below, we'll write our first deep link together:

  1. Build your string of preset values, respecting the syntax structure: every value is separate by a semi-color (;), while key-value pairs are separate by a colon (:). For example:
accountId:67744;payeeAmount:1000;payeeCurrencyCode:USD;purposeOfPayment:Goods;purposeOfPaymentDescription:Goods description
  1. We'll encode this string for use in a URL. For ease of testing, we can encode this string with one of the many online tools made available to us:
accountId%3A67744%3BpayeeAmount%3A1000%3BpayeeCurrencyCode%3AUSD%3BpurposeOfPayment%3AGoods%3BpurposeOfPaymentDescription%3AGoods%20description
  1. We will add this value to one of the base URLs specified above. Note that we want to apply our URL-encoded string value to the preset query parameter:
https://apps.veem.com/CustomerApp/Dashboard/SendPayment?preset=accountId%3A67744%3BpayeeAmount%3A1000%3BpayeeCurrencyCode%3AUSD%3BpurposeOfPayment%3AGoods%3BpurposeOfPaymentDescription%3AGoods%20description

📘

Some technical notes

If the URL is malformed or incorrectly structuring the preset information, your clients should see a graceful fallback to a non-contextualized experience; we try to auto-populate what data we are provided, but if a specific preset value is invalid, we will skip that specific field to be auto-populated. Providing preset context is an experience augmentation for your clients.

For most countries, the allowable values for purposeOfPayment are: Goods, Services and Charitable Donation.

Updated over 1 year ago