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.

Please note, this value has a unique constraint, no two Customers can share the same app_user_id

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.


Full Customer API Reference

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.


bank_identifier String (optional)

The bank identifier you want your customer to add a payment source for - you can read more about skipping bank selection here.


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",
bank_identifier: "HSBC_UAE"
})

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

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.


account_id String (optional)

The account id to initiate the payment from - you can read more about skipping account selection here.


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.

Webhook Structure

type String

The type of the webhook, this will be payment.created.

payload Payment Object

The payment attempt created by the LinkSDK flow.

View Object Attributes

id String

The ID of the payment.


customer_id String

The id of the customer who has initiated this payment


intent_id String

The payment intent id that initiated this payment


status Enum

View statuses

ACCEPTED_BY_BANK

The payment request has been accepted by the bank.


FAILED

The payment request was rejected by the bank.


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",
account_id: "53bf3538-d5fa-4230-9a36-8622da90de99"
})

json

// Webhook response - Payment accepted by bank
{
"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"
}
// Webhook response - Payment rejected by bank
{
"type": "payment.created",
"payload": {
"id": "99829d37-47f7-4cda-b2d7-ece1aa90860b",
"customer_id": "6dd9c7d2-1c8c-4862-bb1f-fcf52f5033d4",
"intent_id": "7cfd19ae-dd0a-4c60-9389-9121097c784d",
"status": "FAILED",
"amount": 1234.56,
"currency": "AED"
},
"message": "A payment object has been created.",
"timestamp": "2020-07-31T07:11:39.779636Z"
}

Delete a Payment Source

You can delete a payment source via the API with a simple DELETE request. This will remove the user's login information and the payment source from Lean systems, please note: this will not remove your accounts as a beneficiary of the users account.

Request

Reason enum

Please always pass in the value USER_REQUESTED.

Response

A 200 OK response will be sent back.

bash

curl -X DELETE 'sandbox.leantech.me/customers/v1/{customer_id}/payment-sources/{payment_source_id}' \
--header 'Content-Type: application/json' \
--header 'lean-app-token: 40289089716ab818017178bc1cff0005' \
--data-raw '{
"reason": "USER_REQUESTED"
}'