Concepts

Every resource on the API belongs to a small hierarchy. Learn it once and the reference reads as one system.

Cowdi (the root organization)
└── Organization            a partner, such as a lender or a buyer
    ├── Members             people who work for the organization, with roles
    ├── OAuth clients       credentials the organization's software calls the API with
    ├── Webhooks            where the platform sends the organization's events
    ├── Lending products    the loan terms the organization offers
    ├── Agents              field staff who look after customers
    ├── Merchants           businesses the organization serves
    │   └── Merchant members   people who act for the merchant
    └── Users               the customers
        ├── KYC application    identity verification
        ├── Profile and contact details
        └── Accounts           loan, credit, Flex Credit, or current account
            ├── Transactions
            ├── Installments
            └── Statements

Organization

An organization is a partner of Cowdi: a lender, an employer, or a buyer that finances its suppliers. Cowdi itself is the root organization; every partner is a child of it. Your access token names one organization, and everything you create belongs to it. The organization's own settings live under /v1/organizations/{organizationId}: its members, its merchants, and the API version it is pinned to.

Members

A member is a person who works for the organization and signs in to Cowdi Connect or calls the API with a user token. A member holds roles, and a role holds permissions such as org:connect:write. Members join through invitations: the organization creates one with one or more roles, and the person accepts it from their own account. An inviter can only grant roles whose permissions they hold.

Users

A user is a customer: a person who borrows, pays, or holds an account. A user is one record across the whole platform, unique by phone number and email, and can be a customer of several organizations at once. Each organization keeps its own reference for the user in organization_user_id. A partner's software acts on a customer's behalf by naming user_id; the customer's own app acts as the signed-in user, whose resources live under /v1/user/....

Before a customer can transact, a KYC application verifies their identity, as Identity verification explains. Their profile holds their name and settings, and their contact details hold verified phone numbers and email addresses.

Merchants

A merchant is a business the organization serves, such as a supplier that a buyer pays through invoice financing. The organization onboards the merchant, and the merchant's own people become merchant members through invitations. Merchant-level resources, such as invoice financing applications, live under /v1/merchants/{merchantId}.

Agents

An agent is a member of the organization who looks after a set of customers in the field. Customers are assigned to agents, agents earn commissions on their customers' activity, and the agent's dashboard and insights summarize that book.

Accounts

An account belongs to one user within one organization. There are four kinds:

A loan account holds one term loan, created from a loan application.
A credit account is a revolving line the customer draws on and repays each billing cycle.
A Flex Credit account finances purchases, each with its own installment plan. A credit line product, such as iPOS credit, opens one Flex Credit account at the first loan application. Each approved application is a draw on it.
A current account holds money the customer can spend and receive.

Every account has transactions, the money movements posted to it. A loan, credit, or Flex Credit account also has installments, the scheduled repayments, and each installment records the repayment transactions allocated to it. Any account can produce a statement.

Transaction failures

When a transaction's status is FAILED, failure_reason names why. It is null for every other status. Branch on the reason; treat a value you do not know as unknown and do not fail the whole response.

Know these reasons apart:

`failure_reason`	Meaning
`INSUFFICIENT_FUNDS`	The customer's account does not have enough balance.
`ACCOUNT_CANNOT_TRANSACT`	A block or restriction on the account stops it from sending or receiving right now.
`INTERNAL_ERROR`	No more specific reason applies. Most often the transaction failed on Cowdi's side or the payment provider's side. Do not tell the customer they are out of funds. Retry later, and contact Cowdi support if the failure repeats.

The API does not return PROVIDER_INSUFFICIENT_FUNDS or INITIATOR_CONFIGURATION_ERROR. A failure on the provider's side shows INTERNAL_ERROR. If your mapping table lists either value, map those cases to INTERNAL_ERROR.

One-time codes

Some actions ask the customer for a one-time code (OTP) before they take effect: changing or verifying a contact, confirming a transaction, and activating, verifying or closing a current account. Send the code in otp_code.

Codes do not all have the same length. Cowdi sends 6-digit codes, and the custodian bank sends 4-digit codes. Size your code field from the code you are waiting for, not from a fixed length:

On contact details, the otp object gives the length in digits, 4 or 6.
Codes for transactions and current account activation, email verification and closure come from the bank, so they have 4 digits.

A code of any other length is refused with 400 and the code OTP_INVALID, like a wrong code.

Lending products

A lending product is a set of loan terms an organization offers: the amount range, the tenure, the interest rate, and the penalty terms. A customer receives a quote as a loan application, and applying for it disburses the loan into a new loan account.

Read the products your organization offers, and the published version of each, with List products. Get a product reads one. List product versions lists that product's versions, newest first. A version is DRAFT, PUBLISHED, or SUPERSEDED. Its terms have one of three shapes, and product selects the shape. TERM_LOAN and REVOLVING_CREDIT share one shape. FLEX_CREDIT and INVOICE_FINANCING each have their own. The role needs org:products:read. The organization comes from the token. A product the caller does not offer is a 404.

The products you can quote for a customer are a separate list. See List the organization's loan products.

Access

Software calls the API with an OAuth client the organization creates in Cowdi Connect. A client-credentials client acts as the organization; an authorization-code client acts as the signed-in member or customer. Webhooks deliver the organization's events, such as a completed disbursement, to endpoints it registers. See Authentication and Webhooks.

On this page