Lean Docs

Payment Sources

A Payment Source is a representation of a Payment Method for a customer. To generate a Payment Source use the .createPaymentSource() method with the LinkSDK in your frontend.

ENDPOINTS

   GET /customers/v1/:customer-id/payment-sources
   GET /customers/v1/:customer-id/payment-sources/:payment_source_id
DELETE /customers/v1/:customer-id/payment-sources/:payment_source_id

The Payment Source Object

Attributes

id String

The unique identifier for the Payment Source

customer_id String

The unique identifier for the customer that owns the Payment Source

app_id String

The application associated with the Payment Source

status String deprecated

The current status of the first beneficiary added to the Payment Source.

Note: status is depreciated and will be removed in future iterations of the Lean API. You should instead watch the status of individual beneficiaries within the Payment Source object.

View Statuses

AWAITING_BENEFICIARY_COOL_OFF - Lean has added the beneficiary, but it is not yet chargeable due to bank cool off period(s)

ACTIVE - Payment source is chargeable.

beneficiaries array

An array of Destinations that have been added to the Payment Source.

View beneficiary attributes

id string

The unique identifier for the beneficiary

payment_destination_id string

The unique identifier for the Destination that has been added to the Payment Source.

status string

The current status of the beneficiary. Indicates whether the Payment Destination and Payment Source channel is chargeable.

View Statuses

AWAITING_BENEFICIARY_COOL_OFF - Lean has added the beneficiary, but it is not yet chargeable due to bank cool off period(s)

ACTIVE - Payment source is chargeable.

beneficiary_cool_off_expiry datetime

The time that the beneficiary cool down period will, or did, expire. After this time the beneficiary will be chargeable.

accounts array

A list of chargeable accounts within the Payment Source.

View account attributes

id string

The unique identifier for the account.

account_id string deprecated

A secondary identifier for the account.

The account_id parameter has been deprecated and will be removed in future versions of the API

account_name string

The friendly name for the account - for example "Gold Savings Account".

account_number string

The bank account number for the account.

iban string

The IBAN number for the account.

balance float deprecated

The balance available on the account at the last payment.

The balance_available has been deprecated and will be removed in future versions of the API.

currency string

The currency that the account supports.

balance_last_updated datetime deprecated

The last date the balance was refreshed.

The balance_last_updated has been deprecated and will be removed in future versions of the API.

jsx

{
  "id": "d8d7a9b3-c401-49f6-81a4-386d8398aa2c",
  "customer_id": "6db94cb7-3a02-4a57-a03a-e2a92ce86406",
  "app_id": "YOUR_APP_ID",
    "status": "AWAITING_BENEFICIARY_COOL_OFF",
    "beneficiary_cool_off_expiry": "2021-02-13T13:20:57.674299Z",
  "bank_identifier": "ENBD_UAE",
  "beneficiaries": [
    {
      "id": "26891A75-9406-4E06-97BA-F4D6DA664F3C",
      "payment_destination_id": "f044c18b-3a51-49a2-bd3f-a585679d8885"
      "status": "AWAITING_BENEFICIARY_COOL_OFF",
      "beneficiary_cool_off_expiry": "2021-02-13T13:20:57.674299Z"
    }
  ]
  "accounts": [
    {
      "id": "9acde98e-9d19-495d-934c-b2ff966262c8",
      "account_id": "aaadbc4e-96a4-420f-ba01-597fa63502ee",
      "account_name": "CURRENT ACCOUNT",
      "account_number": "1015528734001",
      "iban": "AE340260001015528734001",
      "balance": 35681.15,
      "currency": "AED",
      "balance_last_updated": "2021-02-12T13:20:23.83922Z"
    }, {
      "id": "1457d23a-c1f8-4aee-bc6f-2a253b2e617f",
      "account_id": "69f22112-e95d-427e-8bd1-eb58b4db60ba",
      "account_name": "CURRENCY PASSPORT SAVINGS AC",
      "account_number": "0315528734002",
      "iban": "AE790260000315528734002",
      "balance": 80871.00,
      "currency": "USD",
      "balance_last_updated": "2021-02-12T13:20:57.370659Z"
    }
  ]
}

Create a Payment Source

Payment Sources are created with the LinkSDK on your frontend.

Parameters

app_token String

The app token for the application making the call.

customer_id String

The Customer you want to create a Payment Source for.

bank_identifier String

Optional: The Lean identifier for the Bank you want to connect, a list of Banks supported by Lean can be retrieved from the Banks endpoint. If the bank_identifier is not present, the LinkSDK will allow users to choose which bank they connect.

sandbox bool

Whether the payment source should be created in Sandbox or not.

payment_destination_id string

Optional: The Payment Destination you want to add as the beneficiary to the payment source. This will be your default Payment Destination if not supplied.

Response

The .createPaymentSource() method will return your created Payment Source via a payment_source.created webhook.

javascript

Lean.createPaymentSource({
    app_token: "YOUR_APP_TOKEN",
    customer_id: "6db94cb7-3a02-4a57-a03a-e2a92ce86406",
    bank_identifier: "ENBD_UAE",
    sandbox: true
})

Retrieve a list of Payment Sources for a customer

Parameters

customer_id string

The Customer object you want to retrieve a list of Payment Sources for.

Response

Returns an array of Payment Source objects.

bash

