Payment Intents

A Payment Intent object is a contract between your backend and Lean for an amount that you want to charge a Customer. Payment Intents also store any Payment made against the Intent. Allowing you to see the details of the executed payment. The Payment Intent API allows you to create and retrieve payment intents.

The Payment Intent object id must be passed into the LinkSDK's .pay() method to initiate the transaction.

ENDPOINTS

POST /payments/v1/intents
GET /payments/v1/intents/:id

The Payment Intent Object

Attributes

payment_intent_id string

The unique identifier for the Payment Intent.


customer_id string

The Customer object associated with the Payment Intent.


amount float

The amount that should be charged to the customer.


currency string

The currency that the customer will make the payment in.


payments array

An array of Payment Initiation(s) - currently there will only ever be one Payment object within the array once a user has started to complete a payment.

View Payment Attributes

id string

The unique identifier for this payment.


payment_intent_id string

The Payment Intent identifier responsible for generating the Payment.


payment_source_id string

The identifier for the payment source object from which the payment was initiatied.


sender_details object

The account details for the customer sending the payment. Includes account number, name of the account holder and IBAN.


recipient_details object

Details for the recipient of the Payment, generated from the details available in the payment_destination.


amount float

The amount the charge was initiated for.


currency string

The currency the payment was initiated with.


description string

The description submitted to the bank as a reference when initiating a payment. Can be used for reconciliation. By default this value is a the Payment Intent UUID without hyphens but you can also specify the description upon creation of a payment intent.


submission_timestamp string

The time the Payment Initiation was submitted.


initiation_timestamp string

The time the Payment Initiation was started.


status enum

The current status of the payment

View Statuses

AWAITING_LOGIN_MFA - user is currently logging in to the bank and an OTP is required / user dropped out at the login OTP stage.


AWAITING_PAYMENT_MFA - user needs to approve the transaction with the bank and an OTP is required / user dropped out at the payment OTP stage.


AWAITING_APP_AUTH - user needs to approve the transaction in their banking application or over the phone / user dropped out at the transaction approval stage.


FAILED - The bank rejected, or could not process, the transaction.


PENDING_WITH_BANK - The payment request has been marked as pending by the bank and the money may not have been transferred immediately. Requires manual reconcilliation.


ACCEPTED_BY_BANK - The bank has accepted the transaction and is now processing the transaction. Transactions with an ACCEPTED_BY_BANK status should be reconciled before making the funds available to the customer as the bank may, in some circumstances, not complete the transaction.


bank_transaction_reference string

The transaction reference number supplied by the initiating bank on successful initiation of a transfer. Can be used for reconciliation.


payment_destination object

The Payment Destination object, detailing where the payment was sent. For further reading on Payment Destinations see the relevant section of this guide.


json

{
"payment_intent_id": "77f0c07e-7b7b-4677-bb05-6261f9eead0c",
"customer_id": "34c11087-b6bc-429b-9a91-725941b1a547",
"amount": 1000.00,
"currency": "AED",
"description": "77f0c07e7b7b4677bb056261f9eead0c",
"payments": [
{
"id": "25c90cc6-67dc-4193-a6e9-a7c875fcc0af",
"payment_intent_id": "77f0c07e-7b7b-4677-bb05-6261f9eead0c",
"payment_source_id": "b6fba7da-1054-5e82-8a9a-afd3ab4d1710",
"sender_details": {
"account_number": "XXXXXXXXXXXX",
"iban": "AE940030011XXXXXXXXXXXX",
"name": "John Doe"
},
"recipient_details": {
"account_number": "XXXXXXXXXXXX",
"iban": "AE870200000XXXXXXXXXXXX",
"name": "Al Fulani"
},
"amount": 1000.00,
"currency": "AED",
"description": "77f0c07e7b7b4677bb056261f9eead0c",
"submission_timestamp": "2021-05-18T13:58:03.427045Z",
"initiation_timestamp": "2021-05-18T13:58:42.445103Z",
"status": "ACCEPTED_BY_BANK",
"bank_transaction_reference": "0492981211381081"
}
],
"payment_destination": {
"id": "95c29647-c568-40d7-8710-3e330de1b5f2",
"bank_identifier": "HSBC_UAE",
"name": "Acme Corp.",
"iban": "AE870200000XXXXXXXXXXXX",
"display_name": "Acme Corp.",
"account_number": "XXXXXXXXXXXX",
"swift_code": "BBMEAEAD",
"status": "CONFIRMED",
"address": "Acme Towers, 51st Floor",
"country": "ARE",
"city": "Dubai",
"default": true,
"customer_id": null,
"owner_type": "APPLICATION"
}
}

