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.


sender_details object

The account details for the customer sending the payment. Includes account number 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 entered into the bank when initiating the payment. Can be used for reconciliation. This value is a bank safe string representative of the Payment Intent UUID.


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 accepted and is processing the payment (A webhook is sent to notify your backend when a Payment's status changes to ACCEPTED_BY_BANK).


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

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
AED1040,000
USD1010,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 for the transaction, and be displayed in both yours and your customer's bank statement.


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