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? 

Payment Flow Overview

Lean's Payment API is split into two parts. Creating a payment source and making a payment. You can see an overview of the flow you will be implementing below:

Was this section helpful? 

Errors

Lean uses conventional HTTP response codes with requests to help you identify errors and how to rectify them. We also provide a status and message within the body of an error response to indicate how to resolve the error that has occurred.

In general: codes in the 2XX range indicate success, codes in the 4XX range indicate a bad request and codes in the 5XX range indicate something went wrong on our end.

View List of Error Statuses

MISSING_PARAMETERS 400

The request does not have all the required parameters to complete the call.


INVALID_PARAMETERS 400

The request provided invalid parameters.


AMOUNT_OVER_MAX_VALUE 400

The amount specified in a payment_intent request is over the maximum allowed value for a single transfer.

Maximum transfer amounts
CurrencyAmount
AED40,000.00

AMOUNT_UNDER_MIN_VALUE 400

The amount specified in a payment_intent request is under the minimum allowed value for a single transfer (AED 10).

Minimum transfer amounts
CurrencyAmount
AED10.00

INVALID_CERTIFICATE 403

The certificate on your server has not been recognized.


UNKNOWN_ENTITY 404

The entity_id provided did not match an account in our records.


UNKNOWN_APP_ID 404

The app_id provided has not been recognized by Lean.


UNKNOWN_RESULTS_ID 404

The results_id provided has not been recognized by Lean


RATE_LIMIT_EXCEEDED 429

Rate limit exceeded. Please try again later.


INTERNAL_SERVER_ERROR 500

Something has gone wrong. If you continue to see this error, please get in touch with Lean.

Was this section helpful? 

javascript

HTTP CODE: 400
{
results_id: "139820938109823",
status: "MISSING_PARAMETERS",
message: "The request does not have all the required parameters to complete the call.",
payload: null
meta: {
...meta_data
}
timestamp: "2020-08-08T00:00:00Z"
}

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.

Test Users & OTPs

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.

Test Users & OTPs

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"
}