Get a Session

This endpoint returns a session key and a URL to be used for SDK requests. The only mandatory fields in the session request are email, firstName, and lastName. Additional data provided through the session API enables the payment functionality, maximizes our ability to decision payments, and enhances the user experience.

Headers

Content-Type String - (Required)
application-json

Accept String - (Required)
application-json

Authorization String - (Required)
header 'Basic <base64({CLIENT_ID}:{CLIENT_SECRET})>'

Parameters

firstName String - (Required)
Customer First Name

lastName String - (Required)
Customer Last Name

email String - (Required)
Customer Email

phoneNumber String - (Optional)
Customer Phone Number

billingAddress Object - (Optional)
Customer Billing Address View Object

orderDetails Object - (Optional)
Order Details View Object

customerProfile Object - (Conditional)
Customer information collected to increase authorization rate and prevent fraud View Object

paymentDetails Object - (Conditional)
Details of the payment View Object

product enum - (Optional)
PAY or VERIFY - indicates whether this session is for Pay by Bank or AccountVerify. Defaults to PAY

redirectUrl String - (Required)
URL customer will be redirected to after success or failure - must be pre-approved by Link Money

experienceId enum - (Optional)
Override default linking experience and enable payments directly from the Link Money UI, provide [LINK_MANAGED_PAYMENT] Learn more

Billing Address

streetAddress String - (Required)

city String - (Required)

stateOrProvince String - (Required)

postalCode String - (Optional)

country String - (Required)

Order Details

The following fields are part of the orderDetails object and are meant to collect information that will communice details about the order on the UI, additionally mitigating fraud, increasing conversion rate and maximizing risk decisioning accuracy.

items Array[Item] - (Optional)
List of Items View Object

subtotalAmount Object - (Conditional)
Base total not including customary charges or discounts. Required if any of discountAmount, shippingAmount, or taxAmount are populated.

discountAmount Object - (Optional)
Only accepted if subtotalAmount is populated

shippingAmount Object - (Optional)
Only accepted if subtotalAmount is populated

taxAmount Object - (Optional)
Only accepted if subtotalAmount is populated

totalAmount Object - (Required)
Total amount for the order

shippingAddress Object - (Optional)
Customer Shipping Address View Object

CustomerProfile

The following fields are part of the customerProfile object and are meant to collect customer information to provide the best experience possible by mitigating fraud, increasing authorization rate and maximizing risk decisioning accuracy.

id String - (Optional)
Unique Merchant-defined customer identifier. 128 character limit .

guestCheckout boolean - (Conditional)
Whether this is a registered or guest checkout. This field is not required for Account Verification requests.

accountCreationDate String - (Optional)
Timestamp in ISO-8601 format e.g. '2023-12-30T07:00:00-04:00' and '2023-12-30T07:00:00.1234-04:00'

transactionCount integer - (Optional)
The number of transactions a customer has previously made with the merchant.

firstTransactionDate String - (Optional)
Timestamp in ISO-8601 format e.g. '2023-12-30T07:00:00-04:00' and '2023-12-30T07:00:00.1234-04:00'

verifiedEmail boolean - (Optional)
Whether the customer’s email has been verified.

verifiedPhone boolean - (Optional)
Whether the customer’s phone has been verified.

paymentDetails

The following fields are part of the paymentDetails object and are only required if merchants intend for customers to initiate payments directly from the Link Money UI. They are not required for Account Verification requests. Merchants will need to pass the experienceId field with the value [LINK_MANAGED_PAYMENT].

amount String - (Required)
{ value: (float), currency: USD }

requestKey String - (Required)
Merchant-generated unique key for this specific payment call. This is used to avoid duplicate payment calls (idempotency). The payment call is rejected if a payment record already exists in the system with the same request key.

softDescriptor String - (Optional)
This is an optional freeform text field that will travel with the payment instruction to the RDFI. Please note that this information may or may not be displayed to the customer, based on the bank’s capabilities, and method of access (i.e., online banking, statement, etc.) - 80 Alphanumeric Character Limit.

clientReferenceId String - (Optional)
Unique merchant-generated ID that identifies this payment. This ID is stored along with the payment request. Optional.

Shipping Address

streetAddress String - (Required)

city String - (Required)

stateOrProvince String - (Required)

postalCode String - (Optional)

country String - (Required)

Items

description String - (Required)
Description of item

goodType enum - (Optional)
The type of item (Possible values: Physical, Digital)

amount String - (Required)
{ value: (float), currency: USD }

Returns

sessionKey String
A session key which establishes a trust between customer and Link

sessionUrl String
URL required for customer to be directed to for linking and payment

Post Request

POST - /v2/sessions

POST Request

1curl --location --request POST '{API_BASE_URL}/v2/sessions'
2--header 'Content-Type: application/json'
3--header 'Accept: application/json'
4--header 'Authorization: Basic <base64({CLIENT_ID}:{CLIENT_SECRET})>'
5--data-raw '{
6  "firstName" : "{CUSTOMER_FIRST_NAME}",
7  "lastName" : "{CUSTOMER_LAST_NAME}",
8  "email" : "{CUSTOMER_EMAIL}",
9  "phoneNumber" : "{CUSTOMER_PHONE_NUMBER}",
10  "billingAddress" : {
11    "streetAddress": string,
12    "city": string,
13    "stateOrProvince": string
14    "postalCode": string,
15    "country": string 
16  },
17  "orderDetails": {
18    "items": [{  
19        "description": string,
20        "goodType": enum
21        "amount": { "value": float, "currency": "USD" }
22      },
23      {
24        "description": string,
25        "goodType": enum
26        "amount": { "value": float, "currency": "USD" }
27      }],
28   "subtotalAmount": { "value": float, "currency": "USD" },
29    "discountAmount": { "value": float, "currency": "USD" },
30    "shippingAmount": { "value": float, "currency": "USD" },
31     "taxAmount": { "value": float, "currency": "USD" },
32    "totalAmount": { "value": float, "currency": "USD" },
33    "shippingAddress": {
34      "streetAddress": string,
35      "city": string,
36      "stateOrProvince": string
37      "postalCode": string,
38      "country": string
39   }},
40  "customerProfile":{
41     "id": string,
42    "guestCheckout": boolean,
43    "accountCreationDate": timestamp,
44    "transactionCount": integer,
45    "firstTransactionDate": timestamp,
46    "verifiedEmail": boolean,
47    "verifiedPhone": boolean
48  },
49  "paymentDetails": { 
50      "amount": {
51         "value": float,
52        "currency": "USD"
53      },
54      "requestKey": string,
55      "softDescriptor": string,
56      "clientReferenceId": string 
57  },
58  "product": enum, 
59  "redirectUrl": string,
60  "experienceId": enum
61  }'
62

Response Body

Response

{
"sessionKey" : "a5292de413e-2626d8244239-879a9-ffbdfa2",
"sessionUrl": "https://client.link.money?redirect={REDIRECT_URL}&version=web-v1.0.0&sessionKey={SESSION_KEY}"
}

Prior version: /v1/sessions