Payments API Reference

The Payments API is currently in Early Access - please contact us for more information.

Lean’s Payments API supports bank-to-bank transfers from your customer’s account to your business account. There are three steps required to use the Payments API with your customers:

  1. Set up your payment details.
  2. Enable customer payments from a nominated account.
  3. Initiate payment from a customer account to your account.

Set up payment details

To enable payments for your customers, you first need to provide Lean with your business‘s bank details for your customers to transfer funds to.

To do this, speak to your product representative at Lean.

View required information bank details

Contact Details

Nick Name

First Name

Last Name

Email Address

Telephone Number

SMS


Account Details

Bank Name

Bank Address

Swift Code

Account Number

IBAN

Was this section helpful? 

Create a new Customer

A Customer object is a container for all the billing details for your customer and should map on a one-to-one basis with users in your platform. To create a Customer object, make a call to the Customer API endpoint with your application token in the header and the related user ID in your own database.

A new Customer object will be returned, and the customer_id should be saved in your own database.

Request

app_user_id String

The user ID in your own user table. This is to allow you to easily reconcile users and customers in the future.

Response

app_user_id String

The user ID you assigned the customer during creation.


customer_id String

A UUID identifying the customer for future calls.


Was this section helpful? 

bash

curl -X POST 'https://api.leantech.me/customers/v1/' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \
--data-raw '{
"app_user_id": "001"
}'

json

{
app_user_id: "001",
customer_id: "f08fb010-878f-407a-9ac2-a7840fb56185"
}

Create a Payment Source

Next, you need to enable a payment source for your customer. You can enable multiple payment sources for a customer with different banks.

Please note: dependent on the bank, a cooling-off period up to 24 hours will come into effect before you can make transfers between the customer account and your own account.

To create a payment_source you will need to have the Link SDK available in your application.

Request

customer_id String

The Customer object you want to create a payment source for.


Returns

status ENUM

Indicates success or failure of the connection process.


Webhooks

Once a payment_source is successfully created, a webhook will be sent to your server notifying you of the creation. If the status of a source is AWAITING_BENEFICIARY_COOL_OFF, a second webhook will be sent when the payment source becomes ACTIVE at the end of the cooling-off period, which can take up to 24 hours, depending on the bank.

Was this section helpful? 

javascript

Lean.createPaymentSource({
app_token: "2c9280887230f322017231b408cf0007",
customer_id: "f08fb010-878f-407a-9ac2-a7840fb56185"
})

json

{
status: "200 OK"
}

json

// Webhook response
{
"type": "payment_source.created",
"payload": {
"id": "838af9d4-d77d-4a1e-bc9d-e4f6067ec9a3",
"customer_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"status": "AWAITING_BENEFICIARY_COOL_OFF",
"bank_identifier": "HSBC_UAE",
"bank_name" : "HSBC"
},
"message": "A payment source was preauthorized by your customer.",
"timestamp": "2020-07-31T07:11:39.862804Z"
}
// Payment source ACTIVE
{
"type": "payment_source.updated",
"payload": {
"id": "838af9d4-d77d-4a1e-bc9d-e4f6067ec9a3",
"customer_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"status": "ACTIVE",
"bank_identifier": "HSBC_UAE",
"bank_name" : "HSBC"
},
"message": "A payment source has been updated.",
"timestamp": "2020-07-31T07:11:39.862804Z"
}

Payment Intents

Before you can initiate a payment for a customer, you will need to create a payment intent for the value of the transaction you wish to make from your backend to Lean.

Request

amount Int

The value of the transaction.


currency String

The three-letter ISO code for the currency you’re trying to process the payment in.


customer_id String

The customer you want to bill for this transaction.


Response

payment_intent_id String

This ID will need to be passed to your application to input to the Link SDK and to retrieve updates on the payment in the future.


Was this section helpful? 

bash

curl -X POST api.leantech.me/payments/v1/intents \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \
--data-raw '{
"amount": 400,
"currency": "AED",
"customer_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4"
}'

json

{
payment_intent_id: "452bcde4-5e48-44bb-8f6d-40c5c286466b"
}

Querying Payment Sources

Once a payment source is created, you can monitor the status of the source with the payment-source endpoint.

Request

customer_id String

The UUID returned when creating a new customer.


payment_source_id String

The payment source you want to check the status of.


Response

id String

The ID of the payment source requested.

customer_id** String

The customer ID for the requested payment source.

bank String

The friendly name of the bank that is tied to the payment source.

status ENUM

The current status of the payment source.

View statuses

ACTIVE The payment source is active and able to make transfers.


AWAITING_BENEFICIARY_COOL_OFF The payment source is in a cooling-off period mandated by the bank. It can take up to 24 hours.


INACTIVE The payment source is no longer active. This could be because your customer removed you as a beneficiary from their account or Lean has lost access to the account.

Was this section helpful? 

Endpoint

api.leantech.me/customers/v1/{customer_id}/payment-sources/{payment_source_id}

json

{
"id": "838af9d4-d77d-4a1e-bc9d-e4f6067ec9a3",
"customer_id": :"6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"bank": "HSBC",
"status" : "AWAITING_BENEFICIARY_COOL_OFF"
}

Initiate a Payment

Once you have a payment intent you can now initiate the Link SDK to complete the payment.

To use the Link SDK, it must be available in your application: How to install the Link SDK in your application.

To initiate a payment, call the .pay() method in the LinkSDK from your frontend. This will guide your user through the final steps to complete the payment.

Request

payment_intent String

The payment intent created by your backend.


Response

status String

The status of the payment once the LinkSDK has completed.

View statuses

success

Payment was successful.


insufficient_funds

Payment failed due to insufficient funds.


user_unconfirmed

User did not confirm the payment details.


payment_unauthorized

User did not enter correct authorization details.


payment_intent_id String

The payment intent for the requested payment.


payment Object

The payment attempt created by the LinkSDK flow.

View Object Attributes

id String

The ID of the payment.


status Enum

View statuses

ACCEPTED_BY_BANK

Payment has been made successfully and funds have been transferred from the bank.


REJECTED_BY_BANK

Payment was rejected by the bank.


FAILED

Payment failed.


amount Int

The amount transferred from the customer’s payment source.


currency String

The currency the transfer was made in.

Was this section helpful? 

javascript

Lean.pay({
app_token: "40289089716ab818017178bc1cff0005",
payment_intent_id: "452bcde4-5e48-44bb-8f6d-40c5c286466b"
})

json

// Webhook response
{
"type": "payment.created",
"payload" : {
"id": "452bcde4-5e48-44bb-8f6d-40c5c286466b"
"customer_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"intent_id": "8c339261-a62f-4251-bb58-f005bd0c6cd2",
"status": "ACCEPTED_BY_BANK",
"amount": 123.45,
"currency": "AED"
},
"message": "A payment object has been created.",
"timestamp": "2020-07-31T07:11:39.862804Z"
}