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:
- Set up your payment details.
- Enable customer payments from a nominated account.
- 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"}