{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-openapi.json","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"openapi.json","dynamicMarkdocComponents":[],"baseSlug":"/openapi","seo":{"title":"LeanX payment API","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"LeanX payment API","description":"\n### Changelog\n\n#### 2.5.1 Amount _required_ for quote\n\n- Since quotes are not reusable since v2.5.0, we could now add requirement that quote also contains rate:\n  Quote amount is in base currency (e.g. AED/BHD) and payment amount is in destination currency (e.g. INR)\n  We now check that `payment_amount = quote_amount * quote_rate`\n\n#### 2.5.0 Extended sender details _required_ for payments\n\n- `/v2/payment_ext` endpoint is now merged with `/v2/payment` endpoint;\n   You must supply details, like sender name, dob, some document id etc\n\n- Quotes are now per single payment (i.e. no quote reuse, which was possible by accident)\n\n- For more efficient routing you can now add amount, bank and bank account details to the quote\n  which allows for more efficient routing of payments.\n\n\n#### 2.1.1 External ID for payments\n\n- You can now supply `external_id` for the payment order and fetch the payment status using that id.\n\n    `POST /v2/payment` (`external_id` body parameter)\n\n    `GET /v2/payments/{id}?external=true` (`external_id` body parameter)\n\n\n#### 2.1.0 Extended quote and payment API\n\n- You can now supply additional parameters to quote request (`amount`, `acc` and `bank` ID).\n  These allows us to return best possible quote and increase payment success rate.\n\n- There is a new `/v2/payment_ext` endpoint which allows adding sender info.\n  This allows payments for more countries.\n\n\n#### 2.0.0 Initial release of the v2 API\n\n\n### Credentials\n\nBefore using this API you need to obtain valid credentials:\n- ACCESS KEY: Random base64 encoded string with custom prefix\n- SECRET KEY: Random base64 encoded string\n\nIf possible, you need to keep `ACCESS_KEY` private and under no circumstances\nyou should share your `SECRET KEY`. For user convenience, ACCESS KEY includes custom prefix in the value, e.g.\n\n```\n    company-test-sIEUpUP7b41n51WY\n```\n\nwhere the first part is your company tag, followed by key usage hint and\nlast part is a random value.\n\n\n### Authentication\n\nFor API authentication we use JWT/Bearer tokens, passed on the\n`Authorization: Bearer <token>` header.\n\nCurrently supported JWT algorithms are:\n- `HS256` — symmetric: the token is signed with your `SECRET KEY`.\n- `RS256` — asymmetric: LeanX issues you a private/public key pair. You sign\n  the token with the private key, and LeanX verifies it with the matching\n  public key. Use this when you prefer not to sign with a shared secret.\n\nThe LeanX team will select and deliver the authentication method to be used\nfor your integration. The algorithm is selected from the token's `alg` header,\nso the same endpoint accepts either. The required claims are identical for\nboth; only the header and signing method differ.\n\nJWT token header MUST include `kid`:\n\n```json\n{\n  \"alg\": \"HS256\",  /* or \"RS256\" */\n  \"typ\": \"JWT\",\n  \"kid\": \"someuser-demo-1234567890ABCDEF\"\n}\n```\n\nFor `HS256` the `kid` is your `ACCESS KEY`. For `RS256` the `kid` identifies\nwhich of the public keys issued to you by LeanX should be used to verify the\nsignature.\n\nJWT token body MUST include the following claims:\n\n```json\n{\n    \"sub\": \"someuser-demo-1234567890ABCD\", /* (your `ACCESS KEY`), the same as `kid` */\n    \"exp\": 1234,  /* (expiration time, UNIX timestamp, UTC) */\n    \"iat\": 1234,  /* (issued at time, UNIX timestamp, UTC) */\n    \"aud\": \"https://api.example.net\",  /* (API URL, e.g. \"https://api.leanxdev.me\") */\n    \"iss\": \"https://api.example.com\"   /* (API URL, e.g. \"https://api.leanxdev.me\") */\n}\n```\n\nIn addition to the above, you can add `hmac` claim for POST requests:\n\n```json\n{\n    \"hmac\": \"str (SHA256 HMAC of the raw POST body)\"\n}\n```\n\nThis allows attesting that POST payloads are not modified in transit.\n\nUsing fast expiring tokens with HMAC adds additional guards so your requests\ncan't be intercepted/forged, nor replayed.\n\nLeanx doesn't provide JWT editor for the time being, you can use the excellent [jwt.io](https://jwt.io/beta) (password is 'jwtv2')\n\n### Transaction states\n\n\nTransactions accepted by the API can be in one of the following states.\nAs soon as the order is accepted, you will get unique id in the response, which can base\nused to track the transaction.\n\nPlease note that orders rejected up-front by the API with 4xx (authentication or\nvalidation errors) are not represented in the state table, since they've never been accepted\nfor processing.\n\n\n| Status Category  | Status       | Description                   | Notes                                                                               |\n|------------------|--------------|-------------------------------|-------------------------------------------------------------------------------------|\n| **In Progress**  | `queued`     | Payment order accepted        | Order is accepted and waiting to be submitted for processing                        |\n| **In Progress**  | `pending`    | Payment order pending         | DEPRECATED (see `processing`)                                                       |\n| **In Progress**  | `processing` | Payment order is processing   | Payment submitted and accepted by processor                                         |\n| **Success**      | `succeeded`  | Payment executed successfully |                                                                                     |\n| **Failed**       | `failed`     | Payment failed                | Payment failed by the processor                                                     |\n| **Failed**       | `rejected`   | Payment rejected              | Payment rejected by processor or by API during processing (e.g API could not route) |\n| **Failed**       | `canceled`   | Payment is canceled           | DEPRECATED (see `reversed`)                                                         |\n| **Failed**       | `reversed`   | Payment is reversed           | Payment reversed (and refunded) on the processor side                               |\n| **Call Support** | `unknown`    | Payment state is unknown      | Payment has encountered uknown status by the processor, needs manual intervantion   |                                                           |\n\n### Settlement currencies\n\n\nThis API enables processing and settlement of transactions in fiat currency USD, and stable coins: USDT and USDC. \nIt supports seamless currency conversion, validation, and settlement routing between traditional and digital assets.\n\n    ","summary":"\n### Intro\n\nLeanx API facilitate fast payments via bank tranfers to specified beneficiaries.\n    "},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.leanx.me","port":4000,"ipAddress":"216.73.216.237"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/openapi","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}