Skip to main content

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]

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