curl -X GET 'https://sandbox.leantech.me/customers/v1/:customer_id/payment-sources' \
    --header 'lean-app-token: YOUR_APP_TOKEN', \
    --header 'Content-Type: application/json' \

json

[
    {
      "id": "d8d7a9b3-c401-49f6-81a4-386d8398aa2c",
      "customer_id": "6db94cb7-3a02-4a57-a03a-e2a92ce86406",
      "app_id": "YOUR_APP_ID",
        "status": "AWAITING_BENEFICIARY_COOL_OFF",
        "beneficiary_cool_off_expiry": "2021-02-13T13:20:57.674299Z",
      "bank_identifier": "ENBD_UAE",
      "beneficiaries": [
        {
          "id": "26891A75-9406-4E06-97BA-F4D6DA664F3C",
          "payment_destination_id": "f044c18b-3a51-49a2-bd3f-a585679d8885"
          "status": "AWAITING_BENEFICIARY_COOL_OFF",
          "beneficiary_cool_off_expiry": "2021-02-13T13:20:57.674299Z"
        }
      ]
      "accounts": [
        {
          "id": "9acde98e-9d19-495d-934c-b2ff966262c8",
          "account_id": "aaadbc4e-96a4-420f-ba01-597fa63502ee",
          "account_name": "CURRENT ACCOUNT",
          "account_number": "1015528734001",
          "iban": "AE340260001015528734001",
          "balance": 35681.15,
          "currency": "AED",
          "balance_last_updated": "2021-02-12T13:20:23.83922Z"
        }, {
          "id": "1457d23a-c1f8-4aee-bc6f-2a253b2e617f",
          "account_id": "69f22112-e95d-427e-8bd1-eb58b4db60ba",
          "account_name": "CURRENCY PASSPORT SAVINGS AC",
          "account_number": "0315528734002",
          "iban": "AE790260000315528734002",
          "balance": 80871.00,
          "currency": "USD",
          "balance_last_updated": "2021-02-12T13:20:57.370659Z"
        }
      ]
    }
]

Retrieve a single Payment Source

Parameters

customer_id string

The Customer who owns the Payment Source.

payment_source_id string

The Payment Source you want to retrieve.

Response

Returns the requested Payment Source object.

bash

curl -X GET 'https://sandbox.leantech.me/customers/v1/:customer_id/payment-sources/:payment_source_id' \
    --header 'lean-app-token: YOUR_APP_TOKEN', \
    --header 'Content-Type: application/json' \

json

{
  "id": "d8d7a9b3-c401-49f6-81a4-386d8398aa2c",
  "customer_id": "6db94cb7-3a02-4a57-a03a-e2a92ce86406",
  "app_id": "YOUR_APP_ID",
    "status": "AWAITING_BENEFICIARY_COOL_OFF",
    "beneficiary_cool_off_expiry": "2021-02-13T13:20:57.674299Z",
  "bank_identifier": "ENBD_UAE",
  "beneficiaries": [
    {
      "id": "26891A75-9406-4E06-97BA-F4D6DA664F3C",
      "payment_destination_id": "f044c18b-3a51-49a2-bd3f-a585679d8885"
      "status": "AWAITING_BENEFICIARY_COOL_OFF",
      "beneficiary_cool_off_expiry": "2021-02-13T13:20:57.674299Z"
    }
  ]
  "accounts": [
    {
      "id": "9acde98e-9d19-495d-934c-b2ff966262c8",
      "account_id": "aaadbc4e-96a4-420f-ba01-597fa63502ee",
      "account_name": "CURRENT ACCOUNT",
      "account_number": "1015528734001",
      "iban": "AE340260001015528734001",
      "balance": 35681.15,
      "currency": "AED",
      "balance_last_updated": "2021-02-12T13:20:23.83922Z"
    }, {
      "id": "1457d23a-c1f8-4aee-bc6f-2a253b2e617f",
      "account_id": "69f22112-e95d-427e-8bd1-eb58b4db60ba",
      "account_name": "CURRENCY PASSPORT SAVINGS AC",
      "account_number": "0315528734002",
      "iban": "AE790260000315528734002",
      "balance": 80871.00,
      "currency": "USD",
      "balance_last_updated": "2021-02-12T13:20:57.370659Z"
    }
  ]
}

Update a Payment Source

Payment Sources can be updated with additional beneficiaries to enable payment routing between different accounts such as Peer-to-peer payments and alternative business accounts.

Parameters

app_token String

The app token for the application making the call.

customer_id String

The Customer you want to create a Payment Source for.

payment_source_id String

The identifier for the Payment Source you want to update.

payment_destination_id string

The Payment Destination you want to add as an additional beneficiary to the payment source.

sandbox bool

Whether the payment source should be created in Sandbox or not.

Response

The updatePaymentSource() method will generate webhook with a type of payment_source.updated when completed successfully.

javascript

Lean.updatePaymentSource({
    app_token: "YOUR_APP_TOKEN",
    customer_id: "6db94cb7-3a02-4a57-a03a-e2a92ce86406",
    payment_source_id: "d8d7a9b3-c401-49f6-81a4-386d8398aa2c",
    payment_destination_id: "74317929-f234-4abe-812b-30368ab2732a",
    sandbox: true
})

Delete a Payment Source

Parameters

reason enum

The reason that the Payment Source is being removed. This should always be USER_REQUESTED.

Response

Will return a simple 200 response. Will return an error if reason is not provided.

bash

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

© Lean Technologies Ltd. 2021