Create a Payment Intent

Parameters

customer_id string

The unique identifier for the Customer you are charging.


amount float

The amount you want to charge.

View minimum and maximum amounts
CurrencyMinimumMaximum
AED10100,000
USD5027,000
BHD1810,000

currency string

The currency that the charge will be performed in.

View supported currencies
USD, AED

payment_destination_id string

The unique identifier for the Payment Destination the charge should be sent to.


description string (optional)

The description for the transaction. This will be used in the reference field when we submit the payment to the bank, and subsequently be displayed in both yours and your customer's bank statement. The description should be a maximum of 32 characters. It is highly recommended that you use the unique identifier which references this payment in your internal system as the description. This will help you reconcile the payments in your bank statement with payments made through Lean's service. By default this value is the Payment Intent UUID without hyphens.


Response

Returns a newly created Payment Intent object. The payment_intent_id must be passed in to the .pay() method of the LinkSDK to initiate the transaction.

bash

curl -X POST 'https://sandbox.leantech.me/payments/v1/intents' \
--header 'lean-app-token: YOUR_APP_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"customer_id": "34c11087-b6bc-429b-9a91-725941b1a547",
"amount": 1000.00,
"description": "ACME TXN001",
"currency": "AED",
"payment_destination_id": "517f416f-6632-407f-9110-18e11a4fd4d2"
}'

json

{
"payment_intent_id": "d964ed9b-e6c1-4bd9-bf8f-4a1028fa8b1f",
"customer_id": "6dc68854-e3fc-46e2-880a-9e3afbf50e5e",
"amount": 1000.00,
"currency": "AED",
"payments": [],
"description": "ACME TXN001"
"payment_destination": {
"id": "95c29647-c568-40d7-8710-3e330de1b5f2",
"bank_identifier": "HSBC_UAE",
"name": "Acme Corp.",
"iban": "AE870200000XXXXXXXXXXXX",
"display_name": "Acme Corp.",
"account_number": "XXXXXXXXXXXX",
"swift_code": "BBMEAEAD",
"status": "CONFIRMED",
"address": "Acme Towers, 51st Floor",
"country": "ARE",
"city": "Dubai",
"default": true,
"customer_id": null,
"owner_type": "APPLICATION"
}
}

Retrieve a payment intent

A Payment Intent can be retrieved from Lean to check the state and further details of payments made at any point.

Parameters

app_token string

Your application identifier


id string

The payment_intent_id you want to retrieve

Response

Returns the Payment Intent object requested. Will return an error if the requested Payment Intent does not exist.

bash

curl -X GET 'https://sandbox.leantech.me/payments/v1/intents/:id' \
--header 'lean-app-token: YOUR_APP_TOKEN' \
--header 'Content-Type: application/json' \

json

{
"payment_intent_id": "77f0c07e-7b7b-4677-bb05-6261f9eead0c",
"customer_id": "34c11087-b6bc-429b-9a91-725941b1a547",
"amount": 1000.00,
"currency": "AED",
"description": "77f0c07e7b7b4677bb056261f9eead0c",
"payments": [
{
"id": "25c90cc6-67dc-4193-a6e9-a7c875fcc0af",
"payment_intent_id": "77f0c07e-7b7b-4677-bb05-6261f9eead0c",
"payment_source_id": "b6fba7da-1054-5e82-8a9a-afd3ab4d1710",
"sender_details": {
"account_number": "XXXXXXXXXXXX",
"iban": "AE940030011XXXXXXXXXXXX"
},
"recipient_details": {
"account_number": "XXXXXXXXXXXX",
"iban": "AE870200000XXXXXXXXXXXX",
"name": "Al Fulani"
},
"amount": 1000.00,
"currency": "AED",
"description": "77f0c07e7b7b4677bb056261f9eead0c",
"submission_timestamp": "2021-05-18T13:58:03.427045Z",
"initiation_timestamp": "2021-05-18T13:58:42.445103Z",
"status": "ACCEPTED_BY_BANK",
"bank_transaction_reference": "0492981211381081"
}
],
"payment_destination": {
"id": "95c29647-c568-40d7-8710-3e330de1b5f2",
"bank_identifier": "HSBC_UAE",
"name": "Acme Corp.",
"iban": "AE870200000XXXXXXXXXXXX",
"display_name": "Acme Corp.",
"account_number": "XXXXXXXXXXXX",
"swift_code": "BBMEAEAD",
"status": "CONFIRMED",
"address": "Acme Towers, 51st Floor",
"country": "ARE",
"city": "Dubai",
"default": true,
"customer_id": null,
"owner_type": "APPLICATION"
}
}