{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "API specification for Glomo", "termsOfService": "https://www.glomopay.com/legal#terms-and-conditions", "contact": { "name": "", "email": "developer@glomopay.com", "url": "" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "x-logo": { "url": "https://redocly.github.io/openapi-template/logo.png" }, "description": "The Glomo API follows REST architecture, utilizing resource-oriented URLs for clarity. It handles form-encoded request bodies, delivers responses in JSON format, and operates with standard HTTP methods, authentication, and response codes.\n\nYou can download the complete API collection by using the download options on the right.\n\nThe machine-readable description is also published at a stable URL, bundled into a single self-contained document with every `$ref` resolved:\n\n- [https://docs.glomo.one/openapi.yaml](https://docs.glomo.one/openapi.yaml)\n- [https://docs.glomo.one/openapi.json](https://docs.glomo.one/openapi.json)\n\nPoint an API client or an AI coding agent at either URL to generate calls directly from the contract.\n" }, "tags": [ { "name": "balance_conversions", "x-displayName": "Balance Conversions", "description": "Balance Conversion resource represents the details of the balance conversion. The balance conversion is the conversion of the balance from one supported currency to another supported currency.", "x-group": "Multi Currency Account" }, { "name": "fx_rate", "x-displayName": "FX", "description": "Returns the current mid-market exchange rate for a given currency pair. This is the base rate before any FX fees — FX fees will be charged on top of this rate.", "x-group": "Multi Currency Account" }, { "name": "payment_link", "x-displayName": "Payment Link", "description": "A payment link is a shareable URL that will take your customers to a Glomo-hosted payment page. The payment page can only be accessed by your customer after the completion of 1FA via their email.", "x-group": "Payin" }, { "name": "Customer", "description": "This resource represents a customer of your business. The customer can be an individual or a business from whom you will receive payments.", "x-group": "Payin" }, { "name": "Document", "description": "Document resource represents the documents details uploaded. This document is used in payin, payout, etc.", "x-group": "Document" }, { "name": "Payment", "description": "This resource represents a payment attempt made by your customer. The payment can either be successfully completed or failed, depending on various factors.", "x-group": "Payin" }, { "name": "Refund", "description": "This resource represents a refund transaction from your Glomo account to your customer. You can retrieve it to see the details of the refund transaction.", "x-group": "Payin" }, { "name": "Payout", "description": "This resource represents the disbursement transactions from your Glomo account to your beneficiaries.", "x-group": "Payout" }, { "name": "Quote", "description": "This resource represents a pricing quote for a payout or payin. A quote locks the FX rate and fee breakdown for a fixed period.", "x-group": "Quote" }, { "name": "Balance", "description": "This resource represents your Glomo balance. You can retrieve it to see the current balance on your Glomo account in all currencies enabled for your account.", "x-group": "Multi Currency Account" }, { "name": "bank_account_validation", "x-displayName": "Bank Account Validation", "description": "Bank Account Validation resource represents the validation details of a bank account.", "x-group": "Payout" }, { "name": "beneficiary_v2", "x-displayName": "Beneficiary V2", "description": "This resource represents a payee of a payout initiated by your business. Beneficiary V2 introduces a structured nested format for beneficiary, address, and bank account details, and supports both bank account and UPI payment methods.", "x-group": "Payout" }, { "name": "Price", "description": "This resource represents the details of the referral fees to be configured at the order or payment link level. Only platform businesses are allowed to create prices. The first Price created is set as default for a business.", "x-group": "Payin" }, { "name": "pricing_split", "x-displayName": "Dynamic Fee Split", "description": "You can configure a payin or subscription with your own pricing splits. The split declares merchant's share out of the total pricing rule and rest of it gets charged to the customer. The split needs to be explicitly passed in the API calls to be applied, otherwise system configured pricing rules apply. Use this resource to list the dynamic rules you may declare against, and to create and list your declarations. Pass the resulting split ids as `split_ids` on a payment link, an order, a payin quote, a subscription or an auto debit.", "x-group": "Payin" }, { "name": "Orders", "description": "This resource represents the order details. The order is the request to receive payment from your customer.", "x-group": "Payin" }, { "name": "Subscription", "description": "This resource represents a recurring billing agreement for a customer. Subscriptions allow businesses to automatically charge customers on a regular schedule according to a defined billing plan.", "x-group": "Subscription" }, { "name": "Webhook", "x-displayName": "Webhook", "description": "This resource represents the webhook details. The webhook is the endpoint where the webhook events will be sent.", "x-group": "Webhook" }, { "name": "Settlement", "description": "This resource represents the settlement details. The settlement is the process of transferring funds from your Glomo account to your bank account.", "x-group": "Settlement" }, { "name": "virtual_account", "x-displayName": "Virtual Account", "description": "This resource represents virtual account details. A virtual account is a unique account number provisioned for a customer, allowing payments to be received and transactions to be tracked against that customer.", "x-group": "Virtual Account" }, { "name": "platform", "x-displayName": "Platform", "description": "This resource provides platform functionality that enables platforms to onboard merchants onto Glomo, with each merchant having their own dedicated Virtual Accounts (VA).", "x-group": "Platform" }, { "name": "internal_transfer", "x-displayName": "Internal Transfer", "description": "This resource represents internal fund movements between merchant accounts within the platform–partner model. Internal transfers enable seamless fund movement between merchants who operate under the same platform account. Internal transfers are restricted to accounts linked under the same platform hierarchy. The following transfer directions are supported:\n| Transfer Type | Description |\n| ------------------------------ | ------------------------------------------------------------------------------ |\n| **P → C** | From a **Platform** (P) account to one of its **Child** (C) merchant accounts. |\n| **C → P** | From a **Child** (C) merchant account back to its **Platform** (P) account. |\n| **C → C (same P)** | Between **Child** (C) accounts under the same **Platform** (P). |", "x-group": "Internal Transfer" }, { "name": "KycLink", "x-displayName": "KYC Link", "description": "A KYC link is a shareable URL sent to a customer to complete identity verification. Use this resource to retrieve the KYC link details, including submission status and the documents captured during the verification process.", "x-group": "KYC" }, { "name": "payment_session", "x-displayName": "Payment Session", "description": "A Payment Session is a configurable workflow that wraps a payment journey with pre-steps and/or post-steps — such as identity verification, compliance checks, or data collection — before or after the core payment. The session type is configured per business and determines the exact step sequence. Creating a session returns a short-lived JWT token that is passed to the Glomo Web SDK to launch the guided UI.", "x-group": "Payin" }, { "name": "distributor_link", "x-displayName": "Distributor Link", "description": "A distributor link is one reusable URL for a fund's scheme. Each time an investor opens it, a new payment session starts for the scheme, credited to the distributor. See [One Click Distributor Link](/capital-markets/distributor/share-a-link) for the flow.", "x-group": "Payin" }, { "name": "lrs", "x-displayName": "LRS", "description": "Operations for remittances from customers resident in India under the Liberalised Remittance Scheme (LRS): the banks your customers can remit from, the customer's LRS bank account, and the LRS quote an LRS order is created from. See the [LRS guide](/payin/resident-india-remittance-under-lrs/set-up) for the end-to-end flow.", "x-group": "Payin" }, { "name": "api_key", "x-displayName": "API Key", "description": "Manage your Glomo API keys. Use this resource to rotate your secret key and maintain secure access to the API.", "x-group": "Authentication" }, { "name": "investor_journey", "x-displayName": "Investor Journey", "description": "Create investor journey. Platform merchant JWT required.", "x-group": "Investor Portal" }, { "name": "rfi", "x-displayName": "RFI", "description": "A Request for Information (RFI) is raised when Glomo's compliance checks need additional information — most commonly supporting documents such as a passport — before a transaction can be completed, for example when a payment is placed on a sanctions-screening hold. The RFI `id` is exposed on the underlying resource (for example, the `rfi` object on a Payment). Use this resource to submit the requested documents and resolve the RFI, including an RFI raised on a payout.", "x-group": "Request for Information" } ], "x-tagGroups": [ { "name": "Authentication", "tags": [ "api_key" ] }, { "name": "Multi Currency Account", "tags": [ "Balance", "balance_conversions", "fx_rate" ] }, { "name": "Payin", "tags": [ "payment_link", "Orders", "Customer", "Payment", "Refund", "Price", "pricing_split", "payment_session", "distributor_link", "lrs" ] }, { "name": "Subscription", "tags": [ "Subscription" ] }, { "name": "Quote", "tags": [ "Quote" ] }, { "name": "Payout", "tags": [ "Payout", "beneficiary_v2", "bank_account_validation" ] }, { "name": "Document", "tags": [ "Document" ] }, { "name": "Internal Transfer", "tags": [ "internal_transfer" ] }, { "name": "Settlement", "tags": [ "Settlement" ] }, { "name": "Virtual Account", "tags": [ "virtual_account" ] }, { "name": "Platform", "tags": [ "platform" ] }, { "name": "KYC", "tags": [ "KycLink" ] }, { "name": "Investor Portal", "tags": [ "investor_journey" ] }, { "name": "Request for Information", "tags": [ "rfi" ] } ], "servers": [ { "url": "https://api.glomopay.com/api/v1", "description": "Production server" } ], "paths": { "/balances": { "get": { "tags": [ "Balance" ], "summary": "Retrieve balances", "description": "Retrieves available balances for all currencies.\n", "operationId": "getBalance", "security": [ { "JWT": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllBalances" } } } }, "401": { "description": "Unauthorized" } } } }, "/balance_conversions": { "post": { "tags": [ "balance_conversions" ], "summary": "Convert balances", "description": "Converts balance from one currency to another. In the API you can either send `target_amount` or `source_amount` and the API will calculate the other amount for you.\n", "operationId": "createBalanceConversion", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "source_currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. `source_currency` and `target_currency` must differ, or the request returns `400`.\n", "example": "USD" }, "target_currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. `source_currency` and `target_currency` must differ, or the request returns `400`.\n", "example": "EUR" }, "source_amount": { "type": "number", "minimum": 1, "description": "The amount you want to convert. A positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295. ``` Only one of `source_amount` or `target_amount` can be sent. ```\n", "example": 1000 } }, "required": [ "source_currency", "target_currency", "source_amount" ], "additionalProperties": false }, { "type": "object", "properties": { "source_currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. `source_currency` and `target_currency` must differ, or the request returns `400`.\n", "example": "USD" }, "target_currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. `source_currency` and `target_currency` must differ, or the request returns `400`.\n", "example": "EUR" }, "target_amount": { "type": "number", "minimum": 1, "description": "The amount you want to receive. A positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295. ``` Only one of `source_amount` or `target_amount` can be sent. ```\n", "example": 1000 } }, "required": [ "source_currency", "target_currency", "target_amount" ], "additionalProperties": false } ] }, "examples": { "convert_source_amount": { "summary": "Convert a fixed amount of USD into EUR", "value": { "source_currency": "USD", "target_currency": "EUR", "source_amount": 10000 } }, "receive_target_amount": { "summary": "Receive a fixed amount of EUR, paid for in USD", "value": { "source_currency": "USD", "target_currency": "EUR", "target_amount": 10000 } } } } } }, "responses": { "201": { "description": "Balance conversion created successfully", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/BalanceConversion" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "You can only send source_amount or target_amount, not both." } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "balance_conversions" ], "summary": "List all Balance Conversions", "description": "Returns a list of your balance conversions. The balance conversions are returned sorted by creation date, with the most recent beneficiary appearing first.\n", "operationId": "getBalanceConversions", "parameters": [ { "in": "query", "name": "source_currency", "schema": { "type": "string", "format": "iso-4217" }, "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. When both `source_currency` and `target_currency` are sent they must differ, or the request returns `400`.\n", "example": "USD" }, { "in": "query", "name": "target_currency", "schema": { "type": "string", "format": "iso-4217" }, "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Supported currencies: USD, EUR, GBP, AED, SGD and AUD. When both `source_currency` and `target_currency` are sent they must differ, or the request returns `400`.\n", "example": "EUR" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of balance conversions matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceConversion" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/fx-rate": { "get": { "tags": [ "fx_rate" ], "summary": "Get Mid-Market Rate", "description": "Returns the current mid-market exchange rate for a given currency pair.\nThis is the base rate before any FX fees — FX fees will be charged on top of this rate.\n\n**Notes:**\n- This returns the mid-market rate only. FX fees are charged separately on top of this rate during actual conversions.\n- The rate is cached and `expires_at` indicates when the cached rate expires.\n", "operationId": "getMidMarketRate", "parameters": [ { "in": "query", "name": "source_currency", "required": true, "schema": { "type": "string", "format": "iso-4217" }, "description": "The source currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format (e.g. USD).\n", "example": "USD" }, { "in": "query", "name": "target_currency", "required": true, "schema": { "type": "string", "format": "iso-4217" }, "description": "The target currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format (e.g. EUR).\n", "example": "EUR" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "source_currency": { "type": "string", "description": "Source currency code.", "example": "USD" }, "target_currency": { "type": "string", "description": "Target currency code.", "example": "EUR" }, "mid_market_rate": { "type": "number", "format": "float", "description": "Mid-market exchange rate, as units of `target_currency` per one unit of `source_currency`. `0.859401` with `source_currency` USD and `target_currency` EUR means 1 USD = 0.859401 EUR. FX fees are charged on top of this rate. `1` when the two currencies are the same.\n", "example": 0.859401 }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 UTC timestamp indicating when this cached rate expires. A fresh rate is fetched from the provider after expiry.\n", "example": "2026-05-05T08:39:18Z" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating validation failure.\n", "example": "is not a valid currency" } } }, "examples": { "missing_currency": { "summary": "Missing currency parameter", "value": { "error": "Bad Request", "message": "can't be blank" } }, "invalid_currency": { "summary": "Invalid ISO currency code", "value": { "error": "Bad Request", "message": "is not a valid currency" } }, "non_string_currency": { "summary": "Non-string currency parameter", "value": { "error": "Bad Request", "message": "must be a string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/bank_account_validation": { "post": { "tags": [ "bank_account_validation" ], "summary": "Validate any bank account", "operationId": "validateBankAccount", "description": "Checks with the destination bank that an account exists and that the holder name matches, so you can\ncatch a bad account before you pay out to it rather than after a failed transfer.\n\nIdentify the account in one of two ways, and only one: pass the `id` of a bank account already saved\nagainst a beneficiary, or pass the account details inline. When `id` is present the inline fields are\nignored.\n\nValidation is chargeable. The request is rejected with `400` before the provider is called if your\nbalance does not cover the validation fee, unless fee collection is deferred on your account. You are\ncharged only when the provider completes the check; a check it could not complete is not charged.\n\n`status` is not the verdict on the account and is not whether you were charged. It reports whether the\nprovider returned a usable response at all. A check that completes and does *not* confirm the holder\nname still comes back as `status: success`. Read the verdict from `validation_message`, which carries\nthe match score, and read `fee_charged` to see whether a fee was actually taken.\n", "security": [ { "JWT": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BankAccount", "required": [ "country", "holder_name", "account_number", "bic_primary", "bic_secondary" ] }, { "type": "object", "title": "BankAccountReference", "properties": { "id": { "type": "string", "description": "The ID of an already saved beneficiary bank account", "example": "bene_5JU9yv0lGSUP" } }, "required": [ "id" ] } ] } } } }, "responses": { "200": { "description": "Bank account validation successful", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/BankAccountValidation" } } } }, "400": { "description": "Bad request" } } }, "get": { "tags": [ "bank_account_validation" ], "summary": "List all bank account validations", "description": "Returns the bank account validations your business has run, sorted by creation date with the most\nrecent first. Because `POST /bank_account_validation` is chargeable, use this to check whether an\naccount has already been validated before paying to validate it again.\n\n`country` is matched against the country recorded on the validation request, not against the\nbeneficiary's current country, so editing a beneficiary does not move its past validations between\nfilters.\n", "operationId": "getBankAccountValidations", "security": [ { "JWT": [] } ], "parameters": [ { "in": "query", "name": "beneficiary_account_id", "schema": { "type": "string" }, "description": "The ID of the beneficiary bank account to filter validations", "example": "bene_5JU9yv0lGSUP" }, { "in": "query", "name": "country", "schema": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country where the customer is located. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code, case-insensitive.\n", "example": "Ind" }, "description": "The ISO 3166-1 alpha-3 code of the country to filter validations" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of bank account validations matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccountValidation" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid" } } } } } } } } }, "/v2/beneficiaries": { "servers": [ { "url": "https://api.glomopay.com/api", "description": "Production server" } ], "post": { "tags": [ "beneficiary_v2" ], "summary": "Create a Beneficiary", "description": "Creates a beneficiary with structured nested objects for beneficiary details, address, and bank account or UPI information.\n", "operationId": "createBeneficiaryV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryV2CreateRequest" }, "examples": { "payout_usd": { "summary": "Payout Beneficiary — USD (SWIFT)", "value": { "category": "payout", "beneficiary": { "name": "John Doe", "type": "individual", "address": { "address_line1": "456 Main Street", "city": "Los Angeles", "state": "CA", "country_code": "USA", "postal_code": "90001" } }, "bank_account": { "account_number": "1234567890", "swift_code": "CITIUS33", "currency": "USD" }, "notes": { "invoice_ref": "INV-2026-002" } } }, "payout_eur": { "summary": "Payout Beneficiary — EUR (SEPA, IBAN only)", "value": { "category": "payout", "beneficiary": { "name": "ACME GmbH", "type": "business", "address": { "address_line1": "Friedrichstrasse 12", "city": "Berlin", "state": "Berlin", "country_code": "DEU", "postal_code": "10117" } }, "bank_account": { "account_number": "DE89370400440532013000", "currency": "EUR" } } }, "payout_gbp": { "summary": "Payout Beneficiary — GBP (Faster Payments, sort code)", "value": { "category": "payout", "beneficiary": { "name": "Jane Smith", "type": "individual", "address": { "address_line1": "24 Cheapside", "city": "London", "state": "England", "country_code": "GBR", "postal_code": "EC2V 6DN" } }, "bank_account": { "account_number": "31926819", "local_routing_number": "601613", "currency": "GBP" } } }, "payout_aed": { "summary": "Payout Beneficiary — AED (IBAN only)", "value": { "category": "payout", "beneficiary": { "name": "ACME Trading LLC", "type": "business", "address": { "address_line1": "Sheikh Zayed Road", "city": "Dubai", "state": "Dubai", "country_code": "ARE", "postal_code": "00000" } }, "bank_account": { "account_number": "AE070331234567890123456", "currency": "AED" } } }, "payout_aud": { "summary": "Payout Beneficiary — AUD (NPP, BSB)", "value": { "category": "payout", "beneficiary": { "name": "ACME Pty Ltd", "type": "business", "address": { "address_line1": "100 Collins Street", "city": "Melbourne", "state": "VIC", "country_code": "AUS", "postal_code": "3000" } }, "bank_account": { "account_number": "123456789", "local_routing_number": "062000", "currency": "AUD" } } }, "payout_inr": { "summary": "Payout Beneficiary — INR (IFSC)", "value": { "category": "payout", "beneficiary": { "name": "Rahul Sharma", "type": "individual", "address": { "address_line1": "12 MG Road", "city": "Bengaluru", "state": "Karnataka", "country_code": "IND", "postal_code": "560001" } }, "bank_account": { "account_number": "9876543210", "local_routing_number": "KKBK0000261", "currency": "INR" } } }, "payout_upi_beneficiary": { "summary": "Payout Beneficiary — INR (UPI)", "value": { "category": "payout", "beneficiary": { "name": "Rahul Sharma", "type": "individual", "address": { "address_line1": "12 MG Road", "city": "Bengaluru", "state": "Karnataka", "country_code": "IND", "postal_code": "560001" } }, "upi_account": { "upi_id": "1111111111@ybl" }, "notes": { "invoice_ref": "INV-2026-003" } } }, "lrs_beneficiary": { "summary": "LRS Beneficiary with all fields", "value": { "category": "lrs", "beneficiary": { "name": "ACME Corporation", "type": "business", "email": "finance@acme.com", "phone": "+1-555-123-4567", "nickname": "ACME Primary Account", "address": { "address_line1": "123 Business Park", "address_line2": "Suite 100", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10001" } }, "bank_account": { "account_number": "1234567890", "name": "Citibank NA", "swift_code": "CITIUS33", "local_routing_number": "021000089", "currency": "USD", "address": { "address_line1": "388 Greenwich Street", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10013" }, "intermediate_bank": { "name": "JPMorgan Chase Bank", "country": "USA", "swift_code": "CHASUS33", "account_number": "123456789" } }, "notes": { "invoice_ref": "INV-2026-001", "project": "Alpha" } } } } } } }, "responses": { "201": { "description": "Beneficiary created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryV2" }, "example": { "id": "bene_5JU9yv0lGSUP", "name": "ACME Corporation", "type": "business", "category": "lrs", "status": "pending", "email": "finance@acme.com", "phone": "+1-555-123-4567", "nickname": "ACME Primary Account", "upi_account": null, "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:00:00Z", "address": { "address_line1": "123 Business Park", "address_line2": "Suite 100", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10001" }, "bank_account": { "account_number": "1234567890", "name": "Citibank NA", "swift_code": "CITIUS33", "local_routing_number": "021000089", "currency": "USD", "address": { "address_line1": "388 Greenwich Street", "address_line2": "", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10013" }, "intermediate_bank": { "name": "JPMorgan Chase Bank", "country": "USA", "swift_code": "CHASUS33", "account_number": "123456789" } }, "notes": { "invoice_ref": "INV-2026-001", "project": "Alpha" } } } } }, "400": { "description": "Bad Request - Validation errors in the request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "description": "Error message indicating which fields failed validation" } } }, "examples": { "missing_category": { "summary": "Missing category field", "value": { "error": "Bad Request", "message": "Category can't be blank, Category must be one of: lrs, payout" } }, "invalid_category": { "summary": "Invalid category value", "value": { "error": "Bad Request", "message": "Category must be one of: lrs, payout" } }, "missing_beneficiary_name": { "summary": "Missing beneficiary name", "value": { "error": "Bad Request", "message": "Beneficiary name can't be blank" } }, "invalid_swift_code": { "summary": "Invalid SWIFT code format", "value": { "error": "Bad Request", "message": "Swift code must be 8 to 11 characters long" } }, "lrs_invalid_swift_length": { "summary": "LRS SWIFT code must be 8 characters", "value": { "error": "Bad Request", "message": "Swift code must be 8 characters long" } }, "lrs_missing_routing_number": { "summary": "LRS requires local routing number", "value": { "error": "Bad Request", "message": "Local routing number can't be blank" } }, "unresolved_bank_details": { "summary": "Bank details omitted and could not be resolved", "value": { "error": "Bad Request", "message": "Could not resolve bank details from the swift_code/local_routing_number provided. Send bank_account.name and bank_account.address, or correct the identifier." } }, "missing_address": { "summary": "Missing beneficiary address", "value": { "error": "Bad Request", "message": "Beneficiary address is required" } } } } } }, "409": { "description": "Conflict - a beneficiary with this account number already exists on your account. The body does not carry the id of the existing record: store the `bene_` id when you create one, or recover it by listing beneficiaries.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "A beneficiary with this account number already exists" } } } } } }, "422": { "description": "Unprocessable Entity - Business logic errors (e.g., duplicate bank account)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unprocessable Entity" }, "message": { "type": "string", "description": "Error message indicating the business logic error" } } }, "examples": { "duplicate_account": { "summary": "Duplicate bank account", "value": { "error": "Unprocessable Entity", "message": "Validation failed: Business already had this Account Number, Account Type and Transfer Method" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "beneficiary_v2" ], "summary": "List Beneficiaries", "description": "Returns a paginated list of beneficiaries. Optionally filter by status.\n", "operationId": "listBeneficiariesV2", "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "pending", "active", "rejected" ] }, "description": "Filter beneficiaries by status.", "example": "active" }, { "in": "query", "name": "page", "required": false, "schema": { "type": "integer" }, "description": "Page number for pagination.", "example": 1 }, { "in": "query", "name": "per_page", "required": false, "schema": { "type": "integer" }, "description": "Number of results per page.", "example": 20 } ], "responses": { "200": { "description": "A paginated list of beneficiaries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficiaryV2" } }, "page_meta": { "type": "object", "properties": { "current": { "type": "integer", "example": 1 }, "previous": { "type": [ "integer", "null" ], "example": null }, "next": { "type": [ "integer", "null" ], "example": 2 }, "per_page": { "type": "integer", "example": 20 }, "pages": { "type": "integer", "example": 3 }, "count": { "type": "integer", "example": 50 } } } } }, "example": { "data": [ { "id": "bene_6989dfef8dP9z", "name": "ACME Corporation", "category": "payout", "email": "finance@acme.com", "phone": "+14155551234", "nickname": "ACME Primary Account", "status": "active", "type": "business", "created_at": "2026-02-09T11:03:25Z", "updated_at": "2026-02-09T11:14:36Z", "address": { "address_line1": "123 Business Park", "address_line2": "Suite 100", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10001" }, "bank_account": { "account_number": "1234567890123", "name": "Citibank NA", "swift_code": "CITIUS33", "local_routing_number": "021000089", "currency": "USD", "address": { "address_line1": "388 Greenwich Street", "address_line2": "", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10013" }, "intermediate_bank": { "name": "JPMorgan Chase Bank", "country": "USA", "swift_code": "CHASUS33", "account_number": "123456789" } }, "upi_account": null, "notes": { "invoice_ref": "INV-2026-001", "project": "Alpha" } } ], "page_meta": { "current": 1, "previous": null, "next": null, "per_page": 20, "pages": 1, "count": 10 } } } } }, "400": { "description": "Bad Request - Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Status is not included in the list" } } }, "example": { "error": "Bad Request", "message": "Status is not included in the list" } } } } }, "security": [ { "JWT": [] } ] } }, "/v2/beneficiaries/{id}": { "servers": [ { "url": "https://api.glomopay.com/api", "description": "Production server" } ], "get": { "tags": [ "beneficiary_v2" ], "summary": "Get a Beneficiary", "description": "Retrieves the details of an existing beneficiary by ID.\n", "operationId": "getBeneficiaryByIdV2", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the beneficiary.", "example": "bene_698c0615XZocZ" } ], "responses": { "200": { "description": "Beneficiary details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeneficiaryV2" }, "example": { "id": "bene_698c0615XZocZ", "name": "ACME Corporation", "type": "business", "category": "lrs", "status": "active", "email": "finance@acme.com", "phone": "+1-555-123-4567", "nickname": "ACME Primary Account", "documents": [ "doc_68e7980auYRAs" ], "address": { "address_line1": "123 Business Park", "address_line2": "Suite 100", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10001" }, "bank_account": { "account_number": "1234567890", "name": "Citibank NA", "swift_code": "CITIUS33", "local_routing_number": "021000089", "currency": "USD", "address": { "address_line1": "388 Greenwich Street", "city": "New York", "state": "NY", "country_code": "USA", "postal_code": "10013" }, "intermediate_bank": { "name": "JPMorgan Chase Bank", "country": "USA", "swift_code": "CHASUS33", "account_number": "123456789" } }, "created_at": "2025-01-15T10:00:00Z", "updated_at": "2025-01-15T10:00:00Z", "notes": { "invoice_ref": "INV-2026-001", "project": "Alpha" } } } } }, "404": { "description": "Beneficiary not found or does not belong to the authenticated business", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/v2/beneficiaries/{id}/mock-review": { "servers": [ { "url": "https://api.glomopay.com/api", "description": "Production server" } ], "patch": { "tags": [ "beneficiary_v2" ], "summary": "Mock Review a Beneficiary", "description": "Simulates a review action (approve or reject) on a beneficiary. This endpoint is only available in sandbox/non-production environments.\n", "operationId": "mockReviewBeneficiaryV2", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the beneficiary to review.", "example": "bene_698c0615XZocZ" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "review_action" ], "properties": { "review_action": { "type": "string", "enum": [ "approve", "reject" ], "description": "The review action to perform on a `pending` beneficiary. `approve` moves it to `active`; `reject` moves it to `rejected`. A beneficiary that is not `pending` returns a `422`.\n", "example": "approve" } } }, "example": { "review_action": "approve" } } } }, "responses": { "200": { "description": "Beneficiary status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Beneficiary status updated successfully" } } }, "example": { "message": "Beneficiary status updated successfully" } } } }, "400": { "description": "Bad Request - Invalid review action", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Review action is not included in the list" } } }, "example": { "error": "Bad Request", "message": "Review action is not included in the list" } } } }, "422": { "description": "Unprocessable Entity - Beneficiary is already in a terminal state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid beneficiary status update" } } }, "example": { "error": "Invalid beneficiary status update" } } } } }, "security": [ { "JWT": [] } ] } }, "/customer": { "post": { "tags": [ "Customer" ], "summary": "Create a new customer", "description": "Creates a customer with basic information such as name, contact information, and address. To check complete list of API validations, click [here](/platform/validations#validations-for-creating-customers).\n\nSome fields are required only for a particular flow. **Account funding** additionally requires `dob` and `nationality`, and reads `kyc.last_kyc_date`; **LRS** requires `phone` and `kyc.pan_number` for a customer in India. Creating a customer is not idempotent - a second create with an email already on your account returns `400 Email has already been taken` and does not return the existing record. Store the `id` against your own user, or recover it with `GET /v1/customer?email_address=`.\n", "operationId": "createCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer", "required": [ "name", "customer_type", "email", "address", "city", "state", "country" ] } } } }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad request" } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Customer" ], "summary": "List all customers", "description": "Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.\n", "operationId": "getCustomers", "parameters": [ { "in": "query", "name": "customer_type", "schema": { "type": "string", "enum": [ "individual", "business" ] }, "description": "Type of customer to filter" }, { "in": "query", "name": "email_address", "schema": { "type": "string", "format": "email" }, "description": "Filter customers by email address" }, { "in": "query", "name": "tax_identification_number", "schema": { "type": "string" }, "description": "Filter customers by PAN (tax identification number), for customers created with `kyc.pan_number`. Matched exactly on the normalised value (case-insensitive; the value is trimmed and upper-cased before matching), so a partial PAN returns no results. An invalid PAN format returns a 400 error.\n" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of customers matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/customer/{id}": { "get": { "tags": [ "Customer" ], "summary": "Retrieve a customer", "description": "Retrieves details of a Customer.\n", "operationId": "getCustomerById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer. Starts with `cust_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `cust_`; a well- formed ID that doesn't match a customer on your account returns `404`.\n", "example": "cust_5JU9yv0lGSUP" } ], "responses": { "200": { "description": "Customer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] }, "patch": { "tags": [ "Customer" ], "summary": "Update a customer", "description": "Updates the contact details of an existing customer. Only the customer's `email` and `phone` can be updated. This is a partial update — send only the fields you want to change; any field you omit is left untouched. You must supply at least one of `email` or `phone`, and a supplied field cannot be sent as blank or `null`. The phone number is validated against the customer's stored country. To check the complete list of API validations, click [here](/platform/validations#validations-for-updating-customers).\n**Account funding** partners can also update the address and `kyc.last_kyc_date`, in the same shape as on create, for example after a re-KYC. Other fields, such as `name`, `dob` and `kyc.pan_number`, are not updated.\n", "operationId": "updateCustomer", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer. Starts with `cust_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `cust_`; a well- formed ID that doesn't match a customer on your account returns `404`.\n", "example": "cust_5JU9yv0lGSUP" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "description": "At least one of `email` or `phone` must be provided.\n", "properties": { "email": { "type": "string", "format": "email", "description": "The new email address of the customer.\n", "example": "customer@gmail.com" }, "phone": { "type": "string", "description": "The new phone number of the customer, with country code. Validated against the customer's stored country using the [phonelib](https://github.com/daddyz/phonelib?tab=readme-ov-file) library.\n", "example": "+91-9023456789" }, "address": { "type": "string", "description": "**Account funding only.** Send with `city`, `state`, `country` and `pincode`. Replaces the stored address.\n", "example": "Villa 12, Jumeirah Beach Road" }, "city": { "type": "string", "example": "Dubai" }, "state": { "type": "string", "example": "Dubai" }, "country": { "type": "string", "format": "iso-3166-1-alpha-3", "example": "ARE" }, "pincode": { "type": "string", "example": "682001" }, "kyc": { "type": "object", "description": "**Account funding only.**\n", "properties": { "last_kyc_date": { "type": "string", "format": "date", "description": "When you last completed KYC on this customer, as `YYYY-MM-DD`. Cannot be in the future or earlier than the date already on file; the same date again changes nothing. Only for a customer created with a `kyc` block.\n", "example": "2026-10-01" } } } } } } } }, "responses": { "200": { "description": "Customer updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad request — no updatable field was supplied, a supplied field was blank, the email or phone was invalid, or the customer ID was malformed.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating what was invalid" } } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/customer/{id}/bank-accounts": { "post": { "tags": [ "Customer" ], "summary": "Register a customer's bank account", "description": "Registers the bank account a customer sends money from.\n\nA customer holds one bank account at a time. Registering another one replaces the existing account, so use this endpoint to correct an account or to move a customer to a new bank.\n\nFor an LRS remittance, register the customer's Indian bank account with `POST /customer/{id}/bank_account` (`createLrsCustomerBankAccount`) instead. Accounts registered here have `acccus_` IDs and cannot be used as `lrs.bank_account_id` on an order.\n", "operationId": "createCustomerBankAccount", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer", "example": "cust_5JU9yv0lGSUP" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBankAccount", "required": [ "account_number", "bank_name" ] } } } }, "responses": { "201": { "description": "Bank account registered. Any account previously registered against this customer is no longer in use.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerBankAccount" } } } }, "400": { "description": "The request is missing an account number or a bank name, or carries neither `bic_primary` nor `bic_secondary`.\n" }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Customer" ], "summary": "List a customer's bank accounts", "description": "Returns the bank accounts registered against a customer.\n", "operationId": "getCustomerBankAccounts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer", "example": "cust_5JU9yv0lGSUP" } ], "responses": { "200": { "description": "Bank accounts retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerBankAccount" } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/customer/{id}/bank_account": { "post": { "tags": [ "lrs" ], "summary": "Register a customer's LRS bank account", "description": "Registers the Indian bank account an LRS remittance is debited from. Pass the returned `id` (`acclrs_...`) as `lrs.bank_account_id` when you create an LRS order.\n\nThis is not the same endpoint as `POST /customer/{id}/bank-accounts` (`createCustomerBankAccount`), and the two sets of accounts are kept apart:\n- A customer can hold several LRS bank accounts. Registering another one adds to the list, whereas\n `createCustomerBankAccount` keeps one account per customer and replaces it. Registering the same\n account number at the same bank twice is rejected here.\n\n- LRS bank accounts are not returned by `GET /customer/{id}/bank-accounts`, and a bank account from\n `POST /customer/{id}/bank-accounts` cannot be used as `lrs.bank_account_id`.\n\n- The account number is returned in full, as sent.\n", "operationId": "createLrsCustomerBankAccount", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer", "example": "cust_68468bfcxaGo2" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LrsCustomerBankAccount", "required": [ "bank_code", "account_number" ] }, "example": { "bank_code": "hdfc", "account_number": "12345678901234", "bank_customer_id": "12345678" } } } }, "responses": { "201": { "description": "LRS bank account registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LrsCustomerBankAccount" }, "example": { "id": "acclrs_68468c03g9xt7", "bank_code": "hdfc", "account_number": "12345678901234", "bank_customer_id": "12345678" } } } }, "400": { "description": "Bad Request — `bank_code` or `account_number` is missing, `bank_code` is not a value returned by `GET /lrs/banks` for your account, `account_number` is not all digits or its length is outside the range the bank accepts, `bank_customer_id` is not all digits or its length is outside the range the bank accepts, the customer does not exist on your account, or the same account number is already registered for this customer at the same bank.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Bank account already exists" } } }, "examples": { "account_number_missing": { "summary": "account_number missing", "value": { "error": "Bad Request", "message": "Validation failed: Account number can't be blank" } }, "bank_code_not_valid": { "summary": "bank_code is not a supported bank", "value": { "error": "Bad Request", "message": "Validation failed: Bank code HDFC is not a valid bank code" } }, "bank_code_not_enabled": { "summary": "Bank not enabled for your account", "value": { "error": "Bad Request", "message": "Validation failed: Bank code axis is not enabled for your business" } }, "bank_customer_id_not_digits": { "summary": "bank_customer_id contains a non-digit", "value": { "error": "Bad Request", "message": "Validation failed: Bank customer ID must contain only digits" } }, "customer_not_found": { "summary": "Customer does not exist on your account", "value": { "error": "Bad Request", "message": "Customer does not exist" } }, "duplicate_account": { "summary": "Account already registered at the same bank", "value": { "error": "Bad Request", "message": "Bank account already exists" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "lrs" ], "summary": "List a customer's LRS bank accounts", "description": "Returns the LRS bank accounts stored against a customer, including those registered with `POST /customer/{id}/bank_account`. Account numbers are returned in full. May include accounts added through other flows, with IDs that do not start with `acclrs_`. Extra fields can include the account holder's name and internal verification data; treat them as sensitive and don't rely on them.\n", "operationId": "getLrsCustomerBankAccounts", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer", "example": "cust_68468bfcxaGo2" } ], "responses": { "200": { "description": "LRS bank accounts retrieved. Empty when the customer has none.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LrsCustomerBankAccount" } }, "example": [ { "id": "acclrs_68468c03g9xt7", "bank_code": "hdfc", "account_number": "12345678901234", "bank_customer_id": "12345678" } ] } } }, "400": { "description": "Bad Request — the customer does not exist on your account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Customer does not exist" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/customer/{id}/bank_account/{bank_account_id}": { "get": { "tags": [ "lrs" ], "summary": "Retrieve a customer's LRS bank account", "description": "Returns one LRS bank account stored against a customer. The account number is returned in full. May include accounts added through other flows, with IDs that do not start with `acclrs_`. Extra fields can include the account holder's name and internal verification data; treat them as sensitive and don't rely on them.\n", "operationId": "getLrsCustomerBankAccountById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer", "example": "cust_68468bfcxaGo2" }, { "in": "path", "name": "bank_account_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the LRS bank account", "example": "acclrs_68468c03g9xt7" } ], "responses": { "200": { "description": "LRS bank account retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LrsCustomerBankAccount" }, "example": { "id": "acclrs_68468c03g9xt7", "bank_code": "hdfc", "account_number": "12345678901234", "bank_customer_id": "12345678" } } } }, "400": { "description": "Bad Request — the customer does not exist on your account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Customer does not exist" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } }, "404": { "description": "Not Found — the customer has no bank account with this ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Bank account not found" } } } } } } }, "security": [ { "JWT": [] } ] }, "patch": { "tags": [ "lrs" ], "summary": "Update the bank customer ID on an LRS bank account", "description": "Sets `bank_customer_id` on a customer's LRS bank account, for example to correct a value the customer entered wrongly. Any existing value is replaced. The value is checked against the rules of the account's bank.\n", "operationId": "updateLrsCustomerBankAccount", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the customer", "example": "cust_68468bfcxaGo2" }, { "in": "path", "name": "bank_account_id", "required": true, "schema": { "type": "string" }, "description": "The ID of the LRS bank account", "example": "acclrs_68468c03g9xt7" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_customer_id": { "type": "string", "description": "The customer's identifier at their bank. Required for banks that use one. For those banks it must contain only digits, with a length inside the range the bank accepts. For other banks it is optional; omitting it clears the value.\n", "example": "12345678" } } }, "example": { "bank_customer_id": "12345678" } } } }, "responses": { "200": { "description": "Bank customer ID updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LrsCustomerBankAccount" }, "example": { "id": "acclrs_68468c03g9xt7", "bank_code": "hdfc", "account_number": "12345678901234", "bank_customer_id": "12345678" } } } }, "400": { "description": "Bad Request — the customer does not exist on your account, `bank_customer_id` is missing for a bank that uses one, or it is not all digits or its length is outside the range the bank accepts.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Bank customer id can't be blank" } } }, "examples": { "customer_not_found": { "summary": "Customer does not exist on your account", "value": { "error": "Bad Request", "message": "Customer does not exist" } }, "bank_customer_id_missing": { "summary": "bank_customer_id missing for a bank that uses one", "value": { "error": "Bad Request", "message": "Bank customer id can't be blank" } }, "bank_customer_id_not_digits": { "summary": "bank_customer_id contains a non-digit", "value": { "error": "Bad Request", "message": "Bank Customer ID must contain only digits" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } }, "404": { "description": "Not Found — the customer has no bank account with this ID.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Bank account not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/document": { "post": { "tags": [ "Document" ], "summary": "Create a new document", "description": "Uploads a file and returns a document record you can reference from other resources — as the invoice\nor supporting paperwork on a payin or payout, or as evidence when responding to a request for\ninformation (RFI).\n\nSend the request as `multipart/form-data`. The file must be a JPEG, PNG or PDF of at most 10 MB\n(10,485,760 bytes), and the uploaded filename and `document_name` at most 128 characters each.\n\nUpload is a separate step from attaching, and each consumer names the reference differently: pass the\nreturned `id` as `document_id` when creating a payin, an order or a refund, and inside the `documents`\narray when creating a payout or responding to an RFI. Check the schema of the endpoint you are\nattaching to — the key inside `documents` is not the same on every one. A document that is never\nreferenced stays listed but has no effect.\n", "operationId": "createDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document_name": { "type": "string", "description": "The name of the document\n", "example": "invoice" }, "file": { "type": "string", "format": "binary", "description": "The file to be uploaded. This should be sent as a binary in the multipart/form-data request.\n" } }, "required": [ "file", "document_name" ] } } } }, "responses": { "201": { "description": "Document created successfully", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Bad request" } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Document" ], "summary": "List all documents", "description": "Returns a list of your documents. The documents are returned sorted by creation date, with the most recent documents appearing first.\n", "operationId": "getDocuments", "parameters": [ { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of documents matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad request" } }, "security": [ { "JWT": [] } ] } }, "/document/{document_id}": { "get": { "tags": [ "Document" ], "summary": "Get a document by ID", "description": "Retrieve a single document by its unique identifier.\n", "operationId": "getDocumentById", "parameters": [ { "name": "document_id", "in": "path", "description": "The ID of the document to retrieve. Starts with `doc_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `doc_`; a well-formed ID that doesn't match a document on your account returns `404`.\n", "required": true, "schema": { "type": "string", "example": "doc_12345" } } ], "responses": { "200": { "description": "Document retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Validation failed: Id must start with 'doc_' and contain only alphanumeric characters" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Document not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/orders": { "post": { "tags": [ "Orders" ], "summary": "Create a new order", "description": "Create an order for checkout in one of two ways:\n- **Order without quote** - specify the amount, currency and payment methods inline\n (`Orders`).\n\n- **Order with quote** - pass a `quote_id` from `POST /quotes` (with `resource: payin`) to bind\n the order to a quote. When supplied, the quote is the single source of truth for amount,\n currency, payment method, expiry and fee splits; the locked fields (`amount`, `currency`,\n `price_id`, `payment_methods`, `split_ids`) must not be sent (`CreateOrderWithQuoteRequest`).\n **When a `quote_id` is supplied, the order's expiry is set to the quote's expiry.**\n\nThe request variant is selected by the presence of `quote_id`.\n\nAn **account funding** order is bound to a quote with `resource_type: account_funding` and also requires `beneficiary_id`. A declined order answers `422` with a `code`.\n\nPass `split_ids` to declare your share of a dynamic pricing rule's fee for this order. See [Dynamic Fee Split](#tag/pricing_split). If a split on the order later stops resolving (Glomo deleted the underlying rule, or the rule is no longer dynamic) opening the checkout returns a `400 Bad Request`, the order is expired, and you must issue a new one.\nTo check complete list of API validations, click [here](/platform/validations#validations-for-creating-orders).\n", "operationId": "createOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Orders", "required": [ "amount", "currency", "customer_id" ] }, { "$ref": "#/components/schemas/CreateOrderWithQuoteRequest", "required": [ "quote_id", "customer_id" ] } ] } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Bad Request — validation error. For quote-based orders, possible messages include `quote_id not found`, `quote_id is not a payin quote`, `quote_id has expired`, `quote_id has already been used`, and `amount cannot be specified when quote_id is present` (likewise for any other locked field: `currency`, `price_id`, `payment_methods`, `split_ids`).\n\nFor `split_ids`, every id must resolve to a live dynamic rule declared by your business, every dynamic rule on the same dimension must be declared, and every declared payment method must be enabled for your business.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "Currency not supported" } } }, "examples": { "currency_not_supported": { "summary": "Currency not supported", "value": { "error": "Bad Request", "message": "Currency not supported" } }, "duplicate_request_id": { "summary": "Duplicate request_id", "value": { "error": "Bad Request", "message": "Order already exists for this request_id" } }, "quote_not_found": { "summary": "quote_id not found", "value": { "error": "Bad Request", "message": "quote_id not found" } }, "quote_not_payin": { "summary": "quote_id is not a payin quote", "value": { "error": "Bad Request", "message": "quote_id is not a payin quote" } }, "quote_expired": { "summary": "quote_id has expired", "value": { "error": "Bad Request", "message": "quote_id has expired" } }, "quote_already_used": { "summary": "quote_id has already been used", "value": { "error": "Bad Request", "message": "quote_id has already been used" } }, "locked_field_amount": { "summary": "Locked field sent with quote_id", "value": { "error": "Bad Request", "message": "amount cannot be specified when quote_id is present" } }, "locked_field_split_ids": { "summary": "split_ids sent with quote_id", "value": { "error": "Bad Request", "message": "Validation failed: Split ids cannot be specified when quote_id is present" } }, "split_ids_unresolved": { "summary": "A split id does not resolve to a live dynamic rule", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are invalid or no longer point at a dynamic rule: psplit_7Kq2mXbTdLp9" } }, "split_ids_incomplete": { "summary": "Another dynamic rule on the same dimension is not declared", "value": { "error": "Bad Request", "message": "Validation failed: Split ids must be declared for every dynamic rule on the dimension, missing rules: price_Kd82nvQ1TzAe" } }, "split_ids_method_not_enabled": { "summary": "A declared payment method is not enabled for your business", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are not valid for any enabled payment method: bank_transfer" } }, "split_ids_required": { "summary": "split_ids omitted on an account where a declaration is required", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are required when dynamic fee splits are enforced" } } } } } }, "422": { "description": "Unprocessable Entity - the request was well formed but the order was declined. Returned for account funding orders, which carry a machine-readable `code` beside the message.\n\n`order_cap_unavailable` and `payment_method_unavailable` share the same customer-safe message, so branch on `code`, never on `message`. The cap applies to the **destination** currency - the amount credited, not the amount charged to the card.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Unprocessable Entity" ] }, "message": { "type": "string", "description": "A customer-safe description of the decline.\n", "example": "The order amount is above the limit for this programme" }, "code": { "type": "string", "enum": [ "quote_not_found", "quote_not_owned", "quote_expired", "quote_resource_type_missing", "beneficiary_missing", "order_amount_above_cap", "order_cap_unavailable", "payment_method_unavailable" ], "description": "Why the order was declined.\n\n- `quote_not_found` - no quote with that id.\n- `quote_not_owned` - the quote belongs to another business.\n- `quote_expired` - the quote lapsed. Create a new one.\n- `quote_resource_type_missing` - the quote did not declare `account_funding`.\n- `beneficiary_missing` - no `beneficiary_id` named, or it does not resolve.\n- `order_amount_above_cap` - above the configured cap for that currency.\n- `order_cap_unavailable` - no cap is configured for that currency. Not the same as\n the amount being too large.\n- `payment_method_unavailable` - your account has no active card payment method.\n", "example": "order_amount_above_cap" } } }, "examples": { "order_amount_above_cap": { "summary": "Above the configured cap", "value": { "error": "Unprocessable Entity", "message": "The order amount is above the limit for this programme", "code": "order_amount_above_cap" } }, "order_cap_unavailable": { "summary": "No cap configured for the destination currency", "value": { "error": "Unprocessable Entity", "message": "This order cannot be accepted at this time", "code": "order_cap_unavailable" } }, "beneficiary_missing": { "summary": "beneficiary_id missing or unresolvable", "value": { "error": "Unprocessable Entity", "message": "Beneficiary not found", "code": "beneficiary_missing" } }, "quote_resource_type_missing": { "summary": "The quote was not created for account funding", "value": { "error": "Unprocessable Entity", "message": "This quote cannot be used for an account funding order", "code": "quote_resource_type_missing" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Orders" ], "summary": "List all orders", "description": "Returns a list of your orders. The orders are returned sorted by creation date, with the most recent order appearing first.\n", "operationId": "getOrders", "parameters": [ { "in": "query", "name": "customer_id", "schema": { "type": "string" }, "description": "Orders of customer to filter" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "action_required", "under_review", "paid", "failed", "cancelled", "expired" ] }, "description": "Return only orders in this status. Uses the same values as the order's `status` field.\n" }, { "in": "query", "name": "request_id", "schema": { "type": "string" }, "description": "Return only the order created with this `request_id`.", "example": "unique_order_request_id_123" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of orders matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderResponse" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message.\n", "example": "Invalid customer_id" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Retrieve an order", "description": "Retrieve details of an order.\n", "operationId": "getOrderById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the order. Starts with `order_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `order_`; a well-formed ID that doesn't match an order on your account returns `404`.\n", "example": "order_678a4c88hpAjf" } ], "responses": { "200": { "description": "Payment link retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "404": { "description": "Payment link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/orders/{id}/update-rfi": { "patch": { "tags": [ "Orders" ], "summary": "Update RFI documents for an order", "description": "Updates the RFI (Request for Information) document status for an order. This endpoint is used to submit required documents when an order is in 'action_required' status due to sanction screening.\n", "operationId": "updateOrderRfi", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the order to update RFI for", "example": "order_678a4c88hpAjf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "description": "Array of documents to be submitted for RFI requirements", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the document being uploaded for this RFI requirement\n", "example": "doc_67fc2f42468Bw" }, "rfi_doc_id": { "type": "string", "description": "The unique identifier of the RFI document being submitted\n", "example": "rfidoc_68c8dffedhMHD" } }, "required": [ "id", "rfi_doc_id" ], "additionalProperties": false } } }, "required": [ "documents" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "RFI document updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "Invalid rfi_doc_id or order not in action_required status" } } } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/payin": { "post": { "tags": [ "payment_link" ], "summary": "Create a new Payment Link", "description": "Create a shareable URL for a hosted payment page in one of two ways:\n- **Payment link without quote** — specify the amount, currency, expiry and payment methods\n inline (`PaymentLink`).\n\n- **Payment link with quote** — pass a `quote_id` from `POST /quotes` (with `resource: payin`) to\n bind the payment link to a quote. When supplied, the quote is the single source of truth for\n amount, currency, payment method, expiry and fee splits; the locked fields (`amount`, `currency`,\n `expires_at`, `price_id`, `payment_methods`, `split_ids`) must not be sent\n (`CreatePaymentLinkWithQuoteRequest`). **When a `quote_id` is supplied, the payment link's\n expiry is set to the quote's expiry.**\n\nThe request variant is selected by the presence of `quote_id`.\n\nPass `split_ids` to declare your share of a dynamic pricing rule's fee for this payment link. See [Dynamic Fee Split](#tag/pricing_split). If a split on the payment link later stops resolving — Glomo deleted the underlying rule, or the rule is no longer dynamic — opening the checkout returns a `400 Bad Request`, the payment link is expired, and you must issue a new one.\n\nPayment link creation does not take a `request_id` and has no duplicate-request check. Sending the same request twice without a `quote_id` creates two payment links, and `GET /v1/payin` has no `request_id` filter.\nTo check complete list of API validations, click [here](/platform/validations#validations-for-creating-payment-links).\n", "operationId": "createPayin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentLink", "required": [ "amount", "currency", "customer_id", "purpose_code", "expires_at" ] }, { "$ref": "#/components/schemas/CreatePaymentLinkWithQuoteRequest", "required": [ "quote_id", "customer_id", "purpose_code" ] } ] } } } }, "responses": { "201": { "description": "Payment link created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "Bad Request — validation error. For quote-based payment links, possible messages include `quote_id not found`, `quote_id is not a payin quote`, `quote_id has expired`, `quote_id has already been used`, and `amount cannot be specified when quote_id is present` (likewise for any other locked field: `currency`, `expires_at`, `price_id`, `payment_methods`, `split_ids`).\n\nFor `split_ids`, every id must resolve to a live dynamic rule declared by your business, every dynamic rule on the same dimension must be declared, and every declared payment method must be enabled for your business.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "You can only send source_amount or target_amount, not both." } } }, "examples": { "amount_conflict": { "summary": "Both amounts specified", "value": { "error": "Bad Request", "message": "You can only send source_amount or target_amount, not both." } }, "quote_not_found": { "summary": "quote_id not found", "value": { "error": "Bad Request", "message": "quote_id not found" } }, "quote_not_payin": { "summary": "quote_id is not a payin quote", "value": { "error": "Bad Request", "message": "quote_id is not a payin quote" } }, "quote_expired": { "summary": "quote_id has expired", "value": { "error": "Bad Request", "message": "quote_id has expired" } }, "quote_already_used": { "summary": "quote_id has already been used", "value": { "error": "Bad Request", "message": "quote_id has already been used" } }, "locked_field_amount": { "summary": "Locked field sent with quote_id", "value": { "error": "Bad Request", "message": "amount cannot be specified when quote_id is present" } }, "locked_field_split_ids": { "summary": "split_ids sent with quote_id", "value": { "error": "Bad Request", "message": "Validation failed: Split ids cannot be specified when quote_id is present" } }, "split_ids_unresolved": { "summary": "A split id does not resolve to a live dynamic rule", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are invalid or no longer point at a dynamic rule: psplit_7Kq2mXbTdLp9" } }, "split_ids_incomplete": { "summary": "Another dynamic rule on the same dimension is not declared", "value": { "error": "Bad Request", "message": "Validation failed: Split ids must be declared for every dynamic rule on the dimension, missing rules: price_Kd82nvQ1TzAe" } }, "split_ids_method_not_enabled": { "summary": "A declared payment method is not enabled for your business", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are not valid for any enabled payment method: bank_transfer" } }, "split_ids_required": { "summary": "split_ids omitted on an account where a declaration is required", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are required when dynamic fee splits are enforced" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "payment_link" ], "summary": "List all payment links", "description": "Returns a list of your payment links. The payment links are returned sorted by creation date, with the most recent payment link appearing first.\n", "operationId": "getPayins", "parameters": [ { "in": "query", "name": "customer_id", "schema": { "type": "string" }, "description": "Payment links of customer to filter" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "action_required", "under_review", "paid", "failed", "cancelled", "expired" ] }, "description": "Return only payment links in this status. Uses the same values as the payment link's `status` field.\n" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of payment links matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLinkResponse" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message.\n", "example": "Invalid customer_id" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/payin/{id}": { "get": { "tags": [ "payment_link" ], "summary": "Retrieve a payment link", "description": "Retrieve details of a payment link.\n", "operationId": "getPayinById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the payment link. Starts with `plink_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `plink_`; a well-formed ID that doesn't match a payment link on your account returns `404`.\n", "example": "plink_678a4c88hpAjf" } ], "responses": { "200": { "description": "Payment link retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "404": { "description": "Payment link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] }, "patch": { "tags": [ "payment_link" ], "summary": "Update an existing payment link", "description": "Extends or reschedules a payment link that is still live. Only `expires_at` and `reminder_frequency`\ncan be changed — no other field on a payment link is editable, and the amount, currency and customer\nare fixed at creation.\n\nThe link must not have reached a terminal state. A payin that is `success`, `failed`, `cancelled`,\n`expired` or `rejected` cannot be updated and the call returns `400` with the message\n`Payin cannot be updated from current state`. Use this to give a customer more time rather than\ncancelling and re-issuing the link, which would change the URL your customer already has.\n", "operationId": "updatePayin", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the payment link to update.", "schema": { "type": "string", "example": "plink_678a4c88hpAjf" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reminder_frequency": { "type": "number", "description": "The frequency at which you want to remind customers, valid values are 1 (remind every day), 2 (remind every alternate day), 7 (remind every week), 14 (remind every alternate week).\n", "example": 1 }, "expires_at": { "type": "string", "format": "date-time", "description": "The new expiry for the payin. Send an ISO 8601 date-time with a UTC offset or `Z` (`YYYY-MM-DDThh:mm:ssZ`). A value without an offset is read as UTC, and a date without a time is read as 00:00 UTC on that day. Must be later than the time of the request and at most 6 calendar months after the payin was created. A past value returns `400` with the message `Validation failed: Expires at must be in the future`. A value more than 6 months from now returns `400` with `Validation failed: Expires at cannot be more than 6 months from now`, and one within that but more than 6 months after creation returns `400` with `Validation failed: Expiry date must be in the future and within 6 months`. Send at least one of `expires_at` or `reminder_frequency`.\n", "example": "2026-12-15T12:00:00Z", "x-glomo-relative-example": "P14D" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Payment link updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "Bad request" }, "404": { "description": "Payment link not found" } }, "security": [ { "JWT": [] } ] } }, "/payin/{id}/cancel": { "patch": { "tags": [ "payment_link" ], "summary": "Cancel a payment link", "description": "Invalidate payment link and prevent further transactions\n", "operationId": "cancelPayin", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the payment link to cancel. Starts with `plink_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `plink_`; a well-formed ID that doesn't match a payment link on your account returns `404`.\n", "example": "plink_678a4c88hpAjf" } ], "responses": { "200": { "description": "Payment link canceled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "404": { "description": "Payment link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/payin/{id}/update-rfi": { "patch": { "tags": [ "payment_link" ], "summary": "Update RFI documents for a payment link", "description": "Updates the RFI (Request for Information) document status for a payment link. This endpoint is used to submit required documents when a payment link is in 'action_required' status due to sanction screening.\n", "operationId": "updatePayinRfi", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the payment link to update RFI for", "example": "plink_678a4c88hpAjf" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "description": "Array of documents to be submitted for RFI requirements", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the document being uploaded for this RFI requirement\n", "example": "doc_67fc2f42468Bw" }, "rfi_doc_id": { "type": "string", "description": "The unique identifier of the RFI document being submitted\n", "example": "rfidoc_68c8dffedhMHD" } }, "required": [ "id", "rfi_doc_id" ], "additionalProperties": false } } }, "required": [ "documents" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "RFI document updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "Invalid rfi_doc_id or payment link not in action_required status" } } } } } }, "404": { "description": "Payment link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/payin/{id}/mock_mark_reviewed": { "patch": { "tags": [ "payment_link" ], "summary": "Mock review a payment link", "description": "Mark an under_review payment link reviewed\n", "operationId": "mockReviewPaymentLink", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the payment link to review. Starts with `plink_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `plink_`; a well-formed ID that doesn't match a payment link on your account returns `404`.\n", "example": "plink_E602dMzgjpDC" } ], "responses": { "200": { "description": "Payment link successfully marked reviewed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message.\n", "example": "Payment link is not under review." } } } } } }, "404": { "description": "Payment link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/payouts": { "post": { "tags": [ "Payout" ], "summary": "Create a new payout", "operationId": "createPayout", "description": "Create a payout in one of two ways:\n- **Payout without quote** — specify the beneficiary, currencies and amount inline. Fees and the FX\n rate are determined at creation time (`CreatePayoutWithoutQuoteRequest`).\n\n- **Payout with quote** — pass a `quote_id` from `POST /quotes` (with `resource: payout`) to settle\n against a locked rate and fee breakdown. The currencies, amount and payment rail are derived from\n the quote and must not be sent (`CreatePayoutWithQuoteRequest`).\n\nThe request variant is selected by the presence of `quote_id`.\nIf payout queueing is enabled on your account, every payout is accepted with `status: queued`, including one that the balance in the source currency already covers, and a payout the balance does not cover is accepted instead of rejected. Glomo releases it automatically once the balance covers the amount plus fees. Fees and the FX rate are fixed at creation and honoured when the payout is released. Without payout queueing, a short balance is rejected at creation.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreatePayoutWithoutQuoteRequest", "required": [ "purpose_code", "beneficiary_id", "source_currency", "destination_currency" ] }, { "$ref": "#/components/schemas/CreatePayoutWithQuoteRequest", "required": [ "quote_id", "beneficiary_id", "purpose_code" ] } ] }, "examples": { "payout_without_quote": { "summary": "Payout without quote (no quote_id)", "value": { "purpose_code": "S0802", "beneficiary_id": "bene_a1b2c3d4e5", "source_currency": "USD", "destination_currency": "INR", "source_amount": 100000, "payment_rail": "neft", "invoice_number": "INV-2026-001", "request_id": "req-7f3a9c20", "documents": [ "doc_11aa22bb33" ], "notes": { "internal_ref": "batch-42" } } }, "payout_with_quote": { "summary": "Payout with quote (quote_id present)", "value": { "quote_id": "quote_3m4n5o6p7q", "beneficiary_id": "bene_a1b2c3d4e5", "purpose_code": "S0802", "invoice_number": "INV-2026-001", "request_id": "req-7f3a9c20", "documents": [ "doc_11aa22bb33" ], "notes": { "internal_ref": "batch-42" } } } } } } }, "responses": { "201": { "description": "Payout created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "description": "Bad Request — validation error. For quote-based payouts, possible messages include `quote_id not found`, `quote_id has expired`, `quote_id has already been used`, `source_amount cannot be specified when quote_id is present` (likewise for any other quote-derived field), `Quote is not compatible with the selected beneficiary` (the quote's rail is not supported by the chosen beneficiary), and `Quote is not a payout quote` (the `quote_id` belongs to a payin quote).\nWhen the balance does not cover the payout and payout queueing is not enabled on your account, the message reads `Account has insufficient balance to process this transaction. Additional amount required: N.` where `N` is the shortfall, in the smallest unit of the source currency.\n", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "A payout with this `request_id` already exists on your account. The existing payout is not returned; look it up with `GET /v1/payouts?request_id=`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "Record already exists" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Payout" ], "summary": "List all payouts", "description": "Returns a list of your payouts, sorted by creation date with the most recent first. Filters combine\nwith AND, so a `status` and a `beneficiary_id` together return only payouts matching both.\n\nPayouts in `draft` are excluded unconditionally, whatever you filter on; `GET /payouts/{id}` returns\nthem. Creating a payout through this API submits it in the same call, so a payout of your own should\nnot be sitting in `draft`.\n\nOnly beneficiary payouts are returned. A settlement ID will not appear in this list — retrieve those\nfrom `GET /settlements`.\n", "operationId": "getPayouts", "parameters": [ { "in": "query", "name": "beneficiary_id", "schema": { "type": "string" }, "description": "The unique identifier of the beneficiary", "example": "bene_5JU9yv0lGSUP" }, { "in": "query", "name": "request_id", "schema": { "type": "string" }, "description": "Filter payouts by the client-provided `request_id`. Returns at most one result.", "example": "your-internal-id" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "pending_approval", "queued", "in_progress", "success", "failed", "action_required", "cancelled" ] }, "description": "Status of payout to filter" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of payouts matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "JWT": [] } ] } }, "/payouts/{id}": { "get": { "tags": [ "Payout" ], "summary": "Retrieve a payout\n", "description": "Retrieves a single payout by ID.\n\nUnlike `GET /payouts`, this returns a payout in any state, including one still in draft that the\nlist endpoint hides. The payout must belong to the merchant the API key authenticates as — an ID\nthat exists but belongs to another merchant returns `404`, not `403`, so the response does not\nreveal whether the ID exists. An ID that is not a well-formed payout ID is rejected with `400`\nbefore any lookup happens.\n", "operationId": "getPayoutById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the payout. Starts with `payout_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `payout_`; a well-formed ID that doesn't match a payout on your account returns `404`.\n", "example": "payout_E602dMzgjpDC" } ], "responses": { "200": { "description": "Payout found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "404": { "description": "Payout not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } } } }, "/payouts/{id}/cancel": { "patch": { "tags": [ "Payout" ], "summary": "Cancel a payout", "operationId": "cancelPayout", "description": "Cancel a payout that has not yet reached a stage where it can no longer be stopped. A payout with `status: queued` can be cancelled at any time while it waits for the balance to cover it. Nothing is reversed, because no funds were held.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the payout to cancel. Starts with `payout_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `payout_`; a well-formed ID that doesn't match a payout on your account returns `404`.\n", "schema": { "type": "string", "example": "payout_DdWpHUbOnlg" } } ], "responses": { "200": { "description": "Payout cancelled successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Payout" }, { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the payout.\n", "example": "cancelled" } } } ] } } } }, "400": { "description": "Bad request" }, "404": { "description": "Payout not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/quotes": { "post": { "tags": [ "Quote" ], "summary": "Create quotes", "operationId": "createQuote", "description": "Create one or more pricing quotes for a `payout` or `payin`. Each quote locks an exchange rate and fee breakdown for fixed period.\nProvide exactly one of `source_amount` or `destination_amount`.\n\nOn a payin quote, pass `split_ids` to price the fee from your declared share of a dynamic pricing rule. See [Dynamic Fee Split](#tag/pricing_split). A payment link or an order created from the quote inherits the quote's splits, so it must not send `split_ids` of its own. `split_ids` is rejected on a payout quote.\n\nAn **account funding** quote is a payin quote with `payment_method.type: card` and `resource_type: account_funding`. It takes no subtype, prices in the destination currency, and is the only quote an account funding order can be created from. See [Add funds with a card](/payin/account-funding).\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" }, "examples": { "payout_source_amount": { "summary": "Payout quote using source_amount", "value": { "resource": "payout", "source_currency": "USD", "destination_currency": "INR", "source_amount": 10000, "payment_method": { "type": "bank_transfer", "subtype": "swift_transfer" } } }, "payout_destination_amount": { "summary": "Payout quote using destination_amount", "value": { "resource": "payout", "source_currency": "USD", "destination_currency": "INR", "destination_amount": 882000, "payment_method": { "type": "bank_transfer", "subtype": "local_transfer" } } }, "payin_quote": { "summary": "Payin quote with referral price", "value": { "resource": "payin", "source_currency": "USD", "destination_currency": "INR", "source_amount": 10000, "payment_method": { "type": "bank_transfer", "subtype": "swift_transfer" }, "price_id": "price_5JU9yv0lGSUP" } }, "payin_quote_with_splits": { "summary": "Payin quote priced from a declared dynamic fee split", "value": { "resource": "payin", "source_currency": "USD", "destination_currency": "INR", "source_amount": 10000, "payment_method": { "type": "bank_transfer", "subtype": "swift_transfer" }, "split_ids": [ "psplit_7Kq2mXbTdLp9" ] } }, "account_funding_quote": { "summary": "Account funding quote paid by card", "value": { "resource": "payin", "resource_type": "account_funding", "source_currency": "AED", "destination_currency": "USD", "destination_amount": 100000, "payment_method": { "type": "card" } } } } } } }, "responses": { "201": { "description": "Quotes created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } } } } } } }, "400": { "description": "Bad Request - missing required parameters, both amounts specified, neither amount specified, invalid currency, an unsupported payment method or subtype, `local_transfer` with a non-INR destination, `pay_via_bank` with a subtype other than `local_transfer`, a subtype sent with `card`, a card payin quote without `resource_type`, `resource_type` on a non-payin quote, `split_ids` on a non-payin quote, an unresolvable `split_ids` entry, or no available pricing options.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Either source_amount or destination_amount must be provided, not both" } } }, "examples": { "both_amounts": { "summary": "Both amounts specified", "value": { "error": "Bad Request", "message": "Either source_amount or destination_amount must be provided, not both" } }, "missing_payment_method": { "summary": "payment_method object missing", "value": { "error": "Bad Request", "message": "payment_method is required" } }, "missing_type": { "summary": "payment_method.type missing", "value": { "error": "Bad Request", "message": "payment_method.type is required" } }, "missing_subtype": { "summary": "payment_method.subtype missing on a method that requires one", "value": { "error": "Bad Request", "message": "payment_method.subtype is required" } }, "subtype_on_card": { "summary": "A subtype sent with card, which takes none", "value": { "error": "Bad Request", "message": "payment_method.subtype is not supported for card" } }, "unsupported_payment_method": { "summary": "Unsupported payment method", "value": { "error": "Bad Request", "message": "'wallet' is not a supported payment method" } }, "card_on_payout_quote": { "summary": "A payin-only method sent on a payout quote", "value": { "error": "Bad Request", "message": "card is only supported for payin quotes" } }, "resource_type_required": { "summary": "Card payin quote without resource_type", "value": { "error": "Bad Request", "message": "Validation failed: resource_type_required" } }, "resource_type_on_payout": { "summary": "resource_type sent on a payout quote", "value": { "error": "Bad Request", "message": "resource_type is only valid for payin quotes" } }, "unsupported_subtype": { "summary": "Unsupported subtype", "value": { "error": "Bad Request", "message": "'instant_transfer' is not a supported subtype" } }, "local_transfer_non_inr": { "summary": "local_transfer to a non-INR destination", "value": { "error": "Bad Request", "message": "local_transfer is only supported for INR destination" } }, "pay_via_bank_subtype": { "summary": "pay_via_bank with an unsupported subtype", "value": { "error": "Bad Request", "message": "pay_via_bank only supports the local_transfer subtype" } }, "split_ids_on_payout_quote": { "summary": "split_ids sent on a payout quote", "value": { "error": "Bad Request", "message": "Validation failed: split_ids is only valid for payin quotes" } }, "split_ids_unresolved": { "summary": "A split id does not resolve to a live dynamic rule", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are invalid or no longer point at a dynamic rule: psplit_7Kq2mXbTdLp9" } }, "split_ids_incomplete": { "summary": "Another dynamic rule on the same dimension is not declared", "value": { "error": "Bad Request", "message": "Validation failed: Split ids must be declared for every dynamic rule on the dimension, missing rules: price_Kd82nvQ1TzAe" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/lrs/quotes": { "post": { "tags": [ "lrs" ], "summary": "Create an LRS quote", "description": "Creates a quote for an LRS remittance (`resource: payin`) or an LRS withdrawal (`resource: payout`). Use it to show the customer the exchange rate, the GST and the converted amount before they proceed. Payout quotes expire 30 minutes after they are created; for a payin quote, rely on the returned `expires_at`.\n\nThis is not the same endpoint as `POST /quotes` (`createQuote`). To create an LRS order, pass the payin quote's `id` as `lrs.lrs_quote_id` on `POST /orders`, with `currency` set to `USD` and `amount` equal to the `USD` side of the quote: `from.amount` when `source_currency` is `USD`, `to.amount` when it is `INR`.\n\nFor a payin quote, `bank_code` is required and must be a bank enabled for your account (see `GET /lrs/banks`). Either direction between `INR` and `USD` is supported. For a payout quote, only `USD` to `INR` is supported and `bank_code` must not be sent. LRS must be enabled for your account.\n", "operationId": "createLrsQuote", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLrsQuoteRequest" }, "examples": { "payin_inr_to_usd": { "summary": "Payin quote from INR to USD", "value": { "bank_code": "hdfc", "source_amount": 4400000, "source_currency": "INR", "target_currency": "USD" } }, "payout_usd_to_inr": { "summary": "Payout quote from USD to INR", "value": { "resource": "payout", "source_amount": 1000000, "source_currency": "USD", "target_currency": "INR" } } } } } }, "responses": { "201": { "description": "Quote created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LrsQuote" }, "examples": { "payin_inr_to_usd": { "summary": "Payin quote from INR to USD", "value": { "id": "quote_6ab60de4Kx7Pq", "from": { "amount": 4400000, "currency": "INR" }, "to": { "amount": 51763, "currency": "USD" }, "fx_rate": "84.85", "bank_code": "hdfc", "total_tax": 7906, "expires_at": "2026-09-25T06:30:04.113Z", "created_at": "2026-09-25T06:00:04.113Z" } }, "payout_usd_to_inr": { "summary": "Payout quote from USD to INR", "value": { "id": "quote_6ab4e690Rt3Vm", "from": { "amount": 1000000, "currency": "USD" }, "to": { "amount": 93953000, "currency": "INR" }, "fx_rate": "94.0", "total_tax": 47000, "expires_at": "2026-09-24T09:30:00.412Z", "created_at": "2026-09-24T09:00:00.412Z" } } } } } }, "400": { "description": "Bad Request — a required field is missing, a currency is not `INR` or `USD`, both currencies are the same, `source_amount` is not a whole number, `bank_code` is missing on a payin quote or is not enabled for your account, `bank_code` is sent on a payout quote, a payout quote is not `USD` to `INR`, the amount on a payin quote is outside the bank's limits, the converted amount on a payout quote is outside the range a payout can be sent for, or LRS is not enabled for your account.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Validation failed: Bank code can't be blank" } } }, "examples": { "bank_code_missing": { "summary": "bank_code missing on a payin quote", "value": { "error": "Bad Request", "message": "Validation failed: Bank code can't be blank" } }, "bank_code_not_enabled": { "summary": "Bank not enabled for your account", "value": { "error": "Bad Request", "message": "Validation failed: Bank code icici is not enabled for your business" } }, "currency_not_supported": { "summary": "Currency other than INR or USD", "value": { "error": "Bad Request", "message": "Validation failed: Source currency is not supported" } }, "same_currency": { "summary": "source_currency equals target_currency", "value": { "error": "Bad Request", "message": "Validation failed: source_currency and target_currency cannot be the same" } }, "amount_not_integer": { "summary": "source_amount is not a whole number", "value": { "error": "Bad Request", "message": "Validation failed: Source amount must be an integer" } }, "below_minimum": { "summary": "Amount below the bank's minimum", "value": { "error": "Bad Request", "message": "Amount 100.00 INR is below minimum limit. (Minimum limit is 10.00 USD)" } }, "above_maximum": { "summary": "Amount above the bank's maximum", "value": { "error": "Bad Request", "message": "Amount 5,000,000.00 INR exceeds maximum limit. (Maximum limit is 50,000.00 USD)" } }, "bank_code_on_payout": { "summary": "bank_code sent on a payout quote", "value": { "error": "Bad Request", "message": "Validation failed: Bank code is not supported for payout quotes" } }, "payout_corridor": { "summary": "Payout quote other than USD to INR", "value": { "error": "Bad Request", "message": "Validation failed: payout quotes are only supported from USD to INR" } }, "payout_no_options": { "summary": "Payout amount outside the range a payout can be sent for", "value": { "error": "Bad Request", "message": "No available options for this amount" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } }, "422": { "description": "Unprocessable Entity — no exchange rate is available for the bank right now.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unprocessable Entity" }, "message": { "type": "string", "example": "No active exchange rate found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/lrs/quotes/{id}": { "get": { "tags": [ "lrs" ], "summary": "Retrieve an LRS quote", "description": "Returns any quote on your account by ID. Quotes created with `POST /quotes` also resolve here, in this shape. Use `expires_at` to check whether an LRS quote can still be used for an LRS order.\n", "operationId": "getLrsQuoteById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the quote", "example": "quote_6ab60de4Kx7Pq" } ], "responses": { "200": { "description": "Quote retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LrsQuote" }, "example": { "id": "quote_6ab60de4Kx7Pq", "from": { "amount": 4400000, "currency": "INR" }, "to": { "amount": 51763, "currency": "USD" }, "fx_rate": "84.85", "bank_code": "hdfc", "total_tax": 7906, "expires_at": "2026-09-25T06:30:04.113Z", "created_at": "2026-09-25T06:00:04.113Z" } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } }, "404": { "description": "Not Found — no quote with this ID exists on your account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Quote not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/lrs/banks": { "get": { "tags": [ "lrs" ], "summary": "List LRS banks", "description": "Returns the banks your customers can remit from under LRS. Only banks enabled for your account are listed, so the list can be empty. Use a `bank_code` from this list when you register a customer's LRS bank account and when you create an LRS payin quote.\n", "operationId": "getLrsBanks", "responses": { "200": { "description": "Banks enabled for LRS on your account", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LrsBank" } }, "example": [ { "bank_code": "hdfc", "bank_name": "HDFC bank" }, { "bank_code": "axis", "bank_name": "Axis bank" } ] } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/payouts/mock": { "patch": { "tags": [ "Payout" ], "summary": "Mock update a payout status", "description": "Drives one of your payouts to a chosen status without any real money moving, so you can exercise your\nwebhook handling and reconciliation against statuses that are otherwise hard to reach on demand. The\ntarget must be one of `pending`, `queued`, `success`, `failed`, `action_required` or `cancelled`. This\nendpoint is not available in production.\n\nThe transition must be legal from the payout's current status — the same transition rules apply as in\nproduction, so this cannot force a payout into a state it could not reach for real. An illegal\ntransition returns `400` with `State change not allowed` rather than quietly doing nothing, so that\nerror usually means the payout is not in the state you assumed.\n", "operationId": "mockUpdatePayoutStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MockUpdatePayoutStatusRequest", "required": [ "id", "status" ] } ] } } } }, "responses": { "200": { "description": "Payout updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "JWT": [] } ] } }, "/payment": { "post": { "tags": [ "Payment" ], "summary": "Create a payment", "description": "Creates a payment for an order or subscription. For initial payments, card details and a callback URL are required. For subsequent payments on `as_presented` subscriptions, the card from the last successful payment is reused, and `request_id`, `amount`, and `currency` are required instead.\n\nEither `order_id` or `subscription_id` must be provided, but not both.\n\nOn a `subsequent` auto debit for an `as_presented` subscription, pass `split_ids` to price that charge from your declared share of a dynamic pricing rule. See [Dynamic Fee Split](#tag/pricing_split). The splits apply to that charge only and do not modify the subscription's own declaration. Omit `split_ids` and Glomo prices the charge from the subscription's declaration; if that declaration no longer resolves, the auto debit is rejected with a `400 Bad Request` until you pass a valid `split_ids` to override it.\n", "operationId": "createPayment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }, "examples": { "initial_payment": { "summary": "Initial payment with card details", "value": { "order_id": "order_68c00b7btsthf", "method": "card", "sequence": "initial", "card": { "holder_name": "John Doe", "number": "4111111111111111", "expiry_month": "09", "expiry_year": "30", "cvv": "123" }, "callback_url": "https://server.yoursite.com/payment/callback", "notes": { "internal_ref": "ref_12345" } } }, "subsequent_payment": { "summary": "Subsequent payment for as_presented subscription", "value": { "subscription_id": "sub_5JU9yv0lGSUP", "sequence": "subsequent", "request_id": "unique_request_id_123", "amount": 1500, "currency": "USD" } }, "subsequent_payment_with_splits": { "summary": "Subsequent payment overriding the subscription's fee split for this charge", "value": { "subscription_id": "sub_5JU9yv0lGSUP", "sequence": "subsequent", "request_id": "unique_request_id_124", "amount": 1500, "currency": "USD", "split_ids": [ "psplit_Q3vTn8LcRb2W" ] } } } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentResponse" }, "example": { "payment_id": "payt_691eeb9aV79Uk", "status": "pending", "next_steps": [ { "action": "redirect", "payload": { "url": "https://secure.glomopay.com?paymentId=payt_691eeb9aV79Uk&authToken=ey...&redirectUrl=encoded_url" } }, { "action": "poll", "payload": { "url": "https://api.glomopay.com/api/v1/payment/payt_691eeb9aV79Uk", "interval_in_ms": 5000 } } ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "order_id or subscription_id is required" } } }, "examples": { "missing_order_or_subscription": { "summary": "Missing order_id or subscription_id", "value": { "error": "Bad Request", "message": "order_id or subscription_id is required" } }, "duplicate_request_id": { "summary": "Duplicate request_id", "value": { "error": "Bad Request", "message": "Payment already exists for this request_id" } }, "split_ids_on_fixed_frequency": { "summary": "split_ids sent for a fixed-frequency subscription", "value": { "error": "Bad Request", "message": "split_ids are only supported for as_presented subscriptions" } }, "subscription_declaration_stale": { "summary": "The subscription's own declaration no longer resolves and no override was passed", "value": { "error": "Bad Request", "message": "Declared fee splits on the subscription no longer point at a live dynamic rule: psplit_7Kq2mXbTdLp9. Pass a valid split_id to override." } }, "split_ids_unresolved": { "summary": "A split id does not resolve to a live dynamic rule", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are invalid or no longer point at a dynamic rule: psplit_7Kq2mXbTdLp9" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Payment" ], "summary": "List all payments", "description": "Returns a list of your payments, sorted by creation date with the most recent first.\n\nFilters combine with AND, with one exception: `payin_id` and `subscription_id` are mutually exclusive\nand sending both returns `400`.\n\nThe `status` filter accepts only `in_progress`, `success`, `failed` and `action_required`; any other\nvalue returns `400`. That is not the same set of values a payment can come back with, and the filter\ndoes not map onto the response field one-for-one: a payment returned with `status: under_review` is\nmatched by `status=in_progress`, and some payments returned with `status: in_progress` are not matched\nby `status=in_progress` at all. Treat the filter as a coarse narrowing and read `status` on each\npayment you get back.\n\n`compliance_status` is a separate field with its own filter and moves independently of `status`. Most\npayments have no compliance status at all, so filtering on it will exclude them.\n", "operationId": "getPayments", "parameters": [ { "in": "query", "name": "customer_id", "schema": { "type": "string" }, "description": "The unique identifier for the customer.", "example": "cust_E602sMzgjpDC" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "success", "failed", "action_required", "in_progress" ] }, "example": "success", "description": "Status of payin to filter" }, { "in": "query", "name": "compliance_status", "schema": { "type": "string", "enum": [ "under_review", "action_required", "approved", "rejected" ] }, "description": "Filters payments by the outcome of their compliance review.", "example": "approved" }, { "in": "query", "name": "payin_id", "schema": { "type": "string" }, "description": "The unique identifier for the payin. Accepts a payment link ID (`plink_`), an order ID\n(`order_`) or an Add Balance top-up ID (`addfunds_`). Any other value returns `400`.\n", "example": "plink_E602dMzgjpDC" }, { "in": "query", "name": "payment_type", "schema": { "type": "string", "enum": [ "payment_link", "orders", "add_funds" ] }, "description": "Filters payments by their payin type. Use `add_funds` to list only Add Balance top-ups crediting your Funded Balance.\n", "example": "add_funds" }, { "in": "query", "name": "subscription_id", "schema": { "type": "string" }, "description": "The unique identifier for the subscription.", "example": "sub_68877570b5zeE" }, { "in": "query", "name": "currency", "description": "Filters on the payment's `requested_currency` / `converted_currency` — the currency the merchant asked for, which is also the currency of the order or payment link the payment belongs to. It does not filter on `payment_currency`, the currency the customer was actually charged in. Those two differ whenever local payments are in play: a card payment against a USD order is commonly charged to the customer in AED, and that payment matches `USD`, not `AED`. Matching is case-insensitive.\n", "schema": { "type": "string", "format": "iso-4217", "description": "The currency in which the payment is made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format, case-insensitive. For example, USD.\n" }, "example": "USD" }, { "in": "query", "name": "request_id", "schema": { "type": "string" }, "description": "Return only the payment created with this `request_id`.", "example": "unique_request_id_123" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of payments matching the filters. **Note:** If filters do not match, API will return an empty list.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "JWT": [] } ] } }, "/payment/mock": { "post": { "tags": [ "Payment" ], "summary": "Create a mock payment", "description": "This API is only available in sandbox mode. Sends a mock bank transfer into one of your virtual accounts. See [Test it in sandbox](/payin/payment-methods/bank-transfer/set-up#test-it-in-sandbox).\n", "operationId": "createMockPayment", "security": [ { "JWT": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transfer_type" ], "properties": { "payin_id": { "type": "string", "description": "The order (`order_`) or payment link (`plink_`) that the customer pays. Optional.", "example": "order_678a4c88hpAjf" }, "amount": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "Amount in the smallest unit of the currency. `10000` is 100.00 USD. Required without a `payin_id`.\nWith a `payin_id`, it defaults to the payin's quoted amount. In sandbox, exactly `6623` forces a\nsanctions-screening hit on a matched payment.\n", "example": 10000 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in ISO 4217 format. Required without a `payin_id`. Not allowed with a `payin_id`.\n", "example": "USD" }, "payment_method": { "type": "string", "description": "Optional. Only `BankTransfer` is accepted.", "enum": [ "BankTransfer" ], "example": "BankTransfer" }, "transfer_type": { "type": "string", "enum": [ "local", "swift" ], "description": "The rail of the transfer.", "example": "local" }, "sender": { "type": "object", "description": "The sender of the transfer. Optional, and so is every field. Without a value, a field takes the\npayin customer's detail where one exists, otherwise the placeholder below.\n", "properties": { "name": { "type": "string", "description": "Defaults to the payin's customer name, or `mock sender`.", "example": "John Doe" }, "account_number": { "type": "string", "description": "Account number or IBAN. Defaults to `123456789012`.", "example": "AE070331234567890123456" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 code. Defaults to the payin's customer country, or `USA`.", "example": "ARE" }, "address": { "type": "string", "description": "Defaults to the payin's customer address, or `Mock address for payment`.", "example": "Office 12, Business Bay, Dubai" }, "bic": { "type": "string", "description": "BIC or local bank code. Defaults to a test BIC for the sender's country.", "example": "EBILAEADXXX" }, "external_reference": { "type": "string", "description": "The reference on the transfer. With a `payin_id`, it defaults to the payin's payment reference\n(`GLM` and the last 5 characters of the payin ID). Without a `payin_id`, there is no default.\n", "example": "Invoice 1042 GLMHPAJF" } } } } }, "examples": { "matched_transfer": { "summary": "Mock success for a payin", "value": { "payin_id": "order_678a4c88hpAjf", "transfer_type": "local" } }, "amount_mismatch": { "summary": "Amount mismatch", "value": { "payin_id": "order_678a4c88hpAjf", "transfer_type": "local", "amount": 12000 } }, "unmatched_transfer": { "summary": "Payin not found", "value": { "amount": 10000, "currency": "USD", "transfer_type": "local" } }, "sanctions_hit": { "summary": "Sanctions hit (payin quoted at 6623)", "value": { "payin_id": "order_68f1c1d0sQ4nK", "transfer_type": "local" } } } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "matched_transfer": { "summary": "Mock success for a payin", "value": { "id": "payt_68f1c2a4mK7tQ", "compliance_status": null, "payin_id": "order_678a4c88hpAjf", "payin_type": "orders", "customer_id": "cust_E602dMzgjpDC", "merchant_id": "merch_68c777fcOOMpl", "subscription_id": null, "product_name": null, "product_description": null, "status": "success", "payment_amount": 10000, "payment_currency": "AED", "converted_amount": 10000, "converted_currency": "AED", "requested_amount": 10000, "requested_currency": "AED", "purpose_code": "P1401", "sender_name": "John Doe", "paid_at": "2026-10-14T06:30:00Z", "country": "ARE", "fees": { "txn_fee": { "currency": "AED", "amount": 0 }, "fx_fee": { "currency": "AED", "amount": 0 }, "referral_fee": { "currency": "AED", "amount": 0 } }, "documents": [], "payment_method": { "type": "bank_transfer", "details": { "sender_name": "John Doe", "sender_account_number": "123456789012", "receiver_account_number": "AE070331234567890123456", "sender_country": "ARE", "sender_bank_name": null, "sender_bank_country": null, "sender_bank_address": null, "swift_code": "XKQPAE4T", "local_routing_number": null, "external_reference": "GLMHPAJF", "transfer_type": "local" } }, "fee_bearer": "merchant", "fee_collection_mode": null, "settlement_id": null, "error_code": null, "error_description": null, "customer_error_description": null, "fee_breakdown": { "fx_fee": [], "txn_fee": [], "referral_fee": [] }, "created_at": "2026-10-14T06:30:00Z", "updated_at": "2026-10-14T06:30:00Z", "funds_available": true, "payer_relationship": null, "nre_nro_declaration": null, "notes": {}, "batch_id": null, "request_id": null, "credited_to_beneficiary": false } }, "amount_mismatch": { "summary": "Amount mismatch", "value": { "id": "payt_68f1c2b9pR2wX", "compliance_status": null, "payin_id": "order_678a4c88hpAjf", "payin_type": "orders", "customer_id": "cust_E602dMzgjpDC", "merchant_id": "merch_68c777fcOOMpl", "subscription_id": null, "product_name": null, "product_description": null, "status": "action_required", "payment_amount": 12000, "payment_currency": "AED", "converted_amount": 12000, "converted_currency": "AED", "requested_amount": 12000, "requested_currency": "AED", "purpose_code": "P1401", "sender_name": "John Doe", "paid_at": null, "country": "ARE", "fees": { "txn_fee": { "currency": "AED", "amount": 0 }, "fx_fee": { "currency": "AED", "amount": 0 }, "referral_fee": { "currency": "AED", "amount": 0 } }, "documents": [], "payment_method": { "type": "bank_transfer", "details": { "sender_name": "John Doe", "sender_account_number": "123456789012", "receiver_account_number": "AE070331234567890123456", "sender_country": "ARE", "sender_bank_name": null, "sender_bank_country": null, "sender_bank_address": null, "swift_code": "XKQPAE4T", "local_routing_number": null, "external_reference": "GLMHPAJF", "transfer_type": "local" } }, "fee_bearer": "merchant", "fee_collection_mode": null, "settlement_id": null, "error_code": "PAYIN_AMOUNT_MISMATCH", "error_description": "The received payment amount does not match the order or payment link amount. Please create a new order or payment link for the exact received amount.", "customer_error_description": "The payment amount does not match the expected amount. Please contact the merchant for assistance.", "fee_breakdown": { "fx_fee": [], "txn_fee": [], "referral_fee": [] }, "created_at": "2026-10-14T06:30:00Z", "updated_at": "2026-10-14T06:30:00Z", "funds_available": false, "payer_relationship": null, "nre_nro_declaration": null, "notes": {}, "batch_id": null, "request_id": null, "credited_to_beneficiary": false } }, "unmatched_transfer": { "summary": "Payin not found", "value": { "id": "payt_68f1c2c3hN5vB", "compliance_status": null, "payin_id": null, "payin_type": null, "customer_id": null, "merchant_id": "merch_68c777fcOOMpl", "subscription_id": null, "product_name": null, "product_description": null, "status": "action_required", "payment_amount": 10000, "payment_currency": "USD", "converted_amount": 10000, "converted_currency": "USD", "requested_amount": 10000, "requested_currency": "USD", "purpose_code": null, "sender_name": "mock sender", "paid_at": null, "country": "USA", "fees": { "txn_fee": { "currency": "USD", "amount": 0 }, "fx_fee": { "currency": "USD", "amount": 0 }, "referral_fee": { "currency": "USD", "amount": 0 } }, "documents": [], "payment_method": { "type": "bank_transfer", "details": { "sender_name": "mock sender", "sender_account_number": "123456789012", "receiver_account_number": "AE070331234567890123456", "sender_country": "USA", "sender_bank_name": null, "sender_bank_country": null, "sender_bank_address": null, "swift_code": "MQZTUS7K", "local_routing_number": null, "external_reference": null, "transfer_type": "local" } }, "fee_bearer": "merchant", "fee_collection_mode": null, "settlement_id": null, "error_code": "PAYIN_NOT_FOUND", "error_description": "The incoming payment could not be automatically matched to an existing order or payment link. Please match it manually or create a new order for the received amount.", "customer_error_description": "Your payment could not be matched to an existing order. Please contact the merchant for assistance.", "fee_breakdown": { "fx_fee": [], "txn_fee": [], "referral_fee": [] }, "created_at": "2026-10-14T06:30:00Z", "updated_at": "2026-10-14T06:30:00Z", "funds_available": false, "payer_relationship": null, "nre_nro_declaration": null, "notes": {}, "batch_id": null, "request_id": null, "credited_to_beneficiary": false } }, "sanctions_hit": { "summary": "Sanctions hit", "value": { "id": "payt_68f1c2d8tE6yM", "compliance_status": null, "payin_id": "order_68f1c1d0sQ4nK", "payin_type": "orders", "customer_id": "cust_E602dMzgjpDC", "merchant_id": "merch_68c777fcOOMpl", "subscription_id": null, "product_name": null, "product_description": null, "status": "action_required", "payment_amount": 6623, "payment_currency": "AED", "converted_amount": 6623, "converted_currency": "AED", "requested_amount": 6623, "requested_currency": "AED", "purpose_code": "P1401", "sender_name": "John Doe", "paid_at": null, "country": "ARE", "fees": { "txn_fee": { "currency": "AED", "amount": 0 }, "fx_fee": { "currency": "AED", "amount": 0 }, "referral_fee": { "currency": "AED", "amount": 0 } }, "documents": [], "payment_method": { "type": "bank_transfer", "details": { "sender_name": "John Doe", "sender_account_number": "123456789012", "receiver_account_number": "AE070331234567890123456", "sender_country": "ARE", "sender_bank_name": null, "sender_bank_country": null, "sender_bank_address": null, "swift_code": "XKQPAE4T", "local_routing_number": null, "external_reference": "GLMSQ4NK", "transfer_type": "local" } }, "fee_bearer": "merchant", "fee_collection_mode": null, "settlement_id": null, "error_code": "SANCTION_HIT", "error_description": "This payment requires additional verification. Please contact support for assistance.", "customer_error_description": "This payment requires additional verification. Please contact support for assistance.", "fee_breakdown": { "fx_fee": [], "txn_fee": [], "referral_fee": [] }, "created_at": "2026-10-14T06:30:00Z", "updated_at": "2026-10-14T06:30:00Z", "funds_available": false, "payer_relationship": null, "nre_nro_declaration": null, "notes": {}, "batch_id": null, "request_id": null, "credited_to_beneficiary": false } } } } } }, "400": { "description": "Bad request: a field is invalid or missing, `currency` was sent with a `payin_id`, or there is no virtual\naccount for the transfer (`No active virtual account for this payment`).\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "No active local virtual account for this payment" } } }, "examples": { "currency_with_payin": { "summary": "currency sent with payin_id", "value": { "error": "Bad Request", "message": "Validation failed: Currency can't be sent when payin_id is given" } }, "no_virtual_account": { "summary": "No virtual account for the transfer", "value": { "error": "Bad Request", "message": "No active local virtual account for this payment" } } } } } } } } }, "/payment/{id}": { "get": { "tags": [ "Payment" ], "summary": "Retrieve a payment\n", "description": "Retrieves a single payment by ID. The payment must belong to the merchant the API key authenticates as — an ID that exists but belongs to another merchant returns `404`, not `403`. An ID that is not a well-formed payment ID is rejected with `400` before any lookup happens, so `400` and `404` here mean different things: malformed versus not yours.\n", "operationId": "getPaymentById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the payment. Starts with `payt_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `payt_`; a well-formed ID that doesn't match a payment on your account returns `404`.\n", "example": "payt_E602dMzgjpDC" } ], "responses": { "200": { "description": "Payment found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } } } }, "/payment/{id}/eligible-payins": { "get": { "tags": [ "Payment" ], "summary": "List eligible payins", "description": "Lists the open payment links and orders that an unmatched bank transfer can connect to.\n\nFor the full flow, see [Resolving Action Required Payments](/payin/action-required).\n", "operationId": "getEligiblePayins", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^payt_[a-zA-Z0-9]+$" }, "description": "The unique identifier for the payment. Starts with `payt_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `payt_`; a well-formed ID that doesn't match a payment on your account returns `404`.\n", "example": "payt_6aad0bc0cZtlS" }, { "in": "query", "name": "customer_id", "required": false, "schema": { "type": "string" }, "description": "Returns only the payins of this customer. This is an exact match.\n", "example": "cust_69eb2cf0FYSDF" }, { "in": "query", "name": "reference_number", "required": false, "schema": { "type": "string" }, "description": "Returns only the payins with this reference number. This is an exact match.\n", "example": "RG12FF590" }, { "in": "query", "name": "invoice_number", "required": false, "schema": { "type": "string" }, "description": "Returns only the payins with this invoice number. This is an exact match.\n", "example": "R0001" } ], "responses": { "200": { "description": "The eligible payins for this payment. The endpoint returns a maximum of 10 payins, the newest first. `eligible_payins` is an empty array when no payin matches.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "The unique identifier for the payment.\n", "example": "payt_6aad0bc0cZtlS" }, "payment_amount": { "type": "number", "description": "The amount that the customer sent, in minor units. For example, 10000 is 100.00 AED. The `payment_currency` field gives the currency.\n", "example": 10000 }, "payment_currency": { "type": "string", "format": "iso-4217", "description": "The currency that the customer sent, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "AED" }, "eligible_payins": { "type": "array", "description": "The payins that this payment can connect to. The endpoint returns a maximum of 10 payins, the newest first. The array is empty when no open payin matches the amount and the currency of the payment.\n", "items": { "type": "object", "properties": { "payin_id": { "type": "string", "description": "The unique identifier for the payin. A payment link starts with `plink_`. An order starts with `order_`. An add-funds request starts with `addfunds_`. Send this value as `payin_id` to [Connect a payin](/api-reference/openapi/payment/connectpayin).\n", "example": "plink_6aad0ec19b3bT" }, "payin_status": { "type": "string", "enum": [ "pending" ], "description": "The status of the payin. The endpoint returns only the payins that can still receive a payment.\n", "example": "pending" }, "payin_type": { "type": "string", "enum": [ "payment_link", "orders", "add_funds" ], "description": "The type of the payin.\n", "example": "payment_link" }, "amount": { "type": "number", "description": "The amount that the payin expects, in minor units. For example, 2723 is $27.23. The `currency` field gives the currency.\n", "example": 2723 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency of the payin, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "USD" }, "customer_id": { "type": "string", "description": "The unique identifier for the customer of this payin.\n", "example": "cust_69eb2cf0FYSDF" }, "invoice_number": { "type": [ "string", "null" ], "description": "The invoice number of the payin. The value is `null` when the payin has no invoice number.\n", "example": "R0001" }, "reference_number": { "type": [ "string", "null" ], "description": "The reference number of the payin. The value is `null` when the payin has no reference number.\n", "example": "RG12FF590" }, "created_at": { "type": "string", "format": "date-time", "description": "The creation timestamp of the payin, in UTC.\n", "example": "2026-09-18T10:38:19.237Z" } } } } } }, "examples": { "eligible": { "summary": "One eligible payin", "value": { "payment_id": "payt_6aad0bc0cZtlS", "payment_amount": 10000, "payment_currency": "AED", "eligible_payins": [ { "payin_id": "plink_6aad0ec19b3bT", "payin_status": "pending", "payin_type": "payment_link", "amount": 2723, "currency": "USD", "customer_id": "cust_69eb2cf0FYSDF", "invoice_number": "R0001", "reference_number": "RG12FF590", "created_at": "2026-09-18T10:38:19.237Z" } ] } }, "none": { "summary": "No eligible payin", "value": { "payment_id": "payt_6aad0bc0cZtlS", "payment_amount": 10000, "payment_currency": "AED", "eligible_payins": [] } } } } } }, "400": { "description": "Bad request. The payment identifier is not valid, or the payment cannot connect to a payin.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n\n**Possible messages:**\n\n- `Id must start with 'payt_' and contain only alphanumeric characters` - the `id` path parameter is not valid.\n- `Payment is not in correct state to link a payin` - the payment is not in the `action_required` state.\n- `Payment already belongs to a payin that is not in pending state` - the payin that the payment points at is no longer pending.\n- `Only applicable for bank transfers` - the `payment_method.type` of the payment is not `bank_transfer`.\n- The merchant description of an `error_code` that you cannot resolve by a connect, such as `SANCTION_HIT` or `TXM_HOLD`. An example is `This payment requires additional verification. Please contact support for assistance.` Contact support for these payments.\n", "example": "Payment is not in correct state to link a payin" } } } } } }, "401": { "description": "Unauthorized. The bearer token is absent or not valid." }, "404": { "description": "Glomo did not find the payment. This message also applies to a payment of a different business.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "enum": [ "Payment not found" ] } } } } } } } } }, "/payment/{id}/connect-payin": { "post": { "tags": [ "Payment" ], "summary": "Connect a payin", "description": "Connects an unmatched bank transfer to one of your open payment links or orders. Find the payin first with [List eligible payins](/api-reference/openapi/payment/geteligiblepayins).\n\nFor the full flow, see [Resolving Action Required Payments](/payin/action-required).\n", "operationId": "connectPayin", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^payt_[a-zA-Z0-9]+$" }, "description": "The unique identifier for the payment. Starts with `payt_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `payt_`; a well-formed ID that doesn't match a payment on your account returns `404`.\n", "example": "payt_6aad0bc0cZtlS" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payin_id": { "type": "string", "description": "The unique identifier of the payin to connect. Take this value from the `eligible_payins` list. A payment link starts with `plink_`. An order starts with `order_`. An add-funds request starts with `addfunds_`. The payin must be a payin of your business. Its status must be `pending`.\n", "example": "plink_6aad0ec19b3bT" } }, "required": [ "payin_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Glomo connected the payin. The body is the payment object. It has the same shape as [Retrieve a payment](/api-reference/openapi/payment/getpaymentbyid). Read `status`, `payin_id`, `payin_type`, `converted_amount`, `converted_currency` and `fee_breakdown`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "payt_6aad0bc0cZtlS", "payin_id": "plink_6aad0ec19b3bT", "payin_type": "payment_link", "status": "success", "payment_currency": "AED", "payment_amount": 10000, "converted_currency": "USD", "converted_amount": 2723, "sender_name": "John Doe", "paid_at": "2026-09-18T10:41:02.118Z", "created_at": "2026-09-18T10:38:19.237Z", "updated_at": "2026-09-18T10:41:02.118Z", "customer_id": "cust_69eb2cf0FYSDF", "merchant_id": "merch_68c777fcOOMpl", "fee_bearer": "merchant", "payment_method": { "type": "bank_transfer", "details": { "sender_name": "John Doe", "sender_account_number": "5454545454", "receiver_account_number": "98765432109876", "sender_country": "ARE", "sender_bank_name": "EMIRATES NBD BANK PJSC", "sender_bank_country": "ARE", "swift_code": "EBILAEAD", "local_routing_number": null, "external_reference": "GLM7A2C1", "transfer_type": "swift" } } } } } }, "400": { "description": "Bad request. The payment identifier is not valid, the payment cannot connect to a payin, or the payin cannot receive a payment.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n\n**Possible messages:**\n\n- `Id must start with 'payt_' and contain only alphanumeric characters` - the `id` path parameter is not valid.\n- `Payment is not in correct state to link a payin` - the payment is not in the `action_required` state.\n- `Payment already belongs to a payin that is not in pending state` - the payin that the payment points at is no longer pending.\n- `The payin to be linked to the given payment is in an invalid state` - the payin is not `pending`. It can be expired or cancelled.\n- The merchant description of an `error_code` that you cannot resolve by a connect, such as `SANCTION_HIT` or `TXM_HOLD`. An example is `This payment requires additional verification. Please contact support for assistance.` Contact support for these payments.\n", "example": "The payin to be linked to the given payment is in an invalid state" } } } } } }, "401": { "description": "Unauthorized. The bearer token is absent or not valid." }, "404": { "description": "Glomo did not find the payment or the payin. This message also applies to a resource of a different business, and to a `payin_id` that is absent or unknown.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "description": "Error message.\n\n**Possible messages:**\n\n- `Payment not found`\n- `Payin not found`\n", "example": "Payin not found" } } } } } } } } }, "/payment/{id}/mock-funds-available": { "patch": { "tags": [ "Payment" ], "summary": "Mock funds available", "description": "This API is only available in sandbox mode. Updates the funds_available status of a payment to simulate the availability of funds for testing purposes.\n", "operationId": "mockUpdatePaymentFundsAvailable", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the payment to mark funds as available for. The payment must already be in `success` status, must not have direct settlement enabled, and must have a transaction recorded against it; otherwise the call is rejected with `400`. If funds are already available the call is a no-op and returns `200`.\n", "schema": { "type": "string", "description": "The unique identifier for the payment.", "example": "payt_E602dMzgjpDC" } } ], "security": [ { "JWT": [] } ], "responses": { "200": { "description": "Payment funds available status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Payment" }, "message": { "type": "string", "description": "Success message", "example": "Payment funds available status updated successfully" } } } } } }, "400": { "description": "Bad Request - Payment validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "The specific validation error message indicating why the mock funds available operation failed.\n\n**Possible Error Messages:**\n\n- **Payment Status Error:** `Payment must be in success status`\n- **Settlement Error:** `Payment must not have direct settlement enabled`\n- **Transaction Error:** `No transaction found for payment`\n", "example": "Payment must be in success status" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "404": { "description": "Not Found - Payment with the specified ID not found" } } } }, "/refunds": { "post": { "tags": [ "Refund" ], "summary": "Create refund for a payment", "description": "Creates refund for a payment entity if the payment is in success state and no other refund exists.\n", "operationId": "createRefund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "Requested By Customer", "Duplicate", "Fraudulent", "Others" ], "description": "The reason for the refund. Send one of the listed values exactly as written: the match is case-sensitive and includes the spaces, so `Requested By Customer` is accepted and `requested_by_customer` or `Requested by customer` is rejected with a `400`.\n" }, "payment_id": { "type": "string", "description": "The unique identifier of payment linked to refund.\n", "example": "payt_E602dMzgjpDC" }, "document_id": { "type": "string", "description": "The id of document that is uploaded for refund.\n", "example": "doc_E602dMd2adDC" }, "document_url": { "type": "string", "description": "The url of document that is uploaded for refund.\n", "example": "https://www.example.com/documents/invoice.pdf" }, "file_name": { "type": "string", "description": "The name of document that is uploaded for refund.\n", "example": "invoice" }, "amount": { "type": "integer", "description": "The amount to refund, in the smallest unit of the payment's `converted_currency`, the merchant-side currency (cents for USD), or the currency received for a bank transfer not yet matched to a payin. `1000` is $10.00 when that currency is USD. Required for partial refunds. If not provided, the full payment amount will be refunded. If partial refunds are not enabled on your account, an amount below the payment's `converted_amount` is rejected with `400` and the message `Partial refunds are not enabled for this business`, and an amount equal to or greater than it refunds the full payment. The refund returns its own `amount` in the refund's `currency`, which can differ from this one.\n", "example": 1000 }, "request_id": { "type": "string", "description": "Your unique identifier for this refund, used to reject duplicates. If a refund with the same `request_id` already exists on your account, the request is rejected with `400` and the message `Refund already exists for this request_id`, unless the payment first fails another refund check (for example, it's already fully refunded). The existing refund is not returned. Look it up with `GET /v1/refunds?request_id=`.\n", "example": "unique_refund_request_id_123" } }, "required": [ "payment_id", "reason" ] } } } }, "responses": { "201": { "description": "Refund created successfully", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/Refund" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message.\n", "example": "Refund is already in progress." } } }, "examples": { "refund_in_progress": { "summary": "Refund already in progress", "value": { "message": "Refund is already in progress." } }, "duplicate_request_id": { "summary": "Duplicate request_id", "value": { "error": "Bad Request", "message": "Refund already exists for this request_id" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Refund" ], "summary": "List all refunds", "description": "Returns a list of refunds in response. The refunds are returned sorted by creation date, with the most recent refund appearing first.\n", "operationId": "getRefunds", "parameters": [ { "in": "query", "name": "customer_id", "schema": { "type": "string" }, "description": "Refunds of customer to filter" }, { "in": "query", "name": "payment_method", "schema": { "type": "string" }, "description": "Refunds of payment_methods to filter" }, { "in": "query", "name": "payment_id", "schema": { "type": "string" }, "description": "Refunds of payment_id to filter" }, { "in": "query", "name": "request_id", "schema": { "type": "string" }, "description": "Return only the refund created with this `request_id`.", "example": "unique_refund_request_id_123" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "in_progress", "under_review", "action_required", "success", "failed", "cancelled" ] }, "description": "Return only refunds in this status. Uses the same values as the refund's `status` field." }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of Refunds matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "JWT": [] } ] } }, "/refunds/{id}": { "get": { "tags": [ "Refund" ], "summary": "Retrieve a refund\n", "description": "Retrieves a single refund by ID, including its current status.\n\nA failed refund carries `error_code` and `error_message`, but these are not yet the specific reason\nrecorded against the refund — every failure currently reports the same generic bank-failure value.\nDo not branch on them.\n\nThe refund must belong to the merchant the API key authenticates as — an ID that exists but belongs\nto another merchant returns `404`, not `403`. An ID that is not a well-formed refund ID is rejected\nwith `400` before any lookup happens.\n", "operationId": "getRefundById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the refund. Starts with `refund_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `refund_`; a well-formed ID that doesn't match a refund on your account returns `404`.\n", "example": "refund_E602dMzgjpDC" } ], "responses": { "200": { "description": "Refund found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "404": { "description": "Refund not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } } } }, "/refunds/{id}/mock_update_status": { "patch": { "tags": [ "Refund" ], "summary": "Mock update a refund", "description": "Sandbox only. Moves a refund to `success` or `failed` so you can test how your integration handles each outcome.\n", "operationId": "mockUpdateRefund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the refund. Starts with `refund_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `refund_`; a well-formed ID that doesn't match a refund on your account returns `404`.\n", "example": "refund_E602dMzgjpDC" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "failed" ], "description": "The status to move the refund to.\n\n- `success` — completes a refund that is `in_progress`.\n- `failed` — fails a refund that has not yet reached a terminal status.\n", "example": "success" } } } } } }, "responses": { "200": { "description": "Refund updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message.\n", "example": "Refund cannot be marked success." } } } } } }, "404": { "description": "Refund not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/prices": { "post": { "tags": [ "Price" ], "summary": "Create a new price", "description": "Creates a price governing the referral fee applied to payins, which you then attach to a payin or an\norder by passing its ID as `price_id`. The fee it produces is returned as `referral_fee` on the\npayment and in a quote's `fees` breakdown.\n\nEvery price created here governs the referral fee — there is no fee type to choose, which is why the\nPrice object carries no `fee_type` field. `GET /prices` lists these and only these.\n\n`pricing_type` selects the shape of the rule and which other fields are permitted — sending a field\nbelonging to the other shape is rejected rather than ignored:\n\n- `fixed` requires `fees_amount` and `fees_currency`, and must not include `bps`.\n\n- `percentage` requires `bps`, and must not include `fees_amount` or `fees_currency`.\n\nThe first referral-fee price you create becomes your default automatically, whether or not you send\n`set_as_default`. After that, sending `set_as_default: true` promotes this price and demotes the\nprevious default — a business has at most one default referral-fee price at a time. The default is\nwhat applies when a payin does not name a `price_id`.\n", "operationId": "createPrice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Price" }, { "type": "object", "oneOf": [ { "properties": { "pricing_type": { "enum": [ "fixed" ] }, "fees_currency": { "type": "string" }, "fees_amount": { "type": "number" } }, "required": [ "pricing_type", "fees_currency", "fees_amount" ] }, { "properties": { "pricing_type": { "enum": [ "percentage" ] }, "bps": { "type": "number" } }, "required": [ "pricing_type", "bps" ] } ] } ] } } } }, "responses": { "201": { "description": "Payout created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Price" ], "summary": "List all prices", "description": "Returns the referral-fee prices configured for your business, sorted by creation date with the most\nrecent first.\n\nOnly referral fees are returned. Glomo's other pricing — transaction fees, FX fees — is not exposed\nthrough this endpoint and cannot be filtered in, so an empty list means you have configured no\nreferral fees, not that your account has no pricing.\n\nAvailable to a platform business and to a business hosted by a platform. Any other merchant is\nrejected with `401`.\n", "operationId": "getPrices", "parameters": [ { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of prices matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "JWT": [] } ] } }, "/prices/dynamic": { "get": { "tags": [ "pricing_split" ], "summary": "List dynamic pricing rules", "description": "Returns the payin pricing rules configured for your business whose fee bearer is dynamic. These are the rules you may declare a share of, with [Create a pricing split](#tag/pricing_split).\n\nUse the rule's `pricing_type` to decide what to declare: `bps` on a `percentage` rule, `fixed_amount` on a `fixed` rule.\n", "operationId": "getDynamicPrices", "parameters": [ { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of dynamic pricing rules available to your business", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DynamicPrice" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "price_5JU9yv0lGSUP", "fee_type": "transaction_fees", "payment_type": "payin", "pricing_type": "percentage", "payment_rail": "swift", "from_currency": "USD", "bps": 300, "fees_amount": null, "fees_currency": null, "min_fee": 100, "max_fee": 2000, "min_max_fee_currency": "USD", "display_label": "Processing fee", "effective_from": "2026-07-01", "payment_method": { "type": "bank_transfer", "subtype": "swift_transfer" } }, { "id": "price_Kd82nvQ1TzAe", "fee_type": "transaction_fees", "payment_type": "payin", "pricing_type": "fixed", "payment_rail": "card", "from_currency": "USD", "bps": null, "fees_amount": 500, "fees_currency": "USD", "min_fee": null, "max_fee": null, "min_max_fee_currency": null, "display_label": "Card processing fee", "effective_from": "2026-07-15", "payment_method": { "type": "card", "subtype": null } } ], "page_meta": { "current": 1, "previous": null, "next": null, "per_page": 20, "pages": 1, "count": 2 } } } } }, "400": { "description": "Bad Request — invalid pagination parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "per_page must be an integer" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/prices/dynamic-splits": { "post": { "tags": [ "pricing_split" ], "summary": "Create a pricing split", "description": "Declare your share of a dynamic pricing rule's fee. The customer bears the remainder. List the rules you may declare against with [List dynamic pricing rules](#tag/pricing_split).\n\nProvide `price_id` and exactly one of `bps` or `fixed_amount`. Declare `bps` against a `percentage` rule and `fixed_amount` against a `fixed` rule. Your share cannot exceed the rule's own total: `bps` cannot exceed the rule's `bps`, and `fixed_amount` cannot exceed the rule's `fees_amount`. Each rule is held to its own ceiling.\n\nAmounts are in minor units (cents) and `bps` is basis points, so 100 is 1%. A `bps` of `0` is valid and means the customer bears the whole fee.\n\nPass the returned `id` in `split_ids` when you create a payment link, an order, a payin quote, a subscription or an auto debit. Until you pass it, the dynamic rule is never applied and pricing falls back to your normal (non-dynamic) rules.\n", "operationId": "createPricingSplit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePricingSplitRequest" }, "examples": { "percentage_split": { "summary": "Declare a share of a percentage rule", "value": { "price_id": "price_5JU9yv0lGSUP", "bps": 150 } }, "percentage_split_with_bounds": { "summary": "Declare a share of a percentage rule with a floor and a cap", "value": { "price_id": "price_5JU9yv0lGSUP", "bps": 150, "min_fee": 100, "max_fee": 1000, "fee_currency": "USD" } }, "fixed_split": { "summary": "Declare a share of a fixed rule", "value": { "price_id": "price_Kd82nvQ1TzAe", "fixed_amount": 200, "fee_currency": "USD" } }, "customer_bears_whole_fee": { "summary": "Declare a zero share, so the customer bears the whole fee", "value": { "price_id": "price_5JU9yv0lGSUP", "bps": 0 } } } } } }, "responses": { "201": { "description": "Pricing split created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricingSplit" }, "example": { "id": "psplit_7Kq2mXbTdLp9", "price_id": "price_5JU9yv0lGSUP", "bps": 150, "fixed_amount": null, "min_fee": 100, "max_fee": 1000, "fee_currency": "USD", "created_at": "2026-08-01T09:12:44Z", "updated_at": "2026-08-01T09:12:44Z" } } } }, "400": { "description": "Bad Request — validation error. The rule must belong to your business, have a dynamic fee bearer, price `payin` `transaction_fees`, be currently effective and be the latest effective version of the rule. Your declared share must match the rule's `pricing_type` and must not exceed the rule's own total.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "price_id not found" } } }, "examples": { "price_id_missing": { "summary": "price_id omitted", "value": { "error": "Bad Request", "message": "Price id can't be blank" } }, "price_id_not_found": { "summary": "price_id does not exist or belongs to another business", "value": { "error": "Bad Request", "message": "price_id not found" } }, "not_dynamic": { "summary": "The rule's fee bearer is not dynamic", "value": { "error": "Bad Request", "message": "price_id is not a dynamic-bearer rule" } }, "not_payin": { "summary": "The rule does not price a payin", "value": { "error": "Bad Request", "message": "dynamic splits are only supported for payin" } }, "not_transaction_fees": { "summary": "The rule does not price transaction fees", "value": { "error": "Bad Request", "message": "dynamic splits are only supported for transaction_fees" } }, "not_effective_yet": { "summary": "The rule version is not effective yet", "value": { "error": "Bad Request", "message": "price_id is not effective yet" } }, "superseded": { "summary": "A newer version of the rule is effective", "value": { "error": "Bad Request", "message": "price_id has been superseded by a newer version of the rule" } }, "neither_or_both": { "summary": "Neither bps nor fixed_amount, or both", "value": { "error": "Bad Request", "message": "exactly one of bps or fixed_amount must be provided" } }, "bps_required": { "summary": "fixed_amount declared against a percentage rule", "value": { "error": "Bad Request", "message": "bps is required for a percentage-priced rule" } }, "bps_exceeds_rule": { "summary": "Declared bps exceeds the rule's own bps", "value": { "error": "Bad Request", "message": "bps cannot exceed the rule's total of 300" } }, "fixed_amount_required": { "summary": "bps declared against a fixed rule", "value": { "error": "Bad Request", "message": "fixed_amount is required for a fixed-priced rule" } }, "fixed_amount_exceeds_rule": { "summary": "Declared fixed_amount exceeds the rule's own fees_amount", "value": { "error": "Bad Request", "message": "fixed_amount cannot exceed the rule's total" } }, "fee_currency_mismatch": { "summary": "fee_currency does not match a fixed rule's currency", "value": { "error": "Bad Request", "message": "fee_currency must be USD to match the rule" } }, "bounds_on_fixed_rule": { "summary": "min_fee or max_fee declared against a fixed rule", "value": { "error": "Bad Request", "message": "min_fee and max_fee are not supported for a fixed-priced rule" } }, "bound_without_currency": { "summary": "min_fee or max_fee declared without fee_currency", "value": { "error": "Bad Request", "message": "fee_currency is required when a bound is declared" } }, "min_fee_above_max_fee": { "summary": "min_fee greater than max_fee", "value": { "error": "Bad Request", "message": "min_fee must be less than or equal to max_fee" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "pricing_split" ], "summary": "List pricing splits", "description": "Returns the pricing splits your business has declared, sorted by creation date with the most recent split first. Pass `price_id` to return only the splits declared against one dynamic pricing rule.\n", "operationId": "getPricingSplits", "parameters": [ { "in": "query", "name": "price_id", "schema": { "type": "string" }, "description": "Return only the splits declared against this dynamic pricing rule.", "example": "price_5JU9yv0lGSUP" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of pricing splits matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PricingSplit" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "psplit_7Kq2mXbTdLp9", "price_id": "price_5JU9yv0lGSUP", "bps": 150, "fixed_amount": null, "min_fee": 100, "max_fee": 1000, "fee_currency": "USD", "created_at": "2026-08-01T09:12:44Z", "updated_at": "2026-08-01T09:12:44Z" }, { "id": "psplit_Q3vTn8LcRb2W", "price_id": "price_Kd82nvQ1TzAe", "bps": null, "fixed_amount": 200, "min_fee": null, "max_fee": null, "fee_currency": "USD", "created_at": "2026-08-02T11:04:09Z", "updated_at": "2026-08-02T11:04:09Z" } ], "page_meta": { "current": 1, "previous": null, "next": null, "per_page": 20, "pages": 1, "count": 2 } } } } }, "400": { "description": "Bad Request — invalid pagination parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "per_page must be an integer" } } } } } }, "401": { "description": "Unauthorized — invalid or missing authentication token", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/prices/{id}": { "get": { "tags": [ "Price" ], "summary": "Retrieve a price\n", "description": "Retrieves a single price by ID. Note that the response does not indicate whether this price is your\ncurrent default — that flag is accepted on create but is not returned on read.\n\nThe same access rule as listing applies: available to a platform business and to a business hosted by\na platform, and any other merchant is rejected with `401`. A price ID that is not yours returns `404`\nwith `Entity not found: Price`; one that is not well-formed is rejected with `400` before the lookup.\n", "operationId": "getPriceById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the price. Starts with `price_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `price_`; a well-formed ID that doesn't match a price on your account returns `404`.\n", "example": "price_E602dMzgjpDC" } ], "responses": { "200": { "description": "Price found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Price" }, { "example": { "bps": null } } ] } } } }, "404": { "description": "Price not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } } } }, "/subscriptions": { "get": { "tags": [ "Subscription" ], "summary": "List subscriptions", "description": "Returns a list of subscriptions matching some criteria. The subscriptions are returned sorted by creation date, with the most recent subscriptions appearing first.\n", "operationId": "getSubscriptions", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "created", "authorized", "active", "paused", "halted", "action_required", "under_review", "completed", "cancelled", "expired", "failed" ] }, "description": "Filter subscriptions by status. Uses the same values as the subscription's `status` field.", "example": "active" }, { "in": "query", "name": "customer_id", "schema": { "type": "string" }, "description": "Filter subscriptions by customer ID.", "example": "cust_5JU9yv0lGSUP" }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date" }, "description": "Filter subscriptions with a particular start date, in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2024-01-01" }, { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date" }, "description": "Filter subscriptions with a particular end date, in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2024-12-31" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of subscriptions matching the criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating why the request failed" } } } } } } }, "security": [ { "JWT": [] } ] }, "post": { "tags": [ "Subscription" ], "summary": "Create a new subscription", "description": "Creates a new subscription for a customer with specified billing plan and schedule. The subscription will be created in 'created' status and will be activated when the customer completes the first payment.\n\nOn an `as_presented` subscription, pass `split_ids` to declare your share of a dynamic pricing rule's fee. See [Dynamic Fee Split](#tag/pricing_split). The declaration applies to the first payment and to every subsequent auto debit that does not pass `split_ids` of its own. `split_ids` is rejected on a fixed-frequency subscription, because a fixed-frequency plan auto debits without you and so has no point at which to pass a split or replace one that goes stale.\n\nIf the subscription's declaration later stops resolving — Glomo deleted the underlying rule, or the rule is no longer dynamic — the next auto debit is rejected with a `400 Bad Request` until you pass a valid `split_ids` on [Create a payment](#tag/Payment).\n", "operationId": "createSubscription", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" }, "examples": { "monthly_subscription": { "summary": "Standard monthly subscription", "value": { "customer_id": "cust_5JU9yv0lGSUP", "product_name": "ShieldGuard Insurance", "product_description": "Flexible monthly insurance for belongings travel and digital assets easy to manage", "plan_name": "ShieldGuard Lite", "plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets", "amount": 1000, "currency": "USD", "interval_type": "month", "interval_count": 1, "billing_cycles": 12, "start_date": "2025-01-01", "expires_at": "2026-10-15", "notify_customer": true, "starts_with_first_payment": true } }, "as_presented_subscription": { "summary": "Subscription with as_presented interval (flexible billing, merchant-initiated subsequent payments)", "value": { "customer_id": "cust_5JU9yv0lGSUP", "product_name": "ShieldGuard Insurance", "product_description": "Flexible insurance for belongings easy to manage", "plan_name": "ShieldGuard Lite", "plan_description": "Subscription with flexible billing intervals", "amount": 1000, "max_amount": 5000, "currency": "USD", "interval_type": "as_presented", "expires_at": "2026-10-15", "notify_customer": true, "starts_with_first_payment": true } }, "as_presented_subscription_with_splits": { "summary": "as_presented subscription priced from a declared dynamic fee split", "value": { "customer_id": "cust_5JU9yv0lGSUP", "product_name": "ShieldGuard Insurance", "product_description": "Flexible insurance for belongings easy to manage", "plan_name": "ShieldGuard Lite", "plan_description": "Subscription with flexible billing intervals", "amount": 1000, "max_amount": 5000, "currency": "USD", "interval_type": "as_presented", "expires_at": "2026-10-15", "notify_customer": true, "starts_with_first_payment": true, "split_ids": [ "psplit_7Kq2mXbTdLp9" ] } } } } } }, "responses": { "201": { "description": "Subscription created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionResponse" } } } }, "400": { "description": "Bad Request - validation error or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message describing the validation failure", "example": "Customer not found" } } }, "examples": { "customer_not_found": { "summary": "Customer not found", "value": { "error": "Bad Request", "message": "Customer not found" } }, "split_ids_on_fixed_frequency": { "summary": "split_ids sent on a fixed-frequency subscription", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are only supported for as_presented subscriptions" } }, "split_ids_unresolved": { "summary": "A split id does not resolve to a live dynamic rule", "value": { "error": "Bad Request", "message": "Validation failed: Split ids are invalid or no longer point at a dynamic rule: psplit_7Kq2mXbTdLp9" } }, "split_ids_incomplete": { "summary": "Another dynamic rule on the same dimension is not declared", "value": { "error": "Bad Request", "message": "Validation failed: Split ids must be declared for every dynamic rule on the dimension, missing rules: price_Kd82nvQ1TzAe" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/subscriptions/{id}": { "get": { "tags": [ "Subscription" ], "summary": "Retrieve a subscription by ID", "description": "Retrieves the details of a specific subscription by its unique identifier.\n", "operationId": "getSubscriptionById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the subscription. Starts with `sub_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `sub_`; a well-formed ID that doesn't match a subscription on your account returns `404`.\n", "example": "sub_5JU9yv0lGSUP" } ], "responses": { "200": { "description": "Subscription details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "example": "Subscription not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/subscriptions/{id}/pause": { "patch": { "tags": [ "Subscription" ], "summary": "Pause a subscription", "description": "Pauses an active subscription. While paused, the subscription will not process any payments. A paused subscription can be resumed later using the resume endpoint.\n", "operationId": "pauseSubscription", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the subscription to pause. Starts with `sub_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `sub_`; a well-formed ID that doesn't match a subscription on your account returns `404`.\n", "example": "sub_5JU9yv0lGSUP" } ], "responses": { "200": { "description": "Subscription paused successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "object", "properties": { "status": { "example": "paused" }, "next_payment_date": { "example": null } } } ] } } } }, "400": { "description": "Bad Request - subscription cannot be paused from current state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "example": "Subscription cannot be paused from current state: cancelled" } } } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "example": "Subscription not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/subscriptions/{id}/resume": { "patch": { "tags": [ "Subscription" ], "summary": "Resume a paused subscription", "description": "Resumes a paused subscription. Once resumed, the subscription will continue processing payments according to its original schedule. Only subscriptions in 'paused' status can be resumed.\n", "operationId": "resumeSubscription", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the subscription to resume. Starts with `sub_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `sub_`; a well-formed ID that doesn't match a subscription on your account returns `404`.\n", "example": "sub_5JU9yv0lGSUP" } ], "responses": { "200": { "description": "Subscription resumed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "Bad Request - subscription cannot be resumed from current state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "example": "Subscription cannot be resumed from current state: active" } } } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "example": "Subscription not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/subscriptions/{id}/cancel": { "patch": { "tags": [ "Subscription" ], "summary": "Cancel a subscription", "description": "Cancels a subscription. Once cancelled, the subscription will stop processing future payments. This action cannot be undone, but you can create a new subscription if needed.\n", "operationId": "cancelSubscription", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the subscription to cancel. Starts with `sub_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `sub_`; a well-formed ID that doesn't match a subscription on your account returns `404`.\n", "example": "sub_5JU9yv0lGSUP" } ], "responses": { "200": { "description": "Subscription cancelled successfully", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Subscription" }, { "type": "object", "properties": { "status": { "example": "cancelled" }, "next_payment_date": { "example": null } } } ] } } } }, "400": { "description": "Bad Request - subscription cannot be cancelled from current state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "example": "Subscription cannot be cancelled from current state: completed" } } } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "example": "Subscription not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/subscriptions/{id}/next-payment-date": { "patch": { "tags": [ "Subscription" ], "summary": "Update next payment date", "description": "Updates the next payment date of a subscription.\n", "operationId": "updateNextPaymentDate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriptionNextPaymentDate" } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the subscription whose next payment date to update. Starts with `sub_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `sub_`; a well-formed ID that doesn't match a subscription on your account returns `404`.\n", "example": "sub_5JU9yv0lGSUP" } ], "responses": { "200": { "description": "Subscription updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "description": "Bad Request - next payment date cannot be updated from current state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "example": "New payment date cannot exceed the current next_payment_date by more than 28 days. Difference: 30 days" } } } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "example": "Subscription not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/settlements": { "post": { "tags": [ "Settlement" ], "summary": "Create a new settlement", "description": "Withdraws an amount from one of your currency balances to the withdrawal account registered for that\ncurrency, and returns the resulting settlement in `pending`.\n\nOnly available to businesses on manual settlement mode. On automatic settlement mode Glomo initiates\nsettlements for you and this call returns `403` — it is not a way to pull a settlement forward.\n\nThe destination is not something you choose per request. There is no account field: the withdrawal\naccount already registered against `balance_currency` is used, and a currency with no registered\nwithdrawal account returns `404`. To settle to a different bank, change the registered withdrawal\naccount rather than the request.\n\nSend `balance_currency` in upper case. Unlike most currency parameters on this API it is matched\nexactly, so a lower-case code will not find your withdrawal account and returns the same `404`.\n", "operationId": "createSettlement", "requestBody": { "required": true, "description": "Provide both the `amount` and the `balance_currency`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSettlementRequest" } } } }, "responses": { "201": { "description": "Settlement created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid", "example": "Validation failed: Currency is not supported" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Forbidden" ] }, "message": { "type": "string", "example": "Settlements API is only available for businesses with manual settlement mode" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not Found" ] }, "message": { "type": "string", "example": "Withdrawal account not found" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Settlement" ], "summary": "List all settlements", "description": "Returns a list of your settlements. The settlements are returned sorted by creation date, with the most recent settlement appearing first.\n", "operationId": "getSettlements", "parameters": [ { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of withdrawals matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/settlements/mock-trigger": { "post": { "tags": [ "Settlement" ], "summary": "Trigger a mock settlement", "description": "This API is only available in sandbox mode. Queues a settlement run for your account so you can exercise settlements without a wait for the daily settlement schedule.\n", "operationId": "triggerMockSettlement", "security": [ { "JWT": [] } ], "responses": { "202": { "description": "Settlement run accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Confirms that the settlement run was queued.", "enum": [ "accepted" ] }, "withdrawal_account_id": { "type": "string", "description": "The settlement account that the run pays into.", "example": "accwith_E602dMzgjpDC" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication token" }, "404": { "description": "Not Found - Endpoint is unavailable outside sandbox" } } } }, "/settlements/{id}": { "get": { "tags": [ "Settlement" ], "summary": "Retrieve a settlement", "description": "Returns a specific settlement by its unique identifier.\n", "operationId": "getSettlementById", "parameters": [ { "in": "path", "required": true, "name": "id", "schema": { "type": "string" }, "description": "The unique identifier of the settlement. Starts with `setl_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `setl_`; a well-formed ID that doesn't match a settlement on your account returns `404`.\n", "example": "setl_6878e266jt1P3" } ], "responses": { "200": { "description": "Settlement found", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/Settlement" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid" } } } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/settlements/{id}/transactions": { "get": { "tags": [ "Settlement" ], "summary": "Retrieve transactions linked to a settlement", "description": "Returns a list of transactions that are linked to a specific settlement by its unique identifier.\n", "operationId": "getTransactionsLinkedToSettlement", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the settlement. Starts with `setl_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `setl_`; a well-formed ID that doesn't match a settlement on your account returns `404`.\n", "example": "setl_6878e266jt1P3" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of Transactions matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid" } } } } } }, "404": { "description": "Settlement not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/virtual-accounts": { "get": { "tags": [ "virtual_account" ], "summary": "List all Virtual Accounts", "description": "Returns the customer's virtual accounts, sorted by creation date (newest first), using the customer's JWT token for access.\n", "operationId": "getVirtualAccounts", "parameters": [ { "in": "query", "name": "currency", "schema": { "$ref": "#/components/schemas/Currency" }, "description": "Filter virtual accounts by currency" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of virtual accounts matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualAccount" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid", "example": "Missing Required parameters" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] }, "delete": { "tags": [ "virtual_account" ], "summary": "Close a Virtual Account", "description": "Closing active virtual accounts will be based on the specified payment type and currency. The endpoint closes all virtual accounts for a given payment type and currency. Once closed, the virtual account will no longer accept payments.\n", "operationId": "closeVirtualAccount", "parameters": [ { "in": "query", "name": "payment_type", "required": true, "schema": { "type": "string", "enum": [ "local", "swift" ] }, "description": "The type of payments this virtual account accepts. 'local' for domestic payments within the same country, 'swift' for cross-border payments.\n", "example": "local" }, { "in": "query", "name": "currency", "required": true, "schema": { "$ref": "#/components/schemas/Currency" }, "description": "The currency of the virtual account to close in ISO 4217 format.\n", "example": "AED" } ], "responses": { "200": { "description": "Virtual account closed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Virtual account closed successfully" } } } } } }, "400": { "description": "Bad request - Active account not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Active account not found" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/v2/virtual-accounts": { "servers": [ { "url": "https://api.glomopay.com/api", "description": "Production server" } ], "post": { "tags": [ "virtual_account" ], "summary": "Create a Virtual Account (v2)", "description": "Creates a new virtual account with the specified payment type and currency. Virtual accounts provide unique account numbers that can be used to receive payments for customers. This endpoint returns HTTP 202 indicating the request has been accepted and is being processed. You will receive a [webhook notification](https://glomo-payments--45ac07.preview.redocly.app/api-documentation/webhooks/virtual-account) when the virtual account is activated.\n", "operationId": "createVirtualAccountV2", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_type": { "type": "string", "enum": [ "local", "swift" ], "description": "The type of payments this virtual account will accept. 'local' for domestic payments within the same country, 'swift' for cross-border payments.\n", "example": "local" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The currency for the virtual account in ISO 4217 format.\n", "example": "AED" } }, "required": [ "payment_type", "currency" ] } } } }, "responses": { "202": { "description": "Virtual account creation request is accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Virtual account creation request is accepted." }, "data": { "type": "object", "properties": { "merchant_id": { "type": "string", "example": "merch_694bb0289P4Cz" }, "status": { "type": "string", "enum": [ "pending" ], "example": "pending" } } } } }, "example": { "message": "Virtual account creation request is accepted.", "data": { "merchant_id": "merch_694bb0289P4Cz", "status": "pending" } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message indicating which parameter was invalid", "example": "Missing Required parameters" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "409": { "description": "Conflict - Record already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Duplicate record" ] }, "message": { "type": "string", "description": "Virtual Account already exists", "example": "Virtual Account already exists" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/platform/merchants": { "post": { "tags": [ "platform" ], "summary": "Onboard a merchant", "description": "Allows platforms to onboard a new merchant onto Glomo.\n", "operationId": "onboardMerchant", "security": [ { "JWT": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" }, "examples": { "individual": { "summary": "Individual merchant", "value": { "name": "John Doe", "address_line1": "456 Commerce Street", "address_line2": "Suite 101", "city": "Mumbai", "state": "Maharashtra", "pincode": "400001", "registration_number": "ABCDE1234F", "registration_country": "IND", "entity_type": "individual", "category": "Agricultural Services", "sub_category": "Veterinary Services", "operation_countries": [ "IND" ], "date_of_birth": "2001-08-04", "gender": "male", "passport": { "number": "P1234567", "expiry_date": "2030-06-01", "country_of_issuance": "IND" } } }, "business": { "summary": "Business merchant", "value": { "name": "Acme Trading Private Limited", "dba_name": "Acme Retail", "address_line1": "456 Commerce Street", "address_line2": "Suite 101", "city": "Mumbai", "state": "Maharashtra", "pincode": "400001", "registration_number": "REG123456", "registration_country": "IND", "entity_type": "business", "business_type": "private_limited", "category": "Agricultural Services", "sub_category": "Veterinary Services", "operation_countries": [ "IND" ], "registration_date": "2020-06-01", "website": "https://acme.example.com", "annual_turnover": "1m_to_5m", "registration_document_id": "doc_nYUqLpuYQ0M8", "ubos": [ { "name": "Jane Doe", "type": "individual", "ownership_percentage": 60, "country": "IND" }, { "name": "Doe Holdings Pte Ltd", "type": "company", "ownership_percentage": 40, "country": "SGP" } ], "settlement_account": { "account_holder_name": "Acme Trading Private Limited", "account_number": "123456789", "bank_name": "JPMorgan Chase Bank", "swift_code": "CHASUS33", "currency": "USD", "bank_address": { "address_line1": "270 Park Avenue", "city": "New York", "administrative_area": "NY", "postal_code": "10017", "country_code": "USA" } } } } } } } }, "responses": { "201": { "description": "Merchant onboarded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantCreateResponse" } } } }, "202": { "description": "Merchant has been created and submitted for KYB review. It is not active until the review is approved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantKybReviewResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Invalid request data" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } } } }, "/platform/merchants/{merchant_id}": { "get": { "tags": [ "platform" ], "summary": "Retrieve a merchant", "description": "Retrieves details of a specific merchant by their merchant ID.\n", "operationId": "getMerchant", "security": [ { "JWT": [] } ], "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "description": "Unique identifier of the merchant. Starts with `merch_` followed by letters and digits. An ID of any other shape is rejected with `400` and a message saying it must start with `merch_`; a well-formed ID that doesn't match a merchant under your platform account returns `404`.\n", "schema": { "type": "string", "example": "merch_68c777fcOOMpl" } } ], "responses": { "200": { "description": "Merchant retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Invalid merchant ID format" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Merchant with the specified ID was not found" } } } } } } } }, "patch": { "tags": [ "platform" ], "summary": "Update a merchant", "description": "Updates an existing merchant. Currently supports attaching a `passport`\nobject for individual merchants and a `registration_date` for business\nmerchants; more fields may be supported in future.\n\nThe applicable field is determined by the merchant's entity type, set at\nonboarding, rather than by the request body: send `passport` for an\nindividual merchant and `registration_date` for a business merchant. A field\nthat does not apply to the merchant's entity type is ignored.\n", "operationId": "updateMerchant", "security": [ { "JWT": [] } ], "parameters": [ { "name": "merchant_id", "in": "path", "required": true, "description": "Unique identifier of the merchant. Starts with `merch_` followed by letters and digits. An ID of any other shape, or one that doesn't match a merchant under your platform account, returns `404`.\n", "schema": { "type": "string", "example": "merch_68c777fcOOMpl" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantRequest" }, "examples": { "individual": { "summary": "Individual merchant (attach passport)", "value": { "passport": { "number": "P1234567", "expiry_date": "2030-06-01", "country_of_issuance": "IND" } } }, "business": { "summary": "Business merchant (attach registration_date)", "value": { "registration_date": "2020-06-01" } } } } } }, "responses": { "200": { "description": "Merchant updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Passport is required for individual entity type" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Merchant not found" }, "message": { "type": "string", "example": "Merchant not found for id: merch_68c777fcOOMpl" } } } } } } } } }, "/platform/merchants/status-update": { "patch": { "tags": [ "platform" ], "summary": "Update merchant status", "description": "Allows platforms to update the status of a merchant. This endpoint is available in non-production environments only.\n", "operationId": "updateMerchantStatus", "security": [ { "JWT": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_status": { "type": "string", "enum": [ "success" ], "description": "The target status to update the merchant to", "example": "success" }, "merchant_id": { "type": "string", "description": "The merchant for which the status is to be updated", "example": "merch_68511919RVuf6" } }, "required": [ "target_status", "merchant_id" ] } } } }, "responses": { "200": { "description": "Merchant status updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Invalid merchant status update" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Unauthorized" } } } } } } } } }, "/internal-transfer": { "post": { "tags": [ "internal_transfer" ], "summary": "Create an internal transfer", "description": "Creates an internal transfer between two merchant accounts.\n", "operationId": "createInternalTransfer", "security": [ { "JWT": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInternalTransferRequest" } } } }, "responses": { "201": { "description": "Internal transfer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalTransfer" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Invalid request data" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } } } }, "/kyc-links": { "get": { "tags": [ "KycLink" ], "summary": "List KYC links", "description": "Returns a list of KYC links. The links are returned sorted by creation date, with the most recent links appearing first. Optionally filter by status.\n", "operationId": "listKycLinks", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "initiated", "in_progress", "submitted", "action_required", "under_review", "completed", "failed", "expired", "rejected" ] }, "description": "Filter KYC links by status. Uses the same values as the KYC link's `status` field.", "example": "completed" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of KYC links matching the criteria.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KycLinkDetail" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "description": "Error message indicating why the request failed." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] }, "post": { "tags": [ "KycLink" ], "summary": "Create a KYC link", "description": "Creates a KYC link that can be shared with a customer to complete identity verification. Optionally associate with an existing customer via `customer_id`, or with a new customer via `email`. Both fields are optional and mutually exclusive — passing both will return a 400 error. Omitting both creates an unlinked KYC link.\n\nBy default (`send_email: true`), Glomo will send the link to the customer's email address automatically. Set `send_email: false` to suppress the email and distribute the link yourself.\n\nThe response contains a summary of the created KYC link. To retrieve full details — including the customer ID, status tracker, and submitted documents — use `GET /kyc-links/{id}`.\n", "operationId": "createKycLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "The unique identifier of an existing customer (`cust_` prefix). Mutually exclusive with `email`.\n", "example": "cust_abc123XYZ" }, "email": { "type": "string", "format": "email", "description": "Email address to associate the KYC link with. Mutually exclusive with `customer_id`.\n", "example": "john.doe@example.com" }, "expire_in_days": { "type": "integer", "description": "Number of days until the link expires. Must be greater than 0. Defaults to the platform setting if omitted.\n", "example": 90 }, "send_email": { "type": "boolean", "description": "Whether to send the KYC link to the customer via email. Defaults to `true` — omitting this field will trigger an email to the customer.\n", "default": true, "example": true } } }, "example": { "email": "john.doe@example.com", "expire_in_days": 90, "send_email": true } } } }, "responses": { "201": { "description": "KYC link created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the KYC link.", "example": "kyc_69b3f97eSThQY" }, "status": { "type": "string", "description": "Current status of the KYC link.", "example": "initiated" }, "link_url": { "type": "string", "format": "uri", "description": "The shareable URL to send to the customer to complete KYC. Share it as returned rather than building it yourself: in sandbox it ends with `?sandbox=true`.\n", "example": "https://app.glomopay.com/kyc-links/kyc_69b3f97eSThQY" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the link expires, as an ISO 8601 date-time in UTC.\n", "example": "2026-06-11T11:48:14.361Z" }, "created_at": { "type": "string", "format": "date-time", "description": "When the link was created, as an ISO 8601 date-time in UTC.\n", "example": "2026-03-13T11:48:14.363Z" }, "customer_id": { "type": [ "string", "null" ], "description": "The unique identifier of the customer associated with this KYC link. `null` if no existing customer is associated — e.g. when created with only an email address, or without `customer_id` or `email`.\n", "example": "cust_abc123XYZ" } } }, "example": { "id": "kyc_69b3f97eSThQY", "status": "initiated", "link_url": "https://app.glomopay.com/kyc-links/kyc_69b3f97eSThQY", "expires_at": "2026-06-11T11:48:14.361Z", "created_at": "2026-03-13T11:48:14.363Z", "customer_id": "cust_abc123XYZ" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "description": "Error message describing the validation failure.", "example": "customer_id and email are mutually exclusive" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/kyc-links/{id}": { "get": { "tags": [ "KycLink" ], "summary": "Retrieve a KYC link", "description": "Retrieves the details of a KYC link by its unique identifier, including the verification status, customer ID and the list of KYC documents submitted.\n\nEach document in the `documents` array includes a `document_id` field. When the document `status` is `captured`, the `document_id` (e.g. `doc_nYUqLpuYQ0M8`) can be passed to `GET /api/v1/document/{document_id}` to retrieve full document details such as the preview URL and file name. The `document_id` is `null` when the document has not yet been uploaded (`status: not_captured`).\n", "operationId": "getKycLinkById", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the KYC link.", "example": "kyc_69b3f97eSThQY" } ], "responses": { "200": { "description": "KYC link retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KycLinkDetail" }, "example": { "id": "kyc_69b3f97eSThQY", "status": "completed", "link_url": "https://app.glomopay.com/kyc-links/kyc_69b3f97eSThQY", "expires_at": "2026-06-11T11:48:14.361Z", "created_at": "2026-03-13T11:48:14.363Z", "customer_id": "cust_abc123XYZ", "tracker": [ { "created_at": "2026-03-13T12:00:00.000Z", "text": "KYC verification completed" } ], "documents": [ { "id": "kycdoc_abc111", "document_id": null, "type": "aadhaar", "status": "not_captured", "created_at": "2026-03-13T11:48:14.458Z", "uploaded_at": null }, { "id": "kycdoc_abc222", "document_id": "doc_69b3f9b4MJgKZ", "type": "pan_card", "status": "captured", "created_at": "2026-03-13T11:48:14.458Z", "uploaded_at": "2026-03-13T11:49:08.093Z" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "404": { "description": "KYC link not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "KYC link with given id does not exist" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/payment-sessions": { "get": { "tags": [ "payment_session" ], "summary": "List payment sessions", "description": "Returns payment sessions, newest first. Each item is the same snapshot as [Retrieve a payment session](/api-reference/openapi/payment_session/getpaymentsession), without `failure_reason`.\n\n**Which sessions you see:** a fund sees the sessions it owns. A distributor sees the sessions credited to it, across every fund it has a relationship with.\n\n**Page size:** `per_page` defaults to `20` and is capped at `25`, because each item is a full snapshot. A larger value is not an error: it returns 25 items and `page_meta.per_page` is `25`. This endpoint does not accept `before` or `after`.\n", "operationId": "listPaymentSessions", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "completed", "failed" ] }, "description": "Return only sessions with this final status. Only `completed` and `failed` can be filtered on; any other value returns `400`. Each item's `status` still uses the full set of values described on the snapshot.\n" }, { "in": "query", "name": "scheme_code", "schema": { "type": "string" }, "description": "Return only sessions for this AMC scheme: the scheme the investor chose, or, before they choose, the scheme of the prefilled plan. Case-insensitive. A code that matches no scheme returns an empty page, not an error.\n", "example": "SCH001" }, { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 25 }, "description": "Number of sessions per page. Values above 25 are treated as 25." }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "Payment sessions matching the filters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentSessionSnapshot" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "psess_6819d8046mpKt", "session_type": "kyc_lrs_folio", "status": "completed", "failure": null, "created_at": "2026-11-03T05:12:40Z", "expires_at": "2026-11-10T05:12:40Z", "updated_at": "2026-11-05T08:20:16Z", "customer_id": "cust_6819d7d0lrLvP", "scheme": { "scheme_code": "SCH001", "name": "Example Global Equity Fund - Regular Plan", "plan": "regular", "distributor_arn": "ARN12345" }, "amount": { "value": 500000, "currency": "USD" }, "expected_entities": [ "kyc", "folio", "order", "payments", "folio_transaction" ], "entities": { "kyc": { "id": "kyc_6819d8046mpKt", "status": "completed", "failure_reason": null, "bank_enabled": true, "updated_at": "2026-11-03T05:40:02Z" }, "folio": { "id": "amcfolio_6819e1a2kQwRt", "folio_number": "91234567/89", "status": "active" }, "order": { "id": "order_678a4c88hpAjf", "status": "paid", "expires_at": "2026-11-04T05:45:00Z", "updated_at": "2026-11-03T06:01:58Z" }, "payments": [ { "id": "payt_6819e5b1nTzXc", "status": "success", "amount": 500000, "currency": "USD", "method": "pay_via_bank", "payer": { "name": "Asha Verma", "country": "IND", "bank_name": "HDFC bank", "account_number": "••••1234" }, "paid_at": "2026-11-03T06:01:55Z", "error_code": null, "error_message": null, "updated_at": "2026-11-03T06:01:58Z" } ], "folio_transaction": { "id": "amcftxn_6819f0c3pLmNb", "type": "fresh_purchase", "status": "units_allotted", "payment_id": "payt_6819e5b1nTzXc", "units": "412.3571", "nav": "12.1254", "nav_date": "2026-11-04", "error_code": null, "error_message": null } } } ], "page_meta": { "current": 1, "previous": null, "next": 2, "per_page": 1, "pages": 14, "count": 14 } } } } }, "400": { "description": "Bad request — a `status` other than `completed` or `failed`, a `status` or `scheme_code` that is not a string, or an invalid `page` or `per_page`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Validation failed: Status must be one of: completed, failed" } } } } } }, "401": { "description": "Unauthorized — missing or invalid JWT token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } } }, "security": [ { "JWT": [] } ] }, "post": { "tags": [ "payment_session" ], "summary": "Create a payment session", "description": "Creates a payment session — a configurable workflow that wraps a payment journey with pre-steps and/or post-steps such as identity verification, compliance checks, or data collection. The exact step sequence is determined by the `session_type` configured for your business.\n\n**Example:** The `kyc_lrs` session type adds a KYC verification step before the LRS remittance checkout, ensuring the customer is verified before funds are transferred.\n\n**Next step: launch the SDK.** Creating a session does not start the customer journey on its own. After this call, pass the returned `id` and `token` to the [Unified SDK (Web)](/platform/sdk/unified-sdk) as `paymentSessionId` and `paymentSessionToken` to open the guided UI for the customer. The SDK guide's \"Journey 1: Payment Session\" section has the integration steps.\n\nOptionally associate the session with an existing customer via `customer_id`, or pre-populate customer details using `email`. Both fields are optional and mutually exclusive — passing both returns a 400 error. Omitting both creates an anonymous session.\n\n**Prefilling steps:** Pass prefill data to pre-populate steps in the flow so the customer skips re-entering known values. Include only the data relevant to your `session_type`.\n- **KYC prefill** — identity details (`pan`, `phone`, `country`, `dob`) used to prefill\n the KYC step. Two request shapes are supported: **v1** places the `kyc` object at the\n top level; **v2** nests it under `data.kyc` (recommended, and the shape used alongside\n other `data` groups). Provide only one shape — supplying `kyc` at both the top level and\n under `data` returns a 400 error. When any of `pan`, `phone`, or `dob` is supplied, pair\n it with `email`; these fields cannot be combined with `customer_id` (which is\n authoritative), and supplying them without any identifier returns a 400 error. When\n `phone` is supplied, `country` (ISO 3166-1 alpha-3) is required and is used to validate\n the phone number format.\n\n- **Scheme prefill** (`data.scheme`) — investment scheme details (`plan`, `amount`,\n `currency`, `distributor_arn`, `ria_code`, `sub_distributor_code`) used to prefill the\n scheme plan and amount step. `amount` and `currency` must be supplied together.\n\n\n**Sessions for a named scheme:** pass `data.scheme.scheme_code` to open the session for one scheme. A distributor must send it; see [Open payment sessions as a distributor](/capital-markets/distributor/set-up). A fund can name one of its own schemes.\n\nContact support if you receive a 403 error — payment sessions must be enabled for your business.\n", "operationId": "createPaymentSession", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "The unique identifier of an existing customer (`cust_` prefix). Mutually exclusive with `email`.\n", "example": "cust_abc123XYZ" }, "email": { "type": "string", "format": "email", "description": "Email address to pre-populate customer details in the session flow. Mutually exclusive with `customer_id`.\n", "example": "john.doe@example.com" }, "kyc": { "type": "object", "description": "KYC prefill (v1) — identity details used to prefill the KYC step. Equivalent to `data.kyc` (v2, recommended); provide one shape or the other, not both. Only accepted when `customer_id` or `email` is also provided at the top level.\n", "properties": { "pan": { "type": "string", "description": "Indian Permanent Account Number. Format: 10 characters, e.g. `ABCPE1234F`.\n", "example": "ABCPE1234F" }, "phone": { "type": "string", "description": "Customer phone number, validated against `country`. Must be supplied together with `country` — phone without country is rejected.\n", "example": "9876543210" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code used to validate `phone` (e.g. `IND`, `USA`, `GBR`).\n", "example": "IND" }, "dob": { "type": "string", "format": "date", "description": "Date of birth in ISO 8601 format (`YYYY-MM-DD`).", "example": "1990-05-12" } } }, "data": { "type": "object", "description": "Optional container for prefill data. Include only the groups relevant to your `session_type`; unknown groups are ignored. When present it must be a JSON object; an array, string, number or boolean returns a 400 error.\n", "properties": { "kyc": { "type": "object", "description": "KYC prefill (v2, recommended) — identity details used to prefill the KYC step. Same fields as the top-level `kyc` (v1); the two shapes cannot be combined.\n", "properties": { "pan": { "type": "string", "description": "Indian Permanent Account Number. Format: 10 characters, e.g. `ABCPE1234F`.\n", "example": "ABCPE1234F" }, "phone": { "type": "string", "description": "Customer phone number, validated against `country`. Must be supplied together with `country` — phone without country is rejected.\n", "example": "9876543210" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code used to validate `phone` (e.g. `IND`, `USA`, `GBR`).\n", "example": "IND" }, "dob": { "type": "string", "format": "date", "description": "Date of birth in ISO 8601 format (`YYYY-MM-DD`).", "example": "1990-05-12" } } }, "scheme": { "type": "object", "description": "Investment scheme details used to prefill the scheme plan and amount step. Include `scheme_code` to open the session for a named scheme.\n", "properties": { "scheme_code": { "type": "string", "description": "Code of the AMC scheme the session is for. Case-insensitive. Required for a distributor.\n", "example": "SCH001" }, "plan": { "type": "string", "enum": [ "regular", "direct" ], "description": "AMC scheme plan. Ignored for a distributor. With `scheme_code`, it must match the scheme's plan.\n", "example": "regular" }, "amount": { "type": "integer", "description": "Investment amount in the smallest currency unit (e.g. cents for USD, so `500000` is $5,000.00). Must be a positive integer and supplied together with `currency`. Send a multiple of `100` (whole dollars): the checkout form accepts only whole-dollar amounts, so a prefill with cents, such as `500050`, is shown to the customer as invalid until they change it.\n", "example": 500000 }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency of `amount`. Only `USD` is supported. Supplied together with `amount`.", "example": "USD" }, "distributor_arn": { "type": "string", "description": "AMC distributor ARN. Must start with your configured distributor-code prefix, if one is set for your business. Ignored for a distributor.\n", "example": "ARN12345" }, "ria_code": { "type": "string", "maxLength": 20, "description": "Registration code of the investment adviser (RIA) who sourced a direct-plan investment. Ignored on a regular plan.\n", "example": "INA000012345" }, "sub_distributor_code": { "type": "string", "maxLength": 20, "description": "Code of the sub-broker who sourced a regular-plan investment, sent to the RTA so the commission is credited to them. A distributor can send it. Surrounding spaces are trimmed. The investor can change it. Ignored on a direct plan.\n", "example": "SUB00123" } } } } } } }, "examples": { "anonymous": { "summary": "Anonymous session", "value": {} }, "with_email": { "summary": "With customer email", "value": { "email": "john.doe@example.com" } }, "with_customer_id": { "summary": "With existing customer ID", "value": { "customer_id": "cust_abc123XYZ" } }, "with_kyc_prefill_v1": { "summary": "Prefill KYC — top-level kyc object (v1)", "value": { "email": "john.doe@example.com", "kyc": { "pan": "ABCPE1234F", "phone": "9876543210", "country": "IND", "dob": "1990-05-12" } } }, "with_kyc_prefill_v2": { "summary": "Prefill KYC — nested under data (v2, recommended)", "value": { "email": "john.doe@example.com", "data": { "kyc": { "pan": "ABCPE1234F", "phone": "9876543210", "country": "IND", "dob": "1990-05-12" } } } }, "with_scheme_prefill": { "summary": "Prefill scheme plan and amount", "value": { "email": "john.doe@example.com", "data": { "scheme": { "plan": "regular", "amount": 500000, "currency": "USD", "distributor_arn": "ARN12345" } } } }, "with_ria_code": { "summary": "Prefill a direct plan sourced by an RIA", "value": { "email": "john.doe@example.com", "data": { "scheme": { "plan": "direct", "amount": 500000, "currency": "USD", "ria_code": "INA000012345" } } } }, "with_sub_distributor_code": { "summary": "Prefill a regular plan sourced by a sub-broker", "value": { "email": "john.doe@example.com", "data": { "scheme": { "plan": "regular", "amount": 500000, "currency": "USD", "distributor_arn": "ARN12345", "sub_distributor_code": "SUB00123" } } } }, "with_scheme_code": { "summary": "Session for a named scheme (scheme_code)", "value": { "email": "john.doe@example.com", "data": { "scheme": { "scheme_code": "SCH001", "amount": 500000, "currency": "USD" }, "kyc": { "pan": "ABCPE1234F" } } } } } } } }, "responses": { "201": { "description": "Payment session created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" }, "example": { "id": "psess_6819d8046mpKt", "status": "active", "session_type": "kyc_lrs", "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": "2026-05-07T10:30:00Z" } } } }, "400": { "description": "Bad request — validation error, including an invalid format for `email`, `customer_id`, `pan`, `phone`, `country`, or `dob`, or `phone` supplied without `country`; mutually exclusive fields provided; prefill fields supplied without an identifier; KYC prefill supplied both at the top level (v1) and under `data` (v2); `data` that is not an object; a blank or missing `scheme_code` (required for distributors); or a `ria_code` or `sub_distributor_code` longer than 20 characters. Validation errors carry a `Validation failed: ` prefix in `message`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "customer_id or email is required when pan, phone, or dob is supplied" } } } } } }, "401": { "description": "Unauthorized — missing or invalid JWT token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "403": { "description": "Forbidden — payment sessions are not enabled for this business. For a distributor, also:\n- `No active relationship with this fund` - `Scheme not enabled for this relationship`\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "message": { "type": "string", "example": "Payment session is not enabled for this business" } } } } } }, "404": { "description": "Not found — `scheme_code` does not match an active scheme you can use.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Scheme not found" } } } } } }, "409": { "description": "Conflict — the `pan` supplied is already registered under a different email, on an existing customer or an in-progress KYC.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "PAN is already registered with a different email" } } } } } }, "422": { "description": "Unprocessable entity — with `scheme_code`:\n- `plan must match the scheme` - `Scheme is not available for distribution` (a direct plan, for a distributor) - `Fund is not configured for scheme sessions` - `Distributor ARN is not configured for this fund` - `customer_id is not supported for relationship-originated sessions`\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unprocessable Entity" }, "message": { "type": "string", "example": "Scheme is not available for distribution" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/payment-sessions/{id}": { "get": { "tags": [ "payment_session" ], "summary": "Retrieve a payment session", "description": "Returns the current state of a payment session: its status, failure reason, scheme, amount and the records it has produced so far (KYC, folio, order, payments, folio transaction and refunds). The body is the same snapshot sent as `data` in the [payment_session webhook](/platform/webhooks/payment-session), plus `failure_reason`.\n\n**Who can read it:** the fund that owns the session, or the distributor the session is credited to. Any other business gets `404`, as if the session did not exist.\n\n`status` is read live, so a session past `expires_at` with no money moved reads `expired` here before the `expired` webhook is sent.\n", "operationId": "getPaymentSession", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the payment session, prefixed with `psess_`.", "example": "psess_6819d8046mpKt" } ], "responses": { "200": { "description": "Payment session retrieved successfully.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaymentSessionSnapshot" }, { "type": "object", "properties": { "failure_reason": { "type": [ "string", "null" ], "description": "Same as `failure.message`. `null` unless `status` is `failed`.", "example": null } } } ] }, "examples": { "paid": { "summary": "Paid, waiting for units to be allotted", "value": { "id": "psess_6819d8046mpKt", "session_type": "kyc_lrs_folio", "status": "paid", "failure": null, "created_at": "2026-11-03T05:12:40Z", "expires_at": "2026-11-10T05:12:40Z", "updated_at": "2026-11-03T06:02:11Z", "customer_id": "cust_6819d7d0lrLvP", "scheme": { "scheme_code": "SCH001", "name": "Example Global Equity Fund - Regular Plan", "plan": "regular", "distributor_arn": "ARN12345" }, "amount": { "value": 500000, "currency": "USD" }, "expected_entities": [ "kyc", "folio", "order", "payments", "folio_transaction" ], "entities": { "kyc": { "id": "kyc_6819d8046mpKt", "status": "completed", "failure_reason": null, "bank_enabled": true, "updated_at": "2026-11-03T05:40:02Z" }, "folio": null, "order": { "id": "order_678a4c88hpAjf", "status": "paid", "expires_at": "2026-11-04T05:45:00Z", "updated_at": "2026-11-03T06:01:58Z" }, "payments": [ { "id": "payt_6819e5b1nTzXc", "status": "success", "amount": 500000, "currency": "USD", "method": "pay_via_bank", "payer": { "name": "Asha Verma", "country": "IND", "bank_name": "HDFC bank", "account_number": "••••1234" }, "paid_at": "2026-11-03T06:01:55Z", "error_code": null, "error_message": null, "updated_at": "2026-11-03T06:01:58Z" } ], "folio_transaction": null }, "failure_reason": null } }, "failed": { "summary": "Failed at KYC", "value": { "id": "psess_6819d9a1bXcVq", "session_type": "kyc_lrs", "status": "failed", "failure": { "code": "kyc_rejected", "message": "KYC verification was rejected" }, "created_at": "2026-11-02T10:04:12Z", "expires_at": "2026-11-09T10:04:12Z", "updated_at": "2026-11-02T11:30:47Z", "customer_id": "cust_6819d9b0pRtYw", "scheme": null, "amount": null, "expected_entities": [ "kyc", "order", "payments" ], "entities": { "kyc": { "id": "kyc_6819d9c2mNbVc", "status": "failed", "failure_reason": "Rejected due to unmet compliance requirements", "bank_enabled": true, "updated_at": "2026-11-02T11:30:45Z" }, "order": null, "payments": [] }, "failure_reason": "KYC verification was rejected" } } } } } }, "401": { "description": "Unauthorized — missing or invalid JWT token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Invalid or missing authentication token" } } } } } }, "404": { "description": "Not found — no session with this ID belongs to your business or is credited to you as a distributor.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "PaymentSession not found" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/distributor-links": { "post": { "tags": [ "distributor_link" ], "summary": "Create a distributor link", "description": "Creates a reusable link for one of a fund's schemes. Share the returned `url` with any number of investors: each open starts a new payment session for the scheme, credited to the distributor, prefilled with the scheme, the distributor's ARN, and the amount and sub-distributor code if they were set. The link does not expire; it stops working when the relationship with the fund is disabled, the scheme is no longer allowed or is closed, or the link is disabled.\n\nA distributor calls it for a scheme the fund has enabled for it. A fund can call it for one of its own schemes.\n\nDistributor links are enabled per business. Contact support if you receive `Feature not enabled`. See [One Click Distributor Link](/capital-markets/distributor/share-a-link) for the full flow.\n", "operationId": "createDistributorLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scheme_code" ], "properties": { "scheme_code": { "type": "string", "description": "The scheme to sell. Must be a scheme the fund has enabled for the distributor. Matching ignores case and surrounding spaces.\n", "example": "SCH001" }, "amount": { "type": "integer", "description": "Optional amount to prefill, in cents of USD. Must be a positive integer within the scheme's fresh-purchase limits. The investor can change it. There is no currency field: schemes are in USD.\n", "example": 500000 }, "distributor_arn": { "type": "string", "description": "Optional. For a distributor, it must match its ARN for the fund, with or without the fund's prefix; left out, the ARN from the relationship is used. For a fund creating its own link, an ARN with the fund's prefix, saved as an editable prefill.\n", "example": "ARN-123456" }, "sub_distributor_code": { "type": "string", "maxLength": 20, "description": "Optional code of the sub-broker who sourced the investment, sent to the RTA so the commission is credited to them. Surrounding spaces are trimmed. Every session opened from the link is prefilled with it, and the investor can change it.\n", "example": "SUB00123" } } }, "example": { "scheme_code": "SCH001", "amount": 500000, "sub_distributor_code": "SUB00123" } } } }, "responses": { "201": { "description": "Link created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The link id (`shl_` prefix). Also the last part of `url`.", "example": "shl_q6af9kKWKaXV4LH8XNVliBrc" }, "link_type": { "type": "string", "description": "What the link opens. Always `payment_session`.", "example": "payment_session" }, "url": { "type": "string", "description": "The URL to share, on the fund's checkout domain.", "example": "https://pay.example-fund.com/shared-link/shl_q6af9kKWKaXV4LH8XNVliBrc" }, "status": { "type": "string", "enum": [ "active", "disabled", "unavailable" ], "description": "`active` when the link can be opened. `unavailable` when the relationship or the scheme no longer allows it. `disabled` when the link was disabled.\n", "example": "active" }, "details": { "type": "object", "description": "What the link sells. Product and distributor details only.", "properties": { "fund_name": { "type": "string", "example": "Example Fund" }, "scheme_code": { "type": "string", "example": "SCH001" }, "scheme_name": { "type": "string", "example": "Example Global Equity Fund" }, "plan": { "type": "string", "example": "regular" }, "distributor_name": { "type": [ "string", "null" ], "description": "The distributor's name. `null` on a fund's own link.", "example": "Example Distributor" }, "distributor_arn": { "type": [ "string", "null" ], "example": "ARN-123456" }, "amount": { "type": [ "integer", "null" ], "description": "The prefilled amount in cents of USD, or `null`.", "example": 500000 }, "sub_distributor_code": { "type": [ "string", "null" ], "description": "The prefilled sub-distributor code, or `null`.", "example": "SUB00123" } } }, "openings_count": { "type": "integer", "description": "How many payment sessions the link has started.", "example": 0 }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-09T10:30:00Z" } } }, "example": { "id": "shl_q6af9kKWKaXV4LH8XNVliBrc", "link_type": "payment_session", "url": "https://pay.example-fund.com/shared-link/shl_q6af9kKWKaXV4LH8XNVliBrc", "status": "active", "details": { "fund_name": "Example Fund", "scheme_code": "SCH001", "scheme_name": "Example Global Equity Fund", "plan": "regular", "distributor_name": "Example Distributor", "distributor_arn": "ARN-123456", "amount": 500000, "sub_distributor_code": "SUB00123" }, "openings_count": 0, "created_at": "2026-10-09T10:30:00Z" } } } }, "400": { "description": "Bad request — distributor links are not enabled for the business (`Feature not enabled`), or a validation error: a blank or missing `scheme_code`, an `amount` that is not a positive integer, or a `sub_distributor_code` longer than 20 characters. Validation errors carry a `Validation failed: ` prefix in `message`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Feature not enabled" } } } } } }, "401": { "description": "Unauthorized — missing or invalid JWT token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Missing token" } } } } } }, "403": { "description": "Forbidden — `No active relationship with this fund`, or `Scheme not enabled for this relationship`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "message": { "type": "string", "example": "No active relationship with this fund" } } } } } }, "404": { "description": "Not found — `scheme_code` does not match an active scheme you can use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Scheme not found" } } } } } }, "422": { "description": "Unprocessable — `distributor_arn does not match the registered ARN`, `Amount must be between and USD`, `Scheme is not available for distribution` (a direct plan), or `Fund is not configured for scheme sessions`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unprocessable Entity" }, "message": { "type": "string", "example": "distributor_arn does not match the registered ARN" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/investor-journey": { "post": { "tags": [ "investor_journey" ], "summary": "Create investor journey", "description": "Creates an investor portal URL for the given email, PAN, and scheme. Requires a platform merchant JWT.\n", "operationId": "createInvestorJourney", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "pan", "scheme_no" ], "properties": { "email": { "type": "string", "format": "email", "description": "The investor's email address. Surrounding whitespace is removed and the address is lower-cased before it is checked. The part before `@` can be at most 64 characters, with no leading, trailing or consecutive dots; the domain must contain a dot and end in a top-level domain of 2–63 letters; and the whole address can be at most 254 characters. An invalid address returns `400`.\n", "example": "investor@example.com" }, "pan": { "type": "string", "pattern": "^[A-Z]{3}P[A-Z][0-9]{4}[A-Z]$", "description": "The investor's PAN: five letters, four digits and a final letter, where the fourth letter must be `P`. Surrounding whitespace is removed before the check. An invalid PAN returns `400`.\n", "example": "ABCPD1234E" }, "scheme_no": { "type": "string", "example": "HGEMR" } } }, "example": { "email": "investor@example.com", "pan": "ABCPD1234E", "scheme_no": "HGEMR" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The investor portal URL to send the investor to. The journey details travel encrypted in the URL fragment (`#payload=…`), so pass the URL on unchanged.\n", "example": "https://investor-portal.glomopay.com#payload=..." } } }, "example": { "url": "https://investor-portal.glomopay.com#payload=..." } } } }, "400": { "description": "Bad Request — validation failed (email/PAN), or scheme_no is unknown or not owned by a child merchant of this platform.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bad Request" }, "message": { "type": "string", "example": "Scheme not found" } } }, "examples": { "validation_failed": { "summary": "Invalid PAN or email", "value": { "error": "Bad Request", "message": "Validation failed: Pan is not a valid PAN number" } }, "scheme_not_found": { "summary": "Unknown or unowned scheme", "value": { "error": "Bad Request", "message": "Scheme not found" } } } } } }, "401": { "description": "Unauthorized — missing/invalid JWT, or the caller is not a platform merchant.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Access restricted to platform businesses only" } } }, "examples": { "missing_token": { "summary": "Missing JWT", "value": { "error": "Unauthorized", "message": "Missing token" } }, "not_platform": { "summary": "Non-platform merchant token", "value": { "error": "Unauthorized", "message": "Access restricted to platform businesses only" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/rfis": { "get": { "tags": [ "rfi" ], "summary": "List RFIs", "description": "Returns your business's RFIs across every entity type — payments, payins, payouts, refunds, orders and subscriptions — not just a single resource. Use `status` and `search` to filter the list, and the pagination parameters to page through results. Results are ordered by `created_at` descending.\n", "operationId": "getRfis", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "action_required", "under_review", "approved", "rejected", "superseded", "expired", "cancelled" ] }, "description": "Filter RFIs by status.", "example": "approved" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Filter by an exact match on either the RFI's `id` or the underlying entity's `id`.\n", "example": "rfi_6a7c5018ZGuKP" }, { "$ref": "#/components/parameters/BeforeParam" }, { "$ref": "#/components/parameters/AfterParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "$ref": "#/components/parameters/PageParam" } ], "responses": { "200": { "description": "List of RFIs matching the filters", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RfiListItem" } }, "page_meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "400": { "description": "Bad Request. The `status` filter is not a recognized value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "Validation failed: Status not_a_real_status is not a valid status" } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "JWT": [] } ] } }, "/rfis/{id}": { "get": { "tags": [ "rfi" ], "summary": "Fetch an RFI", "description": "Returns the full detail of a single RFI, including its status, the documents required to resolve it, the instructions to follow, and any reviewer or uploader comments. The RFI is looked up by its `id` (starting with `rfi_`), exposed on the underlying resource (for example the `rfi` object on a Payment) or in the [List RFIs](/api-reference/openapi/rfi/getrfis) response.\n\nAn RFI belonging to a different business, or an unknown `id`, returns `404` — the response does not distinguish the two, so RFI existence is not leaked.\n", "operationId": "getRfi", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the RFI to fetch. Starts with `rfi_`.", "example": "rfi_6a7c5018ZGuKP" } ], "responses": { "200": { "description": "The RFI detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RfiDetail" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "The RFI could not be found, or does not belong to your business.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } } }, "security": [ { "JWT": [] } ] } }, "/rfis/{id}/respond": { "patch": { "tags": [ "rfi" ], "summary": "Respond to an RFI", "description": "Submits the documents requested by a Request for Information (RFI). An RFI is raised when Glomo's compliance checks need additional information — for example, a sanctions-screening hold — before a transaction can be completed. Respond to it using the RFI `id` exposed on the underlying resource (for example, the `rfi.id` field on a Payment), or from the `rfi` webhook sent when the RFI is raised. Payout RFIs can be answered here too; the payout object and payout webhooks don't include the RFI `id`, so take it from the `rfi` webhook. See [Handle RFI for a Payout](/request-for-information/handle-rfi-for-a-payout).\n\nUpload each document first using the [Create a Document](/api-reference/openapi/document/createdocument) endpoint, then submit the resulting `doc_id` (or `doc_ids`) against the matching `rfi_doc_id` from the RFI's `documents_required` list. Once the documents are submitted successfully, the RFI status transitions to `submitted` and the final decision is communicated via the [`rfi` webhook](/platform/webhooks/rfi).\n\nFor RFIs that also ask for structured values, read them from the RFI's `fields_required` list and send them as a `fields` object.\n", "operationId": "respondRfi", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the RFI to respond to. Starts with `rfi_`.", "example": "rfi_6a72a39b38jDD" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "minItems": 1, "description": "The documents being submitted in response to the RFI. At least one document is required.\n", "items": { "type": "object", "properties": { "rfi_doc_id": { "type": "string", "description": "The identifier of the RFI document requirement this document satisfies, taken from the `documents_required` list on the underlying resource's `rfi` object. Starts with `rfidoc_`.\n", "example": "rfidoc_6a7c5018sI3ht" }, "doc_id": { "type": "string", "description": "The identifier of a single uploaded document, returned by the Create a Document endpoint. Provide either `doc_id` or `doc_ids`. Starts with `doc_`.\n", "example": "doc_6a79c6c4SbTxf" }, "doc_ids": { "type": "array", "items": { "type": "string" }, "description": "The identifiers of multiple uploaded documents satisfying this requirement. Provide either `doc_id` or `doc_ids`.\n", "example": [ "doc_6a79c6c4SbTxf" ] } }, "required": [ "rfi_doc_id" ], "additionalProperties": false } }, "fields": { "type": "object", "description": "The structured values requested by the RFI, keyed by the `name` of each entry in its `fields_required` list.\n", "additionalProperties": true, "example": { "invoice_number": "INV-2091", "invoice_date": "2026-08-20", "invoice_amount": 1250000, "invoice_currency": "INR", "customer_name": "Rohan Textiles Pvt Ltd", "customer_address": { "address_line1": "14 Mint Street", "city": "Chennai", "administrative_area": "Tamil Nadu", "postal_code": "600001", "country_code": "IND" } } }, "uploader_comments": { "type": "string", "description": "An optional note recorded against the RFI alongside the submitted documents.\n", "example": "Passport attached for review" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The RFI response was submitted successfully; the RFI transitions to `submitted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rfi" } } } }, "400": { "description": "Bad request.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "must provide doc_id or doc_ids" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden. The RFI belongs to a different business." }, "404": { "description": "The RFI, or a referenced document, could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFound" } } } }, "422": { "description": "The RFI is not awaiting information — for example, it has already been submitted, or is approved, rejected, superseded, expired, or cancelled — and cannot be responded to.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Unprocessable Entity" ] }, "message": { "type": "string", "description": "Error message.\n", "example": "RFI information has already been submitted" } } } } } } }, "security": [ { "JWT": [] } ] } }, "/api-keys/rotate": { "post": { "tags": [ "api_key" ], "summary": "Rotate API key", "description": "Rotates the secret API key for your account, generating a new key immediately. The previous key remains valid until `expire_after_in_seconds` has elapsed, giving you time to update your integrations. Once the expiry period passes, the old key is revoked and any requests using it will return `401 Unauthorized`.\n", "operationId": "rotateApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expire_after_in_seconds" ], "properties": { "expire_after_in_seconds": { "type": "integer", "minimum": 0, "maximum": 604800, "description": "Duration (in seconds) for which the previous key remains valid after rotation. Must be an integer between 0 and 604800 (7 days), sent as a JSON number. A value outside that range, or a string such as `\"3600\"`, returns `400`. Use this window to update all integrations before the old key is revoked.\n", "example": 3600 } } } } } }, "responses": { "200": { "description": "API key rotated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret_key": { "type": "string", "description": "The newly generated secret API key. Store it securely — it will not be shown again.", "example": "" }, "previous_key_expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp (UTC) at which the previous key will be revoked.", "example": "2026-05-13T12:10:57Z" } } } } } }, "400": { "description": "Bad request — invalid `expire_after_in_seconds` value", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Bad Request" ] }, "message": { "type": "string" } } }, "examples": { "non_integer": { "summary": "Non-integer value passed", "value": { "error": "Bad Request", "message": "Validation failed: Expire after in seconds must be an integer" } }, "out_of_range": { "summary": "Value outside allowed range (0–604800)", "value": { "error": "Bad Request", "message": "Validation failed: Expire after in seconds must be between 0 and 604800" } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Unauthorized" ] }, "message": { "type": "string" } } }, "example": { "error": "Unauthorized", "message": "Missing token" } } } } }, "security": [ { "JWT": [] } ] } } }, "components": { "securitySchemes": { "JWT": { "description": "Your secret token to access the API. If you don't have one, please contact support.", "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Balance": { "type": "object", "x-tags": [ "Balance" ], "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "amount": { "type": "number", "description": "The balance amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 } } }, "AllBalances": { "type": "object", "x-tags": [ "Balance" ], "properties": { "available": { "description": "The available balance for all currencies. Each entry's `amount` is in the smallest unit of its `currency`.\n", "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "amount": { "type": "number", "description": "The balance amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 } } } }, "pending": { "description": "The pending balance for all currencies. Each entry's `amount` is in the smallest unit of its `currency`.\n", "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "amount": { "type": "number", "description": "The balance amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 } } } }, "deficit": { "description": "The amount owed to Glomo, for all currencies. Each entry's `amount` is in the smallest unit of its `currency`. This is non-zero when a chargeback or RFI debit was applied against an insufficient balance; it is cleared automatically on your next top-up.\n", "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "amount": { "type": "number", "description": "The balance amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 } } } }, "funded_balances": { "description": "The Funded Balance, broken down by state, with every `amount` in the smallest unit of its `currency`. This key is present only for merchants on the Funded Balance model; it is absent for all other merchants.\n", "type": "object", "properties": { "available": { "description": "The available balance, by currency, that can be drawn for debits. Each entry's `amount` is in the smallest unit of its `currency`.\n", "type": "array", "items": { "$ref": "#/components/schemas/Balance" } }, "pending": { "description": "The pending balance, by currency, awaiting maturity to available. Each entry's `amount` is in the smallest unit of its `currency`.\n", "type": "array", "items": { "$ref": "#/components/schemas/Balance" } }, "deficit": { "description": "The amount, by currency, owed to Glomo. Each entry's `amount` is in the smallest unit of its `currency`. This is non-zero when a chargeback or RFI debit was applied against an insufficient Funded Balance; it is cleared automatically on your next Add Balance top-up.\n", "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } } } }, "Money": { "type": "object", "properties": { "amount": { "type": "number", "description": "A positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } }, "ConversionRate": { "type": "object", "x-tags": [ "ConversionRate" ], "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "rate": { "type": "number", "description": "Units of the currency converted to (`to.currency`) per one unit of the currency converted from (`from.currency`), rounded to 2 decimal places. `1.4` means 1 unit of the source currency converts to 1.40 of the target currency. `0` when no rate was recorded.\n", "example": 1.4 } } }, "BalanceConversion": { "type": "object", "x-tags": [ "balance_conversions" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the balance balance.\n", "example": "conv_6776d57dnbTWj" }, "from": { "type": "object", "$ref": "#/components/schemas/Money", "description": "the amount and currency of the balance used for conversion\n" }, "to": { "type": "object", "$ref": "#/components/schemas/Money", "description": "the amount and currency of the balance after conversion\n" }, "fees": { "type": "object", "$ref": "#/components/schemas/Money", "description": "Total fees for the conversion\n" }, "mid_market_rate": { "type": "object", "$ref": "#/components/schemas/ConversionRate", "description": "The mid-market rate at the time of conversion\n" }, "status": { "type": "string", "readOnly": true, "enum": [ "pending", "success", "failed" ], "description": "The status of the balance conversion.\n\n- `pending` — the conversion has been created and has not completed yet.\n- `success` — the converted amount has been credited. Terminal.\n- `failed` — the conversion did not complete. Terminal.\n", "example": "success" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the balance conversion was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-01-01T00:00:00Z" } } }, "PageMeta": { "type": "object", "properties": { "current": { "type": "integer", "description": "The current page number.\n", "example": 2 }, "previous": { "type": [ "integer", "null" ], "description": "The previous page number.\n", "example": 1 }, "next": { "type": [ "integer", "null" ], "description": "The next page number.\n", "example": 3 }, "per_page": { "type": "integer", "description": "The number of items per page.\n", "example": 20 }, "pages": { "type": "integer", "description": "The total number of pages.\n", "example": 10 }, "count": { "type": "integer", "description": "The total number of items.\n", "example": 200 } } }, "BankAccountValidation": { "type": "object", "x-tags": [ "bank_account_validation" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the bank account validation.\n", "example": "aval_5JU9yv0lGSUP" }, "status": { "type": "string", "enum": [ "success", "failed" ], "description": "The status of the bank account validation. This does not mean the bank account is valid or invalid. It means the validation process was successful or failed.\n" }, "validation_message": { "type": "string", "description": "The message returned by the bank account validation process.\n", "example": "The account is registered to John Doe" }, "fee_charged": { "type": [ "object", "null" ], "description": "The fee charged for the bank account validation. `null` when no fee was charged.\n", "properties": { "cents": { "type": "integer", "description": "The fee in the smallest unit of `currency_iso` (cents for USD). `100` is $1.00 when `currency_iso` is USD.\n", "example": 100 }, "currency_iso": { "type": "string", "description": "The currency of the fee, as an uppercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Always `USD`.\n", "example": "USD" } } } } }, "BankAccount": { "type": "object", "x-tags": [ "bank_account" ], "properties": { "country": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country where the customer is located. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code, case-insensitive.\n", "example": "Ind" }, "holder_name": { "type": "string", "description": "The name of the account holder.\n", "example": "John Doe" }, "account_number": { "type": "string", "description": "The account number of the bank account as provided by the bank.\n", "example": "987654321001" }, "bic_primary": { "type": "string", "description": "The primary BIC of the bank account. This is the BIC of the bank where the account is held. This is also known as the SWIFT code.\n", "example": "QWERIN000" }, "bic_secondary": { "type": "string", "description": "The `local routing code` or `domestic clearing code` of the bank account. For reference, this is the `IFSC` code in India, `SORT` in UK, `ABA` in the US, etc.\n", "example": "YESB0000002" } } }, "Notes": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. Your account may require some `notes` fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns `422` with `Validation failed: Notes is required`, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the `422` names each missing one: add that key to `notes` with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See [Custom fields](/payin/custom-fields). Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.\n", "example": { "invoice_ref": "INV-2026-001", "project": "Alpha" } }, "BeneficiaryV2": { "type": "object", "x-tags": [ "beneficiary_v2" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the beneficiary.\n", "example": "ben_5JU9yv0lGSUP" }, "name": { "type": "string", "description": "The name of the beneficiary.\n", "example": "ACME Corporation" }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "The type of beneficiary.\n", "example": "business" }, "category": { "type": "string", "enum": [ "payout", "lrs" ], "readOnly": true, "description": "The category of the beneficiary.\n", "example": "payout" }, "email": { "type": "string", "format": "email", "description": "The email address of the beneficiary.\n", "example": "finance@acme.com" }, "phone": { "type": "string", "description": "The phone number of the beneficiary.\n", "example": "+1-555-123-4567" }, "nickname": { "type": "string", "description": "A nickname for the beneficiary. If not provided, auto-generated as \"{beneficiary_name} - {bank_name}\".\n", "example": "ACME Primary Account" }, "address": { "type": "object", "description": "The address of the beneficiary.\n", "properties": { "address_line1": { "type": "string", "description": "The street address of the beneficiary.", "example": "123 Business Park" }, "address_line2": { "type": "string", "description": "The second line of street address of the beneficiary.", "example": "Suite 100" }, "city": { "type": "string", "description": "The city where the beneficiary is located.", "example": "New York" }, "state": { "type": "string", "description": "The state or administrative area where the beneficiary is located.", "example": "NY" }, "country_code": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country where the beneficiary is located. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "USA" }, "postal_code": { "type": "string", "description": "The postal code of the beneficiary's address.", "example": "10001" } } }, "bank_account": { "type": "object", "description": "The bank account details of the beneficiary.\n", "properties": { "account_number": { "type": "string", "description": "The account number of the beneficiary.", "example": "1234567890" }, "name": { "type": "string", "description": "The name of the bank where the account is held.", "example": "Citibank NA" }, "swift_code": { "type": "string", "description": "The SWIFT/BIC code of the bank. Must be 8-11 characters with first 6 being letters only.\n", "example": "CITIUS33" }, "local_routing_number": { "type": "string", "description": "The local routing code or domestic clearing code of the bank account. For reference, this is the IFSC code in India, SORT in UK, ABA in the US, etc.\n", "example": "021000089" }, "currency": { "type": "string", "description": "The currency of the bank account.", "example": "USD" }, "address": { "type": "object", "description": "The address of the bank.", "properties": { "address_line1": { "type": "string", "description": "The street address of the bank.", "example": "388 Greenwich Street" }, "address_line2": { "type": "string", "description": "The second line of street address of the bank.", "example": "" }, "city": { "type": "string", "description": "The city where the bank is located.", "example": "New York" }, "state": { "type": "string", "description": "The state or administrative area where the bank is located.", "example": "NY" }, "country_code": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country where the bank is located. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "USA" }, "postal_code": { "type": "string", "description": "The postal code of the bank's address.", "example": "10013" } } }, "intermediate_bank": { "type": "object", "description": "Details of the intermediate/correspondent bank. Present for LRS category beneficiaries (swift_code is required at creation). May be null for payout category beneficiaries.\n", "properties": { "name": { "type": "string", "description": "The name of the intermediate bank.", "example": "JPMorgan Chase Bank" }, "country": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country of the intermediate bank. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "USA" }, "swift_code": { "type": "string", "description": "The SWIFT code of the intermediate bank.", "example": "CHASUS33" }, "account_number": { "type": "string", "description": "The account number at the intermediate bank.", "example": "123456789" } } } } }, "status": { "type": "string", "enum": [ "pending", "active", "rejected" ], "readOnly": true, "description": "The current review status of the beneficiary.\n\n- `active` — the beneficiary can receive payouts.\n- `rejected` — the beneficiary did not pass review and cannot receive payouts. Terminal.\n", "example": "pending" }, "documents": { "type": "array", "readOnly": true, "description": "List of document IDs attached to the beneficiary.\n", "items": { "type": "string" }, "example": [ "doc_68e7980auYRAs" ] }, "upi_account": { "type": [ "object", "null" ], "description": "The UPI account details of the beneficiary. Present when the beneficiary uses UPI, otherwise null.\n", "properties": { "upi_id": { "type": "string", "description": "The UPI ID of the beneficiary.", "example": "1111111111@ybl" } } }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "Timestamp representing when the beneficiary was created in ISO 8601 format.\n", "example": "2025-01-15T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "Timestamp representing when the beneficiary was last updated in ISO 8601 format.\n", "example": "2025-01-15T10:00:00Z" }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "BeneficiaryV2CreateRequest": { "type": "object", "required": [ "category", "beneficiary" ], "properties": { "category": { "type": "string", "enum": [ "payout", "lrs" ], "description": "The category of the beneficiary.\n\n- `payout` - the primary use case. Processes a payout from your Glomo balance.\n- `lrs` - a specific case. Processes an LRS (Liberalised Remittance Scheme) payin whose funds\n go directly to a customer-specific bank account rather than into your Glomo balance.\n\n\nAn **account funding** beneficiary uses `payout`. It is the customer's own account - the account\nthe card funds are credited to - not a third party.\n", "example": "payout" }, "beneficiary": { "type": "object", "required": [ "name", "type", "address" ], "description": "The beneficiary details including name, contact information, and address.\n", "properties": { "name": { "type": "string", "description": "The name of the beneficiary. This is a required field. Reserved sandbox test values: `jexru7`, `nerqu8`, `havku9`, `dexru6` and `renvak4` (any letter case) force a sanctions-screening hit when a payout to this beneficiary is screened.\n", "example": "ACME Corporation" }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "The type of beneficiary. Must be either `individual` or `business`.\n", "example": "business" }, "email": { "type": "string", "format": "email", "description": "The email address of the beneficiary.\n", "example": "finance@acme.com" }, "phone": { "type": "string", "description": "The phone number of the beneficiary.\n", "example": "+1-555-123-4567" }, "nickname": { "type": "string", "description": "A nickname for the beneficiary. If not provided, it will be auto-generated as \"{beneficiary_name} - {bank_name}\".\n", "example": "ACME Primary Account" }, "address": { "type": "object", "required": [ "address_line1", "city", "state", "country_code" ], "description": "The address of the beneficiary. `address_line1`, `city`, `state` and `country_code` are required; `address_line2` and `postal_code` are optional.\n", "properties": { "address_line1": { "type": "string", "description": "The street address of the beneficiary (required).", "example": "123 Business Park" }, "address_line2": { "type": "string", "description": "The second line of street address of the beneficiary (optional).", "example": "Suite 100" }, "city": { "type": "string", "description": "The city where the beneficiary is located (required).", "example": "New York" }, "state": { "type": "string", "description": "The state or administrative area where the beneficiary is located (required).", "example": "NY" }, "country_code": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country where the beneficiary is located (required). Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "USA" }, "postal_code": { "type": "string", "description": "The postal code of the beneficiary's address (optional).", "example": "10001" } } }, "documents": { "type": "array", "description": "Optional list of document IDs to attach to the beneficiary.\n", "items": { "type": "string" }, "example": [ "doc_68e7980auYRAs" ] } } }, "bank_account": { "type": "object", "required": [ "account_number", "currency" ], "description": "The bank account details of the beneficiary.\n\nFor `category: payout`, `name` and `address` are resolved from the `swift_code`, the\n`local_routing_number`, or an IBAN `account_number`. Send them only if the identifier cannot be\nresolved, or to override the resolved values. Both remain required for `category: lrs`.\n\nRouting identifier rules differ by category:\n\n- `category: lrs` — `local_routing_number` is required. `swift_code` is optional.\n- `category: payout` — provide exactly one of `swift_code` or `local_routing_number`, except\n for EUR and AED accounts identified by an IBAN alone, which send neither.\n\nFor the rails each identifier maps to, see\n[Payout rails](/payout/rails).\n", "properties": { "account_number": { "type": "string", "description": "The account number of the beneficiary (required).", "example": "1234567890" }, "name": { "type": "string", "description": "The name of the bank where the account is held. Required for `category: lrs`, optional for `category: payout`.\n", "example": "Citibank NA" }, "swift_code": { "type": "string", "description": "The SWIFT/BIC code of the bank. Must be 8-11 characters with first 6 being letters only. For LRS category it is optional, and must be exactly 8 characters (no branch suffix like XXX). For payout category, see [Payout rails](/payout/rails).\n", "example": "CITIUS33" }, "local_routing_number": { "type": "string", "description": "The local routing code or domestic clearing code of the bank account. Required for LRS category, optional for payout category. For reference, this is the IFSC code in India, the sort code in the UK, ABA in the US, etc. For payout category, see [Payout rails](/payout/rails).\n", "example": "021000089" }, "currency": { "type": "string", "description": "The currency of the bank account (required).", "example": "USD" }, "address": { "type": "object", "required": [ "address_line1", "city", "state", "country_code" ], "description": "The address of the bank. Required for `category: lrs`, optional for `category: payout`. When sent, `address_line1`, `city`, `state` and `country_code` are required; `address_line2` and `postal_code` are optional.\n", "properties": { "address_line1": { "type": "string", "description": "The street address of the bank (required).", "example": "388 Greenwich Street" }, "address_line2": { "type": "string", "description": "The second line of street address of the bank (optional).", "example": "" }, "city": { "type": "string", "description": "The city where the bank is located (required).", "example": "New York" }, "state": { "type": "string", "description": "The state or administrative area where the bank is located (required).", "example": "NY" }, "country_code": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country where the bank is located (required). Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "USA" }, "postal_code": { "type": "string", "description": "The postal code of the bank's address (optional).", "example": "10013" } } }, "intermediate_bank": { "type": "object", "description": "Details of the intermediate/correspondent bank. **`swift_code` is required for LRS category beneficiaries.** Optional for payout category beneficiaries.\n", "properties": { "name": { "type": "string", "description": "The name of the intermediate bank (optional).", "example": "JPMorgan Chase Bank" }, "country": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country of the intermediate bank (optional). Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "USA" }, "swift_code": { "type": "string", "description": "The SWIFT/BIC code of the correspondent/intermediary bank used to route the remittance. Required for LRS category, optional for payout category.\n", "example": "CHASUS33" }, "account_number": { "type": "string", "description": "The account number at the intermediate bank (optional).", "example": "123456789" } } } } }, "upi_account": { "type": "object", "description": "UPI account details. Provide either bank_account or upi_account, not both.\n", "properties": { "upi_id": { "type": "string", "description": "The UPI ID of the beneficiary.", "example": "1111111111@ybl" } } }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "EntityNotFound": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "Not found" ] }, "message": { "type": "string", "description": "Entity not found", "enum": [ "Entity not found" ] } } }, "Customer": { "type": "object", "x-tags": [ "Customer" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the customer.\n", "example": "cust_5JU9yv0lGSUP" }, "name": { "type": "string", "description": "The name of the customer. Reserved sandbox test values: `jexru7`, `nerqu8`, `havku9`, `dexru6` and `renvak4` (any letter case) force a sanctions-screening hit whenever this customer is screened.\n", "example": "John Doe" }, "customer_type": { "type": "string", "enum": [ "individual", "business" ], "description": "The type of customer\n" }, "email": { "type": "string", "format": "email", "description": "The email address of the customer.\n", "example": "customer@gmail.com" }, "phone": { "type": "string", "description": "The phone number of the customer, with country code. Phone number validation is done using the [phonelib](https://github.com/daddyz/phonelib?tab=readme-ov-file) library.\n", "example": "+91-9023456789" }, "dob": { "type": "string", "format": "date", "description": "The date of birth of the customer, as a calendar date in `YYYY-MM-DD` format with no time or time zone. Must be a date before today.\n\nOptional in general, **required for account funding** customers.\n", "example": "2003-11-29" }, "nationality": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The nationality of the customer, as an [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code. The alpha-2 form is rejected: send `IND`, not `IN`.\n\nOptional in general, **required for account funding** customers.\n", "example": "IND" }, "tax_identification_number": { "type": "string", "readOnly": true, "description": "The customer's PAN (tax identification number), derived from the `kyc.pan_number` you send at creation. `null` where you sent none, and also where PAN processing is not enabled for your account; the value you sent is stored either way. Searchable via the `tax_identification_number` query parameter on the list-customers endpoint.\n", "example": "BFQPG7654R" }, "kyc": { "type": "object", "writeOnly": true, "additionalProperties": false, "description": "The KYC records you already hold for this customer. Accepts exactly the two fields below.\n", "properties": { "pan_number": { "type": "string", "description": "The customer's PAN. Surfaces on the customer as `tax_identification_number`. Required for LRS customers in India.\n", "example": "BFQPG7654R" }, "last_kyc_date": { "type": "string", "format": "date", "description": "When you last completed KYC on this customer, as `YYYY-MM-DD`. Cannot be in the future.\n", "example": "2026-02-14" } } }, "address": { "type": "string", "description": "The street address of the customer.\n", "example": "123 Main St" }, "city": { "type": "string", "description": "The city where the customer is located.\n", "example": "Anytown" }, "state": { "type": "string", "description": "The state where the customer is located.\n", "example": "Anystate" }, "country": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country where the customer is located. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "IND" }, "pincode": { "type": "string", "description": "The postal code/pincode of the customer's address. [List of countries where pincode is mandatory](/platform/countries#countries-requiring-pincode) are listed here.\n", "example": "560048" }, "status": { "type": "string", "readOnly": true, "description": "The status of the customer.\n", "example": "active" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the customer was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the customer was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" } } }, "CustomerBankAccount": { "type": "object", "description": "A bank account registered against a customer.\n", "properties": { "id": { "type": "string", "description": "Unique identifier of the bank account.", "readOnly": true, "example": "acccus_6a5f1c92Xq4Wd" }, "account_number": { "type": "string", "description": "The customer's bank account number or IBAN. Masked in every response, showing only the last four characters.\n", "example": "50100123456789" }, "bank_name": { "type": "string", "description": "Name of the bank holding the account.", "example": "HDFC bank" }, "bic_primary": { "type": "string", "description": "SWIFT/BIC code of the bank. Provide this or `bic_secondary`.\n", "example": "HDFCINBBXXX" }, "bic_secondary": { "type": "string", "description": "Local routing code of the bank — IFSC in India, sort code in the United Kingdom, ABA routing number in the United States. Provide this or `bic_primary`.\n", "example": "HDFC0000123" }, "holder_name": { "type": "string", "description": "Name on the account. Always the customer's own name, so it is derived from the customer and cannot be set on the request.\n", "readOnly": true, "example": "Priya Raghunathan" } } }, "LrsCustomerBankAccount": { "type": "object", "description": "The Indian bank account an LRS remittance is debited from. Pass its `id` as `lrs.bank_account_id` on an LRS order.\n", "properties": { "id": { "type": "string", "readOnly": true, "description": "Unique identifier of the LRS bank account. It starts with `acclrs_`.\n", "example": "acclrs_68468c03g9xt7" }, "bank_code": { "type": "string", "description": "Code of the customer's bank. Must be a `bank_code` returned by `GET /lrs/banks` for your account, matched exactly and case-sensitively. An LRS order that uses this account must use a quote created for the same `bank_code`, or the order is rejected.\n", "example": "hdfc" }, "account_number": { "type": "string", "description": "The customer's account number at that bank. Digits only, with a length inside the range that bank accepts. Returned in full, as sent, in the response. In sandbox, `50100117322072` with `hdfc` and `925010000230876` with `axis` make checkout ask for a document after the OTP; any other number skips that step. See [Test it in sandbox](/payin/resident-india-remittance-under-lrs/set-up#test-it-in-sandbox).\n", "example": "12345678901234" }, "bank_customer_id": { "type": "string", "description": "Optional. The customer's identifier at their bank. For banks that use one, it must contain only digits, with a length inside the range that bank accepts; an invalid value is rejected with `400`.\n", "example": "12345678" } } }, "Document": { "type": "object", "x-tags": [ "Document" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the Document.\n", "example": "doc_nYUqLpuYQ0M8" }, "document_name": { "type": "string", "description": "The name of document\n", "example": "invoice" }, "file_name": { "type": "string", "readOnly": true, "description": "The name of the file you uploaded.\n", "example": "invoice_BC8tFdE.pdf" }, "preview_url": { "type": "string", "readOnly": true, "description": "The URL to preview the document.\n", "example": "https://glomopay-service-staging-documents.s3.ap-south-1.amazonaws.com/12345_invoice" }, "status": { "type": "string", "readOnly": true, "description": "The status of file you uploaded. Values can be uploaded, approved and rejected.\n", "example": "uploaded" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the document was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the document was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" } } }, "SplitIds": { "type": "array", "items": { "type": "string" }, "description": "The pricing splits to apply, each entry an `id` returned by [Create a pricing split](#tag/pricing_split). A split fixes your share of a dynamic rule's fee and the customer bears the remainder. Omit `split_ids` and no dynamic rule is applied — pricing falls back to your normal (non-dynamic) rules.\n\n`split_ids` and `payment_methods` are independent. `payment_methods` restricts which methods the checkout offers. `split_ids` only changes how the fee for a method is priced: a split applies to its own payment method whether or not that method appears in `payment_methods`, and a split never adds a method to the checkout or removes one from it. One checkout can therefore price one method from a dynamic split and another method from your normal rules.\n\nEvery id must exist, must belong to your business, and must still point at a live dynamic rule. When two dynamic rules share a dimension — the same payment method, subtype, rail, currency and fee type — declare a split for every one of them or the request is rejected. On payment links and orders, a split whose payment method is not enabled for your business is also rejected.\n\nA subscription only ever charges `card`, or `pay_via_bank` when SEPA-eligible, so a split declared for any other payment method is rejected at subscription creation and on an auto debit. An auto-debit override must be declared for the method the subscription actually charges.\n\nGlomo can configure your account to require a declaration. On such an account, a payment link, an order, a payin quote or an `as_presented` subscription that omits `split_ids` is rejected.\n", "example": [ "psplit_7Kq2mXbTdLp9" ] }, "Product": { "type": "object", "description": "Details of the product that the payment is related to.\n", "properties": { "name": { "type": "string", "description": "Name of the product" }, "description": { "type": "string", "description": "Description of the product" } }, "required": [ "name" ], "example": { "name": "ShieldGuard Insurance", "description": "Flexible insurance for belongings travel and digital assets easy to manage" } }, "LrsOrderDetails": { "type": "object", "description": "Send this object to create an LRS order: a remittance from a customer resident in India, funded\nfrom their Indian bank account. If you send `lrs`, `lrs_quote_id` and `remittance_information` are\nrequired.\n\n- Create the quote first with `POST /lrs/quotes`. The order's `amount` must equal the `USD` side of\n the quote (`from.amount` for a `USD` source quote, `to.amount` for an `INR` source quote), and\n `currency` must be `USD`. Otherwise the order is rejected with `400`.\n- The quote must not have expired. The order expires when the quote does.\n- The customer's country must be India, otherwise the order is rejected with `400`.\n- An LRS order doesn't store `invoice_number`, `invoice_description`, `invoice_amount`,\n `reference_number`, `document_id` or `product`; they come back as `null` or are left out. A value\n you send is still validated, so leave these fields out.\n\nReturned on the order when it was created as an LRS order.\n", "properties": { "lrs_quote_id": { "type": "string", "description": "The `id` of a quote from `POST /lrs/quotes`, created by your account.\n", "example": "quote_6ab60de4Kx7Pq" }, "remittance_information": { "type": "string", "maxLength": 20, "pattern": "^[a-zA-Z0-9-]*$", "description": "Your reference for the remittance. Up to 20 characters, using only letters, digits and hyphens; spaces and other characters are rejected with `400`.\n", "example": "REF12345" }, "bank_account_id": { "type": "string", "description": "The `id` of the customer's LRS bank account, from `POST /customer/{id}/bank_account`. Optional. It must belong to this customer and be at the same bank as the quote's `bank_code`. A bank account from `POST /customer/{id}/bank-accounts` is not accepted here.\n", "example": "acclrs_68468c03g9xt7" }, "beneficiary_id": { "type": "string", "description": "The `id` of a beneficiary created with `category: lrs` through `POST /v2/beneficiaries`, to receive the remittance. Optional.\n", "example": "bene_68468c03g9xua" } }, "required": [ "lrs_quote_id", "remittance_information" ] }, "Orders": { "type": "object", "x-tags": [ "Orders" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the order.\n", "example": "order_678a4c88hpAjf" }, "customer_id": { "type": "string", "description": "The unique identifier of customer linked to order.\n", "example": "cust_E602dMzgjpDC" }, "document_id": { "type": "string", "description": "The unique identifier of document linked to order. This document entity should contain the required documents to process incoming payments. Refer this [Document](#tag/Document) entity for more details.\n", "example": "doc_nYUqLpuYQ0M8" }, "status": { "type": "string", "readOnly": true, "enum": [ "active", "action_required", "under_review", "paid", "failed", "cancelled", "expired" ], "description": "The status of the order.\n\n- `active` — the order has been created and can be paid.\n- `action_required` — Glomo needs more information before the order can be paid. Respond to the\n open RFI to continue.\n- `under_review` — the information you submitted is being reviewed. The order returns to `active` if\n the review passes.\n- `paid` — the order has been paid in full. Terminal.\n- `failed` — the order could not be accepted, for example because the review did not pass. Terminal.\n- `cancelled` — the order was cancelled before it was paid. Terminal.\n- `expired` — the order passed its expiry time without being paid. Not always final: a payment that\n was already under way when the order expired can still complete it, moving it to `paid`.\n", "example": "active" }, "currency": { "type": "string", "format": "iso-4217", "enum": [ "USD", "EUR", "GBP", "AED", "SGD", "AUD" ], "description": "The currency the order is collected in, as an uppercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Must be one of the listed values; the match is case-sensitive. `INR` is not accepted.\n", "example": "USD" }, "amount": { "type": "number", "minimum": 1, "description": "The amount you want to receive, a positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 }, "purpose_code": { "type": "string", "description": "Why you are receiving this payment, as a code from a fixed set: see [Payin purpose codes](/payin/purpose-codes). This is not free text. Pass a listed code exactly, for example `P1401`; matching is exact and case-sensitive. Payins and payouts use different sets, so a payout code such as `S1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.\n\nOptional on orders. When omitted, Glomo applies your account's default payin purpose code if one has been configured.\n", "example": "P1401" }, "invoice_number": { "type": "string", "description": "Number/Id of the invoice submitted with order. LRS orders (sent with `lrs`) don't store this field and return it as `null`, but a value you send is still validated.\n", "example": "RG12FF590" }, "invoice_description": { "type": "string", "description": "Description about the invoice submitted with order\n", "example": "Payment requested for services provided" }, "invoice_amount": { "type": "number", "description": "The amount on the invoice, in the smallest unit of the order's `currency`, the same unit as `amount` (cents for USD). `1000` is $10.00 when `currency` is USD. Must be greater than or equal to `amount`.\n", "example": 1000 }, "reference_number": { "type": "string", "description": "optional identifier to be sent for reconciliations\n", "example": "R0001" }, "price_id": { "type": "string", "description": "The unique identifier of 'Price' entity linked to the order. This is the referral fee for this order. Note: price_id is only applicable for platform businesses.\n", "example": "price_E602dMzgjpDC" }, "split_ids": { "$ref": "#/components/schemas/SplitIds" }, "product": { "$ref": "#/components/schemas/Product" }, "notes": { "$ref": "#/components/schemas/Notes" }, "bank_account_details": { "type": "object", "description": "Optional bank account details to associate with the customer for this order. When provided, the bank account will be linked to the customer and associated with this order. Either bic_primary or bic_secondary must be provided when including this field.\n", "properties": { "account_number": { "type": "string", "description": "The bank account number\n", "example": "1234567890" }, "bic_primary": { "type": "string", "description": "SWIFT code for the bank account. Will be null if not provided in the request.\n", "example": "HDFCINBBDEL" }, "bic_secondary": { "type": "string", "description": "Local routing code for the bank account like IFSC. Will be null if not provided in the request.\n", "example": "HDFC0001097" }, "bank_customer_id": { "type": "string", "description": "Optional bank customer identifier provided by the bank\n", "example": "7189204715" } }, "required": [ "account_number" ], "example": { "account_number": "1234567890", "bic_primary": "HDFCINBBDEL", "bank_customer_id": "7189204715" } }, "lrs": { "$ref": "#/components/schemas/LrsOrderDetails" }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "bank_transfer", "pay_via_bank", "card" ] }, "description": "Array of payment methods that should be available for the customer on the checkout page. This field allows you to control which payment options your customers can use to complete the payment. You can specify one or multiple payment methods in the array. Each value must be a payment method enabled on your account; any other value is rejected with a `400`. Omit the field to offer every payment method enabled on your account.\n", "example": [ "card" ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the order was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the order was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "request_id": { "type": [ "string", "null" ], "description": "Your unique identifier for this order, used to reject duplicates. If an order with the same `request_id` already exists on your account, the request is rejected with `400` and the message `Order already exists for this request_id`; the existing order is not returned. Look it up with `GET /v1/orders?request_id=`. Returned on the order and its webhooks; `null` if you sent none.\n", "example": "unique_order_request_id_123" } } }, "OrderResponse": { "allOf": [ { "$ref": "#/components/schemas/Orders" }, { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the order.\n", "example": "order_678a4c88hpAjf" }, "status": { "type": "string", "readOnly": true, "enum": [ "active", "action_required", "under_review", "paid", "failed", "cancelled", "expired" ], "description": "The status of the order.\n\n- `active` - the order has been created and can be paid.\n- `action_required` - Glomo needs more information before the order can be paid. Respond to the\n open RFI to continue.\n- `under_review` - the information you submitted is being reviewed. The order returns to `active` if\n the review passes.\n- `paid` - the order has been paid in full. Terminal. This is the success value, not `success`.\n- `failed` - the order could not be accepted, for example because the review did not pass. Terminal.\n- `cancelled` - the order was cancelled before it was paid. Terminal.\n- `expired` - the order passed its expiry time without being paid. Not always final: a payment that\n was already under way when the order expired can still complete it, moving it to `paid`.\n", "example": "active" }, "rfi_documents": { "type": "array", "readOnly": true, "description": "List of required documents for RFI (Request for Information). This field is only present when the order status is 'action_required', indicating that sanction screening has been triggered and additional documents are required to proceed with the payment.\n", "items": { "type": "object", "properties": { "rfi_doc_id": { "type": "string", "description": "Unique identifier for the required RFI document\n", "example": "rfidoc_123" }, "name": { "type": "string", "description": "Name/type of the required document\n", "example": "Passport" } }, "required": [ "rfi_doc_id", "name" ] }, "example": [ { "rfi_doc_id": "rfidoc_123", "name": "Passport" }, { "rfi_doc_id": "rfidoc_456", "name": "Proof of Address" } ] }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the order expires, as an ISO 8601 date-time in UTC. An order created from a quote inherits the quote's expiry.\n", "example": "2026-09-24T22:15:18Z" }, "payment_methods": { "type": "array", "readOnly": true, "items": { "type": "string", "enum": [ "bank_transfer", "pay_via_bank", "card" ] }, "description": "Array of payment methods that should be available for the customer on the checkout page. This field allows you to control which payment options your customers can use to complete the payment. You can specify one or multiple payment methods in the array.\n", "example": [ "card" ] }, "bank_account_details": { "type": "object", "readOnly": true, "description": "Bank account details associated with the customer for this order. If provided in the request, all fields will be returned. If bic_primary or bic_secondary was not provided in the request, they will be null in the response.\n", "properties": { "account_number": { "type": "string", "description": "The bank account number\n", "example": "1234567890" }, "bic_primary": { "type": [ "string", "null" ], "description": "SWIFT code for the bank account. Will be null if not provided in the request.\n", "example": "HDFCINBBDEL" }, "bic_secondary": { "type": [ "string", "null" ], "description": "Local routing code for the bank account like IFSC. Will be null if not provided in the request.\n", "example": "HDFC0001097" }, "bank_customer_id": { "type": [ "string", "null" ], "description": "Bank customer identifier provided by the bank. Will be null if not provided in the request.\n", "example": "7189204715" } }, "example": { "account_number": "1234567890", "bic_primary": "HDFCINBBDEL", "bic_secondary": null, "bank_customer_id": "7189204715" } }, "partner_transaction_reference_id": { "type": "string", "readOnly": true, "description": "Transaction ID common to both partners in a partnership payment, so both partners can match the same remittance. Present only for partnership payments.\n", "example": "ptr_6819d8046mpKt" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the order was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the order was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" } } } ] }, "CreateOrderWithQuoteRequest": { "type": "object", "title": "CreateOrderWithQuoteRequest", "additionalProperties": false, "description": "Create an order against a previously generated quote (see `POST /quotes` with `resource: payin`). When supplied, the quote is the single source of truth for amount, currency, payment method and expiry. The locked fields (`amount`, `currency`, `price_id`, `payment_methods`) must NOT be sent — including any of them returns a `400 Bad Request`.\n", "properties": { "quote_id": { "type": "string", "description": "ID of a quote (from `POST /api/v1/quotes` with `resource: \"payin\"`) to bind this order to. When supplied, the quote is the single source of truth for amount, currency, payment method, and expiry.\n", "example": "quote_3m4n5o6p7q" }, "customer_id": { "type": "string", "description": "The unique identifier of customer linked to order.\n", "example": "cust_E602dMzgjpDC" }, "beneficiary_id": { "type": "string", "description": "The account the funds land in, as a beneficiary created through [`POST /v2/beneficiaries`](#tag/beneficiary_v2/operation/createBeneficiaryV2).\n\nRequired for account funding orders, where it is the customer's own account. Not used by other payin orders.\n", "example": "bene_5JU9yv0lGSUP" }, "purpose_code": { "type": "string", "description": "Why you are receiving this payment, as a code from a fixed set: see [Payin purpose codes](/payin/purpose-codes). This is not free text. Pass a listed code exactly, for example `P1401`; matching is exact and case-sensitive. Payins and payouts use different sets, so a payout code such as `S1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.\n\nOptional on orders. When omitted, Glomo applies your account's default payin purpose code if one has been configured.\n", "example": "P1401" }, "document_id": { "type": "string", "description": "The unique identifier of document linked to order. This document entity should contain the required documents to process incoming payments. Refer this [Document](#tag/Document) entity for more details.\n", "example": "doc_nYUqLpuYQ0M8" }, "invoice_number": { "type": "string", "description": "Number/Id of the invoice submitted with order.\n", "example": "RG12FF590" }, "invoice_description": { "type": "string", "description": "Description about the invoice submitted with order.\n", "example": "Payment requested for services provided" }, "invoice_amount": { "type": "number", "description": "The amount on the invoice, in the smallest unit of the quote's `destination_currency`, which is the currency the order is created in (cents for USD). `1000` is $10.00 when that currency is USD. Must be greater than or equal to the quote's `destination_amount`.\n", "example": 1000 }, "reference_number": { "type": "string", "description": "optional identifier to be sent for reconciliations.\n", "example": "R0001" }, "product": { "$ref": "#/components/schemas/Product" }, "notes": { "$ref": "#/components/schemas/Notes" }, "bank_account_details": { "type": "object", "description": "Optional bank account details to associate with the customer for this order. When provided, the bank account will be linked to the customer and associated with this order. Either bic_primary or bic_secondary must be provided when including this field.\n", "properties": { "account_number": { "type": "string", "description": "The bank account number\n", "example": "1234567890" }, "bic_primary": { "type": "string", "description": "SWIFT code for the bank account. Will be null if not provided in the request.\n", "example": "HDFCINBBDEL" }, "bic_secondary": { "type": "string", "description": "Local routing code for the bank account like IFSC. Will be null if not provided in the request.\n", "example": "HDFC0001097" }, "bank_customer_id": { "type": "string", "description": "Optional bank customer identifier provided by the bank\n", "example": "7189204715" } }, "required": [ "account_number" ], "example": { "account_number": "1234567890", "bic_primary": "HDFCINBBDEL", "bank_customer_id": "7189204715" } }, "request_id": { "type": "string", "description": "Your unique identifier for this order, used to reject duplicates. If an order with the same `request_id` already exists on your account, the request is rejected with `400` and the message `Order already exists for this request_id`; the existing order is not returned. Look it up with `GET /v1/orders?request_id=`. Resending with the same `quote_id` fails first with `400`, because the quote has already been used.\n", "example": "unique_order_request_id_123" } } }, "PaymentLink": { "type": "object", "x-tags": [ "payment_link" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the payment link.\n", "example": "plink_678a4c88hpAjf" }, "customer_id": { "type": "string", "description": "The unique identifier of customer linked to payment_link.\n", "example": "cust_E602dMzgjpDC" }, "document_id": { "type": "string", "description": "The unique identifier of document linked to payment_link. This document entity should contain the required documents to process incoming payments. Refer this [Document](#tag/Document) entity for more details.\n", "example": "doc_nYUqLpuYQ0M8" }, "status": { "type": "string", "readOnly": true, "enum": [ "active", "action_required", "under_review", "paid", "failed", "cancelled", "expired" ], "description": "The status of the payment link.\n\n- `active` — the payment link has been created and can be paid.\n- `action_required` — Glomo needs more information before the payment link can be paid. Respond to the\n open RFI to continue.\n- `under_review` — the information you submitted is being reviewed. The payment link returns to `active` if\n the review passes.\n- `paid` — the payment link has been paid in full. Terminal.\n- `failed` — the payment link could not be accepted, for example because the review did not pass. Terminal.\n- `cancelled` — the payment link was cancelled before it was paid. Terminal.\n- `expired` — the payment link passed its expiry time without being paid. Not always final: a payment that\n was already under way when the payment link expired can still complete it, moving it to `paid`.\n", "example": "active" }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "bank_transfer", "pay_via_bank", "card" ] }, "description": "Array of payment methods that should be available for the customer on the checkout page. This field allows you to control which payment options your customers can use to complete the payment. You can specify one or multiple payment methods in the array. A listed method that is not set up on your account is ignored rather than rejected.\n", "example": [ "card" ] }, "currency": { "type": "string", "format": "iso-4217", "enum": [ "USD", "EUR", "GBP", "AED", "SGD", "AUD" ], "description": "The currency the payment link is collected in, as an uppercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Must be one of the listed values; the match is case-sensitive. `INR` is not accepted.\n", "example": "USD" }, "amount": { "type": "number", "minimum": 1, "description": "The amount you want to receive, a positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 }, "purpose_code": { "type": "string", "description": "Why you are receiving this payment, as a code from a fixed set: see [Payin purpose codes](/payin/purpose-codes). This is not free text. Pass a listed code exactly, for example `P1401`; matching is exact and case-sensitive. Payins and payouts use different sets, so a payout code such as `S1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.\n\nRequired, unless Glomo has configured a default payin purpose code on your account, in which case an omitted value falls back to that default.\n", "example": "P1401" }, "invoice_number": { "type": "string", "description": "Number/Id of the invoice submitted with payment_link.\n", "example": "RG12FF590" }, "invoice_description": { "type": "string", "description": "Description about the invoice submitted with payment_link\n", "example": "Payment requested for services provided" }, "reference_number": { "type": "string", "description": "optional identifier to be sent for reconciliations\n", "example": "R0001" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the payment link expires. Send an ISO 8601 date-time with a UTC offset or `Z` (`YYYY-MM-DDThh:mm:ssZ`). A value without an offset is read as UTC, and a date without a time is read as 00:00 UTC on that day. Must be later than the time of the request and at most 6 calendar months from now. A past value returns `400` with the message `Validation failed: Expires at must be in the future`, and a value more than 6 months ahead returns `400` with `Validation failed: Expires at cannot be more than 6 months from now`. Returned in UTC.\n", "example": "2026-12-15T12:00:00Z", "x-glomo-relative-example": "P14D" }, "last_reminder_sent_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the customer was last reminded to complete the payment by visiting the link, as an ISO 8601 date-time in UTC. `null` if no reminder has been sent.\n", "example": "2024-09-13T06:32:34Z" }, "invoice_amount": { "type": "number", "description": "The amount on the invoice, in the smallest unit of the payment link's `currency`, the same unit as `amount` (cents for USD). `1000` is $10.00 when `currency` is USD. Must be greater than or equal to `amount`.\n", "example": 1000 }, "payment_link": { "type": "string", "readOnly": true, "description": "Sharable link which should be shared with customer you want to receive money from. ``` This link gets generated only after the payin has been reviewed and moved to in_progress ```\n", "example": "https://staging-api.glomopay-eng.com/v1/payin/pl/8f31597d-e085-497a-b80f-ae97ea9422a0" }, "notify_customer": { "type": "boolean", "default": true, "description": "Whether to notify the customer via email when the payment link is created. Defaults to `true`. Set to `false` to suppress the notification email.\n", "example": true }, "reminder_frequency": { "type": "number", "description": "The frequency at which you want to remind customers, valid values are 1(remind everyday), 2(remind every alternate day), 7(remind every week), 14(remind every alternate week).\n", "example": 7 }, "price_id": { "type": "string", "description": "The unique identifier of 'Price' entity linked to the payment link. This is the referral fee for this payment link. Note: price_id is only applicable for platform businesses.\n", "example": "price_E602dMzgjpDC" }, "split_ids": { "$ref": "#/components/schemas/SplitIds" }, "product": { "$ref": "#/components/schemas/Product" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the payment link was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the payment link was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "notes": { "$ref": "#/components/schemas/Notes" }, "bank_account_details": { "type": "object", "description": "Optional bank account details to associate with the customer for this payment link. When provided, the bank account will be linked to the customer and associated with this payment link. Either bic_primary or bic_secondary must be provided when including this field.\n", "properties": { "account_number": { "type": "string", "description": "The bank account number\n", "example": "1234567890" }, "bic_primary": { "type": "string", "description": "SWIFT code for the bank account. Will be null if not provided in the request.\n", "example": "HDFCINBBDEL" }, "bic_secondary": { "type": "string", "description": "Local routing code for the bank account like IFSC. Will be null if not provided in the request.\n", "example": "HDFC0001097" }, "bank_customer_id": { "type": "string", "description": "Optional bank customer identifier provided by the bank\n", "example": "7189204715" } }, "required": [ "account_number" ], "example": { "account_number": "1234567890", "bic_primary": "HDFCINBBDEL", "bank_customer_id": "7189204715" } } } }, "PaymentLinkResponse": { "allOf": [ { "$ref": "#/components/schemas/PaymentLink" }, { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the payment link.\n", "example": "plink_678a4c88hpAjf" }, "expires_at": { "example": "2021-06-15T12:00:00Z" }, "status": { "type": "string", "readOnly": true, "enum": [ "active", "action_required", "under_review", "paid", "failed", "cancelled", "expired" ], "description": "The status of the payment link.\n\n- `active` — the payment link has been created and can be paid.\n- `action_required` — Glomo needs more information before the payment link can be paid. Respond to the\n open RFI to continue.\n- `under_review` — the information you submitted is being reviewed. The payment link returns to `active` if\n the review passes.\n- `paid` — the payment link has been paid in full. Terminal.\n- `failed` — the payment link could not be accepted, for example because the review did not pass. Terminal.\n- `cancelled` — the payment link was cancelled before it was paid. Terminal.\n- `expired` — the payment link passed its expiry time without being paid. Not always final: a payment that\n was already under way when the payment link expired can still complete it, moving it to `paid`.\n", "example": "active" }, "rfi_documents": { "type": "array", "readOnly": true, "description": "List of required documents for RFI (Request for Information). This field is only present when the payment link status is 'action_required', indicating that sanction screening has been triggered and additional documents are required to proceed with the payment link.\n", "items": { "type": "object", "properties": { "rfi_doc_id": { "type": "string", "description": "Unique identifier for the required RFI document\n", "example": "rfidoc_123" }, "name": { "type": "string", "description": "Name/type of the required document\n", "example": "Passport" } }, "required": [ "rfi_doc_id", "name" ] }, "example": [ { "rfi_doc_id": "rfidoc_123", "name": "Passport" }, { "rfi_doc_id": "rfidoc_456", "name": "Proof of Address" } ] }, "payment_link": { "type": "string", "readOnly": true, "description": "Sharable link which should be shared with customer you want to receive money from. ``` This link gets generated only after the payin has been reviewed and moved to in_progress ```\n", "example": "https://staging-api.glomopay-eng.com/v1/payin/pl/8f31597d-e085-497a-b80f-ae97ea9422a0" }, "last_reminder_sent_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the customer was last reminded to complete the payment by visiting the link, as an ISO 8601 date-time in UTC. `null` if no reminder has been sent.\n", "example": "2024-09-13T06:32:34Z" }, "payment_methods": { "type": "array", "readOnly": true, "items": { "type": "string", "enum": [ "bank_transfer", "pay_via_bank", "card" ] }, "description": "Array of payment methods that should be available for the customer on the checkout page. This field allows you to control which payment options your customers can use to complete the payment. You can specify one or multiple payment methods in the array.\n", "example": [ "card" ] }, "bank_account_details": { "type": "object", "readOnly": true, "description": "Bank account details associated with the customer for this payment link. If provided in the request, all fields will be returned. If bic_primary or bic_secondary was not provided in the request, they will be null in the response.\n", "properties": { "account_number": { "type": "string", "description": "The bank account number\n", "example": "1234567890" }, "bic_primary": { "type": [ "string", "null" ], "description": "SWIFT code for the bank account. Will be null if not provided in the request.\n", "example": "HDFCINBBDEL" }, "bic_secondary": { "type": [ "string", "null" ], "description": "Local routing code for the bank account like IFSC. Will be null if not provided in the request.\n", "example": "HDFC0001097" }, "bank_customer_id": { "type": [ "string", "null" ], "description": "Bank customer identifier provided by the bank. Will be null if not provided in the request.\n", "example": "7189204715" } }, "example": { "account_number": "1234567890", "bic_primary": "HDFCINBBDEL", "bic_secondary": null, "bank_customer_id": "7189204715" } }, "partner_transaction_reference_id": { "type": "string", "readOnly": true, "description": "Transaction ID common to both partners in a partnership payment, so both partners can match the same remittance. Present only for partnership payments.\n", "example": "ptr_6819d8046mpKt" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the payment link was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the payment link was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "notes": { "$ref": "#/components/schemas/Notes" } } } ] }, "CreatePaymentLinkWithQuoteRequest": { "type": "object", "title": "CreatePaymentLinkWithQuoteRequest", "additionalProperties": false, "description": "Create a payment link against a previously generated quote (see `POST /quotes` with `resource: payin`). When supplied, the quote is the single source of truth for amount, currency, payment method and expiry. The locked fields (`amount`, `currency`, `expires_at`, `price_id`, `payment_methods`) must NOT be sent — including any of them returns a `400 Bad Request`.\n", "properties": { "quote_id": { "type": "string", "description": "ID of a quote (from `POST /api/v1/quotes` with `resource: \"payin\"`) to bind this payment link to. When supplied, the quote is the single source of truth for amount, currency, payment method, and expiry.\n", "example": "quote_3m4n5o6p7q" }, "customer_id": { "type": "string", "description": "The unique identifier of customer linked to payment_link.\n", "example": "cust_E602dMzgjpDC" }, "purpose_code": { "type": "string", "description": "Why you are receiving this payment, as a code from a fixed set: see [Payin purpose codes](/payin/purpose-codes). This is not free text. Pass a listed code exactly, for example `P1401`; matching is exact and case-sensitive. Payins and payouts use different sets, so a payout code such as `S1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.\n\nRequired, unless Glomo has configured a default payin purpose code on your account, in which case an omitted value falls back to that default.\n", "example": "P1401" }, "document_id": { "type": "string", "description": "The unique identifier of document linked to payment_link. This document entity should contain the required documents to process incoming payments. Refer this [Document](#tag/Document) entity for more details.\n", "example": "doc_nYUqLpuYQ0M8" }, "invoice_number": { "type": "string", "description": "Number/Id of the invoice submitted with payment_link.\n", "example": "RG12FF590" }, "invoice_description": { "type": "string", "description": "Description about the invoice submitted with payment_link.\n", "example": "Payment requested for services provided" }, "invoice_amount": { "type": "number", "description": "The amount on the invoice, in the smallest unit of the quote's `destination_currency`, which is the currency the payment link is created in (cents for USD). `1000` is $10.00 when that currency is USD. Must be greater than or equal to the quote's `destination_amount`.\n", "example": 1000 }, "reference_number": { "type": "string", "description": "optional identifier to be sent for reconciliations.\n", "example": "R0001" }, "notify_customer": { "type": "boolean", "default": true, "description": "Whether to notify the customer via email when the payment link is created. Defaults to `true`. Set to `false` to suppress the notification email.\n", "example": true }, "reminder_frequency": { "type": "number", "description": "The frequency at which you want to remind customers, valid values are 1(remind everyday), 2(remind every alternate day), 7(remind every week), 14(remind every alternate week).\n", "example": 7 }, "product": { "$ref": "#/components/schemas/Product" }, "notes": { "$ref": "#/components/schemas/Notes" }, "bank_account_details": { "type": "object", "description": "Optional bank account details to associate with the customer for this payment link. When provided, the bank account will be linked to the customer and associated with this payment link. Either bic_primary or bic_secondary must be provided when including this field.\n", "properties": { "account_number": { "type": "string", "description": "The bank account number\n", "example": "1234567890" }, "bic_primary": { "type": "string", "description": "SWIFT code for the bank account. Will be null if not provided in the request.\n", "example": "HDFCINBBDEL" }, "bic_secondary": { "type": "string", "description": "Local routing code for the bank account like IFSC. Will be null if not provided in the request.\n", "example": "HDFC0001097" }, "bank_customer_id": { "type": "string", "description": "Optional bank customer identifier provided by the bank\n", "example": "7189204715" } }, "required": [ "account_number" ], "example": { "account_number": "1234567890", "bic_primary": "HDFCINBBDEL", "bank_customer_id": "7189204715" } } } }, "AttachedDocument": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier for the Document.\n", "example": "doc_nYUqLpuYQ0M8" }, "type": { "type": "string", "readOnly": true, "description": "The type of the Document.\n", "example": "invoice" }, "status": { "type": "string", "readOnly": true, "enum": [ "pending", "uploaded", "rejected", "approved" ] }, "rfi_doc_id": { "type": [ "string", "null" ], "description": "The unique identifier for the RFI Document. This will be `null` if the document is not an RFI Document.\n", "example": "rfidoc_nYUqLpuYQ0M8" } } }, "Payout": { "type": "object", "x-tags": [ "Payout" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the payout.\n", "example": "payout_DdWp_HUbOnlg" }, "status": { "type": "string", "readOnly": true, "enum": [ "pending_approval", "queued", "in_progress", "action_required", "success", "failed", "cancelled" ], "description": "The status of the payout.\n\n- `pending_approval` — the payout is waiting for a reviewer on your account to approve it. Only\n used when payout approval is turned on for your account.\n- `queued` — the payout is waiting for enough balance to cover it. It moves on once funds arrive, or\n fails with `QUEUE_EXPIRED` if they do not arrive in time.\n- `in_progress` — the payout has been accepted and is being processed or reviewed.\n- `action_required` — Glomo needs more information before the payout can proceed. Respond to the\n open RFI to continue.\n- `success` — the beneficiary has been paid. Terminal.\n- `failed` — the payout could not be completed; see `error_code`. Terminal.\n- `cancelled` — the payout was stopped before it was paid. Terminal.\n", "example": "success" }, "destination_amount": { "type": "number", "minimum": 1, "description": "The amount the beneficiary will receive, in the smallest unit of `destination_currency` (paise for INR, cents for USD). `1000` is $10.00 when `destination_currency` is USD.\n", "example": 1000 }, "destination_currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "source_amount": { "type": "number", "minimum": 1, "description": "The amount you intend to send, in the smallest unit of `source_currency` (cents for USD). `1000` is $10.00 when `source_currency` is USD.\n", "example": 1000 }, "source_currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "beneficiary_id": { "type": "string", "description": "The unique identifier of the beneficiary the payout is sent to.\n", "example": "bene_5JU9yv0lGSUP" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/AttachedDocument" }, "description": "The attached documents for the payout.\n" }, "purpose_code": { "type": "string", "description": "Purpose code of this payout, from the fixed set of [payout purpose codes](/payout/purpose-codes).\n", "example": "S0017" }, "mid_market_rate": { "type": "object", "readOnly": true, "properties": { "currency": { "type": [ "string", "null" ], "format": "iso-4217", "description": "The destination currency, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. `null` when no rate has been recorded yet.\n", "example": "USD" }, "rate": { "type": [ "number", "null" ], "format": "float", "description": "Units of the destination currency (`mid_market_rate.currency`) per one unit of `source_currency`. `1.17` with `currency` `USD` on a payout from EUR to USD means 1 EUR = 1.17 USD. `1` when the source and destination currencies are the same. `null` when no rate has been recorded yet.\n", "example": 1.17 } }, "description": "The mid-market rate at the time of payout creation. The currency represents the destination currency and rate represents the factor of conversion. Example: 1 EUR = 1.17 USD. Rate corresponds to 1.17 and currency is USD.\n" }, "fees": { "type": "object", "readOnly": true, "properties": { "fx_fee": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ], "format": "iso-4217", "description": "The currency of the FX fee, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. `null` until fees are applied to the payout.\n", "example": "USD" }, "amount": { "type": [ "integer", "null" ], "description": "The FX fee, in the smallest unit of this fee's `currency`, which is the payout's `source_currency`. `200` is $2.00 when that currency is USD. `null` until fees are applied to the payout; a zero fee is `0`.\n", "example": 200 } }, "description": "The foreign exchange fees applied to the payout" }, "txn_fee": { "type": "object", "properties": { "currency": { "type": [ "string", "null" ], "format": "iso-4217", "description": "The currency of the transaction fee, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. `null` until fees are applied to the payout.\n", "example": "USD" }, "amount": { "type": [ "integer", "null" ], "description": "The transaction fee, in the smallest unit of this fee's `currency`, which is the payout's `source_currency`. `100` is $1.00 when that currency is USD. `null` until fees are applied to the payout; a zero fee is `0`.\n", "example": 100 } }, "description": "The transaction fees applied to the payout" } }, "description": "The fees applied to this payout\n" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the payout was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the payout was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "utr": { "type": [ "string", "null" ], "readOnly": true, "description": "(Optional) Unique Transaction Reference for the payout. This is a unique identifier assigned by the bank to track the transaction.\n", "example": "AXISN52024112000001234" }, "request_id": { "type": [ "string", "null" ], "readOnly": true, "maxLength": 64, "description": "The `request_id` you sent when creating this payout, at most 64 characters; `null` if you sent none. Look the payout up with `GET /v1/payouts?request_id=`.\n", "example": "your-internal-id" }, "payment_rail": { "type": [ "string", "null" ], "readOnly": true, "enum": [ "swift", "imps", "neft", "rtgs", "upi", "ipp", "fts", "sepa", "fps", "npp", null ], "description": "The payment rail used to settle this payout. Each local rail serves one corridor: `upi`, `imps`, `neft`, `rtgs` for `INR`; `ipp`, `fts` for `AED`; `sepa` for `EUR`; `fps` for `GBP`; `npp` for `AUD`. `swift` is used for international transfers.\n", "example": "swift" }, "invoice_number": { "type": [ "string", "null" ], "readOnly": true, "maxLength": 50, "description": "The invoice reference sent when the payout was created, up to 50 characters. `null` when none was sent.\n", "example": "INV-2026-001" }, "fee_collection_mode": { "type": "string", "readOnly": true, "description": "How fees for this payout are collected.\n", "example": "merchant" }, "error_code": { "type": [ "string", "null" ], "readOnly": true, "enum": [ "QUOTE_EXPIRED", "QUEUE_EXPIRED", "PAYOUT_REJECTED", "INSUFFICIENT_BALANCE", "INVALID_BENE_ACCOUNT_NUMBER", "INVALID_BENE_ACCOUNT_TYPE", "INVALID_BENE_IFSC", "INVALID_VPA", "INVALID_BENE_NAME", "INVALID_BENE_ADDRESS", "INVALID_BENE_EMAIL", "INVALID_BENE_CONTACT", "NAME_MISMATCH", null ], "description": "A machine-readable code describing why the payout failed or was cancelled. `null` unless the\npayout is in an error state. The accompanying `error_description` carries the human-readable text.\n\n| Code | Description |\n| ---- | ----------- |\n| `QUOTE_EXPIRED` | Quote has expired. Please create a new payout with a valid quote. |\n| `QUEUE_EXPIRED` | Payout stayed queued for 30 days because the balance did not cover it. No funds were held. |\n| `PAYOUT_REJECTED` | Payout was rejected by the bank. Please reach out to support. (default fallback) |\n| `INSUFFICIENT_BALANCE` | The balance no longer covered the payout when it came out of review. No funds were held. |\n| `INVALID_BENE_ACCOUNT_NUMBER` | Beneficiary account number is invalid. |\n| `INVALID_BENE_ACCOUNT_TYPE` | Beneficiary account type is invalid. |\n| `INVALID_BENE_IFSC` | Beneficiary IFSC code is invalid. |\n| `INVALID_VPA` | VPA/UPI address is invalid. |\n| `INVALID_BENE_NAME` | Beneficiary name is invalid. |\n| `INVALID_BENE_ADDRESS` | Beneficiary address or PIN/ZIP code is invalid. |\n| `INVALID_BENE_EMAIL` | Beneficiary email is invalid. |\n| `INVALID_BENE_CONTACT` | Beneficiary contact/mobile number is invalid. |\n| `NAME_MISMATCH` | Remitter and beneficiary names do not match for the selected purpose. |\n", "example": null }, "error_description": { "type": [ "string", "null" ], "readOnly": true, "description": "A merchant-facing, human-readable description of the error. Operational copy for the merchant. `null` unless the payout is in an error state. See `customer_error_description` for the copy meant for the end-customer.\n", "example": null }, "customer_error_description": { "type": [ "string", "null" ], "readOnly": true, "description": "Customer-facing error copy, written for the merchant to relay to their end-customer. Derives from the same `error_code` as `error_description` but targets a different audience. `null` when there is no `error_code`, or when the error code has no customer-facing variant (some codes are merchant-only).\n", "example": null }, "quote_id": { "type": [ "string", "null" ], "readOnly": true, "description": "The identifier of the quote this payout was created against. `null` for payouts that were not created from a quote.\n", "example": "quote_3m4n5o6p7q" }, "taxes": { "type": "array", "readOnly": true, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tax withheld.", "example": "GST" }, "amount": { "type": "number", "description": "The tax amount, in the smallest unit of `currency`. For example, 877 is 8.77 INR.\n", "example": 877 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency the tax was withheld in, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "INR" }, "bps": { "type": "integer", "description": "The rate the tax was charged at, in basis points. 1800 is 18%.", "example": 1800 } } }, "description": "Taxes withheld on this payout, deducted from the amount before it reached the beneficiary. Present on repatriation payouts (purpose code `P0001`), where the remitting bank withholds GST on the currency conversion; empty for every other purpose, and empty until the bank has confirmed the payout.\n" }, "estimated_credit_date": { "type": [ "string", "null" ], "format": "date", "readOnly": true, "description": "The date Glomo expects the beneficiary's account to be credited, as an ISO 8601 date (`YYYY-MM-DD`) in IST. Set once, when the payout moves to `in_progress`, and not updated afterwards. It accounts for bank cut-off times, weekends, and settlement holidays for `destination_currency`. It is an estimate, not a guarantee; a `status` of `success` confirms the beneficiary has been paid. `null` until the payout reaches `in_progress`, and stays `null` for payouts that fail or are cancelled before then.\n", "example": "2026-06-05" }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "CreatePayoutWithoutQuoteRequest": { "type": "object", "title": "CreatePayoutWithoutQuoteRequest", "additionalProperties": false, "description": "Create a payout without a quote by specifying the beneficiary, currencies and amount. Fees and the FX rate are determined at creation time. Use this variant when you have not pre-generated a quote. To create a payout against a locked quote instead, see `CreatePayoutWithQuoteRequest`.\n", "properties": { "purpose_code": { "type": "string", "description": "Why you are sending this payout, as a code from a fixed set: see [Payout purpose codes](/payout/purpose-codes). This is not free text. Pass a listed code exactly, for example `S0802`; matching is exact and case-sensitive. Payouts and payins use different sets, so a payin code such as `P1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.\n\nINR payouts on a local rail (`neft`, `imps`, `rtgs`, `upi`) accept only a subset of the payout codes. A code outside that subset is rejected with `400 Bad Request`, with a message saying the code is not valid for the selected payment rail.\n", "example": "S0802" }, "beneficiary_id": { "type": "string", "description": "The unique identifier for the beneficiary.\n", "example": "bene_5JU9yv0lGSUP" }, "source_currency": { "type": "string", "format": "iso-4217", "enum": [ "USD", "EUR", "GBP", "AED", "SGD", "AUD" ], "description": "The currency of the balance the payout is paid from, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code from the list above. Any other value returns `400` with a message containing `Source currency is not supported`.\n", "example": "USD" }, "destination_currency": { "type": "string", "format": "iso-4217", "enum": [ "USD", "EUR", "GBP", "AED", "SGD", "AUD", "INR" ], "description": "The currency in which the beneficiary receives the payout. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "INR" }, "source_amount": { "type": "integer", "minimum": 1, "description": "The amount you intend to send, in the smallest unit of `source_currency` (cents for USD). `100000` is $1,000.00 when `source_currency` is USD.\nExactly one of `source_amount` or `destination_amount` must be provided (not both).\n", "example": 100000 }, "destination_amount": { "type": "integer", "minimum": 1, "description": "The amount the beneficiary will receive, in the smallest unit of `destination_currency` (paise for INR, cents for USD). `8235000` is ₹82,350.00 when `destination_currency` is INR.\nExactly one of `source_amount` or `destination_amount` must be provided (not both).\n", "example": 8235000 }, "payment_rail": { "type": "string", "default": "swift", "enum": [ "upi", "rtgs", "neft", "imps", "ipp", "fts", "sepa", "fps", "npp", "swift" ], "description": "The payment rail to use for this payout. Each local rail serves one corridor and is only available when `destination_currency` matches it: `upi`, `imps`, `neft`, `rtgs` for `INR`; `ipp`, `fts` for `AED`; `sepa` for `EUR`; `fps` for `GBP`; `npp` for `AUD`. `swift` is used for international transfers and is available on any corridor. The rail must be eligible for the beneficiary and the amount must fall inside the rail's limits. Defaults to `swift` if omitted; a local rail is not selected automatically.\n", "example": "neft" }, "invoice_number": { "type": "string", "maxLength": 50, "description": "An optional invoice reference for this payout, up to 50 characters. It is returned on the payout as `invoice_number`. A longer value returns `400` with a message containing `Invoice number must be 50 characters or less`.\n", "example": "INV-2026-001" }, "request_id": { "type": "string", "maxLength": 64, "description": "Your unique identifier for this payout, at most 64 characters, used to reject duplicates. If a payout with the same `request_id` already exists on your account, the request is rejected with `409 Conflict` and the message `Record already exists`; no second payout is created and the existing payout is not returned. Look it up with `GET /v1/payouts?request_id=`. A value longer than 64 characters is rejected with `400`.\n", "example": "req-7f3a9c20" }, "documents": { "type": "array", "items": { "type": "string" }, "description": "List of document IDs to attach to the payout.\n", "example": [ "doc_5JU9yv0lGSUP", "doc_678a5aa9SKkEr" ] }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "CreatePayoutWithQuoteRequest": { "type": "object", "title": "CreatePayoutWithQuoteRequest", "additionalProperties": false, "description": "Create a payout against a previously generated quote (see `POST /quotes` with `resource: payout`). The quote locks the fees, FX rate, currencies, amount and payment rail. The locked fields (`source_amount`, `destination_amount`, `source_currency`, `destination_currency`, `payment_rail`) must NOT be sent — including any of them returns a `400 Bad Request`.\n", "properties": { "quote_id": { "type": "string", "description": "The identifier of a payout quote generated via `POST /quotes`. The quote must exist for your business, must be a payout quote, must not have expired, and must not already have been used for another payout.\n", "example": "quote_3m4n5o6p7q" }, "beneficiary_id": { "type": "string", "description": "The unique identifier for the beneficiary. The quote's payment rail must be supported by this beneficiary, otherwise the request returns a `400 Bad Request`.\n", "example": "bene_5JU9yv0lGSUP" }, "purpose_code": { "type": "string", "description": "Why you are sending this payout, as a code from a fixed set: see [Payout purpose codes](/payout/purpose-codes). This is not free text. Pass a listed code exactly, for example `S0802`; matching is exact and case-sensitive. Payouts and payins use different sets, so a payin code such as `P1401` is rejected here. An unrecognised code is rejected with `400 Bad Request`.\n\nINR payouts on a local rail (`neft`, `imps`, `rtgs`, `upi`) accept only a subset of the payout codes. A code outside that subset is rejected with `400 Bad Request`, with a message saying the code is not valid for the selected payment rail.\n", "example": "S0802" }, "invoice_number": { "type": "string", "maxLength": 50, "description": "An optional invoice reference for this payout, up to 50 characters. It is returned on the payout as `invoice_number`. A longer value returns `400` with a message containing `Invoice number must be 50 characters or less`.\n", "example": "INV-2026-001" }, "request_id": { "type": "string", "maxLength": 64, "description": "Your unique identifier for this payout, at most 64 characters, used to reject duplicates. If a payout with the same `request_id` already exists on your account, the request is rejected with `409 Conflict` and the message `Record already exists`; no second payout is created and the existing payout is not returned. Look it up with `GET /v1/payouts?request_id=`. A value longer than 64 characters is rejected with `400`. Resending with the same `quote_id` fails first with `400`, because the quote has already been used; the `409` applies when a new quote is sent with a repeated `request_id`.\n", "example": "req-7f3a9c20" }, "documents": { "type": "array", "items": { "type": "string" }, "description": "List of document IDs to attach to the payout.\n", "example": [ "doc_5JU9yv0lGSUP", "doc_678a5aa9SKkEr" ] }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "CreateQuoteRequest": { "type": "object", "title": "CreateQuoteRequest", "additionalProperties": false, "description": "Create one or more pricing quotes for a payout or payin. A quote locks the FX rate and fee breakdown for a period. \nProvide exactly one of `source_amount` or `destination_amount`.\n", "properties": { "resource": { "type": "string", "enum": [ "payout", "payin" ], "description": "The resource to create quote for.\n", "example": "payout" }, "resource_type": { "type": "string", "enum": [ "account_funding" ], "description": "The payin programme this quote is priced under. Payin only, and required when `payment_method.type` is `card`.\n", "example": "account_funding" }, "source_currency": { "type": "string", "format": "iso-4217", "enum": [ "USD", "EUR", "GBP", "AED", "SGD", "AUD" ], "description": "The source currency code, as an uppercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Must be one of the listed values; the match is case-sensitive. `INR` is not accepted as a source currency.\n", "example": "USD" }, "destination_currency": { "type": "string", "format": "iso-4217", "enum": [ "USD", "EUR", "GBP", "AED", "SGD", "AUD", "INR" ], "description": "The destination currency code, as an uppercase [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Must be one of the listed values; the match is case-sensitive.\n", "example": "INR" }, "source_amount": { "type": "integer", "minimum": 1, "description": "The amount you intend to send, in the smallest unit of `source_currency` (cents for USD). `10000` is $100.00 when `source_currency` is USD.\nProvide exactly one of `source_amount` or `destination_amount`, not both.\n", "example": 10000 }, "destination_amount": { "type": "integer", "minimum": 1, "description": "The amount to be received, in the smallest unit of `destination_currency` (paise for INR, cents for USD). `882000` is ₹8,820.00 when `destination_currency` is INR.\nProvide exactly one of `source_amount` or `destination_amount`, not both.\n", "example": 882000 }, "payment_method": { "type": "object", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "bank_transfer", "pay_via_bank", "card" ], "description": "The payment method. `pay_via_bank` and `card` are payin only.\n", "example": "bank_transfer" }, "subtype": { "type": "string", "enum": [ "local_transfer", "swift_transfer" ], "description": "The payment method subtype. Required for `bank_transfer` and `pay_via_bank`, and must be omitted for `card`.\n\nThe payment rail is not an input; it is derived per quote and returned on each quote as `payment_method.rail`.\n", "example": "swift_transfer" } }, "required": [ "type" ], "description": "The payment method details to price. `pay_via_bank` only supports the `local_transfer` subtype. `card` takes no subtype.\n" }, "price_id": { "type": "string", "description": "Payin only. The platform referral price to apply. When set, the quote's fee breakdown includes a `referral_fee`.\n", "example": "price_5JU9yv0lGSUP" }, "split_ids": { "allOf": [ { "$ref": "#/components/schemas/SplitIds" } ], "description": "Payin only. The pricing splits to apply when quoting the fee. Sending `split_ids` with `resource: payout` returns a `400 Bad Request`. A payment link or an order created from this quote inherits these splits, and must not send `split_ids` of its own.\n" } }, "required": [ "resource", "destination_currency", "payment_method" ] }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for this quote.\n", "example": "quote_3m4n5o6p7q" }, "resource": { "type": "string", "readOnly": true, "enum": [ "payout", "payin" ], "description": "The resource this quote prices.\n", "example": "payout" }, "resource_type": { "type": "string", "readOnly": true, "enum": [ "account_funding" ], "description": "The payin programme this quote is priced under. Present only when the quote was created with one.\n", "example": "account_funding" }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The expiry timestamp for this quote in ISO 8601 format. Quotes are valid for a fixed period from creation.\n", "example": "2026-06-12T08:16:50Z" }, "payment_method": { "type": "object", "readOnly": true, "properties": { "type": { "type": "string", "enum": [ "bank_transfer", "pay_via_bank", "card" ], "description": "The payment method for this quote.", "example": "bank_transfer" }, "subtype": { "type": "string", "enum": [ "local_transfer", "swift_transfer" ], "description": "The payment method subtype for this quote. Absent on a `card` quote, which has no subtype.\n", "example": "swift_transfer" }, "rail": { "type": "string", "description": "The derived payment rail for this quote. Present only for payout quotes. A SWIFT transfer yields a single `swift` quote. A local transfer yields one quote per local rail for the destination currency whose amount limits admit the payout: `upi`, `imps` or `neft` for INR, `ipp` or `fts` for AED, `sepa` for EUR, `fps` for GBP and `npp` for AUD.\n", "example": "swift" } }, "description": "The payment method details for this quote.\n" }, "source_currency": { "type": "string", "format": "iso-4217", "readOnly": true, "description": "The source currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "USD" }, "destination_currency": { "type": "string", "format": "iso-4217", "readOnly": true, "description": "The destination currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "INR" }, "fx_rate": { "type": "number", "format": "float", "readOnly": true, "description": "The mid-market exchange rate for this quote, before FX fees, as units of `destination_currency` per one unit of `source_currency`. `90.0` means 1 USD = 90 INR. `1` when the two currencies are the same.\n", "example": 90 }, "effective_fx_rate": { "type": [ "number", "null" ], "format": "float", "readOnly": true, "description": "The mid-market rate adjusted for the FX fee only, as units of `destination_currency` per one unit of `source_currency`. For a payin it is `fx_rate / (1 + fx_fee / destination_amount)`.\n\nThe transaction fee is not in it, so this is not the all-in cost. `null` when no mid-market rate is available or the amount is zero.\n", "example": 0.2700972222222222 }, "source_amount": { "type": "integer", "readOnly": true, "description": "The total source amount, in the smallest unit of `source_currency` (cents for USD). `10000` is $100.00 when `source_currency` is USD.\n", "example": 10000 }, "destination_amount": { "type": "integer", "readOnly": true, "description": "The destination amount, in the smallest unit of `destination_currency` (paise for INR, cents for USD). `882000` is ₹8,820.00 when `destination_currency` is INR.\n", "example": 882000 }, "fees": { "type": "object", "readOnly": true, "properties": { "txn_fee": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency of the transaction fee, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code.\n", "example": "USD" }, "amount": { "type": "integer", "description": "The transaction fee, in the smallest unit of this fee's `currency`. `100` is $1.00 when that currency is USD.\n", "example": 100 } }, "description": "The transaction fee applied to this quote" }, "fx_fee": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency of the FX fee, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code.\n", "example": "USD" }, "amount": { "type": "integer", "description": "The FX fee, in the smallest unit of this fee's `currency`. `100` is $1.00 when that currency is USD.\n", "example": 100 } }, "description": "The foreign exchange fee applied to this quote" }, "referral_fee": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency of the referral fee, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code.\n", "example": "USD" }, "amount": { "type": "integer", "description": "The referral fee, in the smallest unit of this fee's `currency`. `50` is $0.50 when that currency is USD.\n", "example": 50 } }, "description": "The platform referral fee. Present only on payin quotes when a referral `price_id` was applied.\n" } }, "description": "The fees breakdown for this quote.\n" } } }, "CreateLrsQuoteRequest": { "type": "object", "properties": { "resource": { "type": "string", "enum": [ "payin", "payout" ], "default": "payin", "description": "What the quote prices.\n\n- `payin` — an LRS remittance from a resident Indian customer. Requires `bank_code`.\n- `payout` — a withdrawal back to the customer in India. Only `USD` to `INR` is supported, and\n `bank_code` must not be sent.\n", "example": "payin" }, "bank_code": { "type": "string", "description": "Code of the customer's bank, as returned by `GET /lrs/banks`. Required when `resource` is `payin`, and the bank must be enabled for your account. Rejected when `resource` is `payout`.\n", "example": "hdfc" }, "source_amount": { "type": "integer", "description": "The amount to convert, in the smallest unit of `source_currency` (paisa for INR, cents for USD). `4400000` is ₹44,000.00 when `source_currency` is `INR`. Must be a whole number; a string of digits such as `\"4400000\"` is also accepted. Send a positive integer; an optional leading sign is accepted. A decimal or an exponent is rejected with `400`. On a payin quote, the amount must fall within the minimum and maximum set for the bank, otherwise the request is rejected with `400` and the message states the limit.\n", "example": 4400000 }, "source_currency": { "type": "string", "format": "iso-4217", "enum": [ "INR", "USD" ], "description": "The currency of `source_amount`. Must differ from `target_currency`.\n", "example": "INR" }, "target_currency": { "type": "string", "format": "iso-4217", "enum": [ "INR", "USD" ], "description": "The currency to convert into. Must differ from `source_currency`.\n", "example": "USD" } }, "required": [ "source_amount", "source_currency", "target_currency" ] }, "LrsQuote": { "type": "object", "description": "An LRS quote: the conversion, tax and exchange rate for an LRS remittance or withdrawal.\n", "properties": { "id": { "type": "string", "readOnly": true, "description": "Unique identifier of the quote. Pass it as `lrs.lrs_quote_id` on an LRS order.\n", "example": "quote_6ab60de4Kx7Pq" }, "from": { "type": "object", "readOnly": true, "description": "The amount the quote converts from: your `source_amount` and `source_currency`.\n", "properties": { "amount": { "type": "integer", "description": "Amount in the smallest unit of `currency` (paisa for INR, cents for USD).\n", "example": 4400000 }, "currency": { "type": "string", "format": "iso-4217", "example": "INR" } } }, "to": { "type": "object", "readOnly": true, "description": "The amount the quote converts to, in `target_currency`.\n\n- `INR` to `USD` payin quote: GST is deducted from `from.amount` before conversion, so\n `to.amount` is the USD remitted.\n- `USD` to `INR` payin quote: `to.amount` is the INR equivalent of `from.amount`, plus any\n transaction fee charged to the customer, with GST added.\n- Payout quote: `to.amount` is the INR the customer receives after fees and GST are deducted.\n\nOn a payin quote, the side in `USD` is the amount an LRS order must be created for.\n", "properties": { "amount": { "type": "integer", "description": "Amount in the smallest unit of `currency` (paisa for INR, cents for USD). `51763` is $517.63 when `currency` is `USD`.\n", "example": 51763 }, "currency": { "type": "string", "format": "iso-4217", "example": "USD" } } }, "fx_rate": { "type": "string", "readOnly": true, "description": "The exchange rate applied to the quote, as a decimal string in INR per 1 USD. It is expressed this way whichever direction the quote converts.\n", "example": "84.85" }, "bank_code": { "type": "string", "readOnly": true, "description": "The `bank_code` the quote was created for. Present on payin quotes only.\n", "example": "hdfc" }, "total_tax": { "type": "integer", "readOnly": true, "description": "GST on the conversion, in paisa, whichever direction the quote converts. `7906` is ₹79.06.\n", "example": 7906 }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the quote expires, as an ISO 8601 date-time in UTC. Payout quotes expire 30 minutes after `created_at`. For payin quotes, rely on this value rather than a fixed duration. An LRS order created from the quote expires at the same time, and an order cannot be created from an expired quote.\n", "example": "2026-09-25T06:30:04.113Z" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the quote was created, as an ISO 8601 date-time in UTC.\n", "example": "2026-09-25T06:00:04.113Z" } } }, "LrsBank": { "type": "object", "description": "A bank your customers can remit from under LRS.\n", "properties": { "bank_code": { "type": "string", "description": "Code of the bank. Pass it as `bank_code` when you register an LRS bank account for a customer and when you create an LRS payin quote.\n", "example": "hdfc" }, "bank_name": { "type": "string", "description": "Display name of the bank.\n", "example": "HDFC bank" } } }, "MockUpdatePayoutStatusRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "The `id` of the payout to update, as returned when you created it. A payout that does not exist, or belongs to another account, returns `404`.\n", "example": "payout_E602dMzgjpDC" }, "status": { "type": "string", "enum": [ "pending", "queued", "success", "failed", "action_required", "cancelled" ], "description": "The state to move the payout to. These are sandbox transition targets, not the values the payout's\n`status` field returns:\n\n- `pending` — accepts the payout for processing. It then reads as `in_progress`. On an account with\n payout queueing, a payout that isn't `queued` yet is queued instead. A `queued` payout moves on only\n if your balance covers it.\n- `queued` — puts the payout in the payout queue. Only on an account with payout queueing.\n- `success` — pays the payout out.\n- `failed` — fails the payout.\n- `action_required` — moves the payout to `action_required`.\n- `cancelled` — cancels the payout.\n\nA transition the payout's current status does not allow returns a `400`.\n", "example": "success" } } }, "TaxLine": { "type": "object", "properties": { "amount": { "type": "number", "description": "The tax amount in the smallest unit of this line's `currency` (cents for USD). `1800` is $18.00 when `currency` is USD.\n", "example": 1800 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "name": { "type": "string", "description": "The name of the tax applied on the fee. For example, GST.\n", "example": "GST" }, "bps": { "type": "number", "description": "The tax rate in basis points. For example, 1800 represents 18%.\n", "example": 1800 } } }, "FeeBreakdownEntry": { "type": "object", "properties": { "amount": { "type": "number", "description": "The fee amount in the smallest unit of this entry's `currency` (cents for USD), aggregated across all rules for this fee bearer. `250` is $2.50 when `currency` is USD.\n", "example": 250 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "bearer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "The party bearing this fee.\n", "example": "merchant" }, "collection_mode": { "type": [ "string", "null" ], "enum": [ "immediate", "deferred", null ], "description": "When the fee is collected. Customer-borne fees are always collected immediately; merchant-borne fees follow the payment's collection mode.\n", "example": "immediate" }, "taxes": { "type": "array", "items": { "$ref": "#/components/schemas/TaxLine" }, "description": "Taxes applied on this fee (for example, GST). Empty when no tax applies to the underlying rules.\n" } } }, "Payment": { "type": "object", "x-tags": [ "Payment" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the payment.\n", "example": "payt_E602dMzgjpDC" }, "payin_id": { "type": [ "string", "null" ], "description": "The unique identifier for the payin. This is set only for payments associated to a payin.\n", "example": "plink_E602dMzgjpDC" }, "payin_type": { "type": [ "string", "null" ], "description": "The type of the payin. This is set only for payments associated to a payin.\n\n- `payment_link` — the payment was made through a payment link.\n- `orders` — the payment was made against an order.\n- `add_funds` — the payment tops up your own Glomo balance.\n", "enum": [ "payment_link", "orders", "add_funds", null ] }, "subscription_id": { "type": [ "string", "null" ], "description": "The unique identifier for the subscription. This is set only for subscription-related payments.\n", "example": "sub_68877570b5zeE" }, "status": { "type": "string", "readOnly": true, "enum": [ "in_progress", "action_required", "under_review", "success", "failed" ], "description": "The status of the payment.\n\n- `in_progress` — the payment has started and has not completed yet.\n- `action_required` — Glomo needs more information before the payment can complete. Respond to the\n open RFI to continue.\n- `under_review` — the information you submitted is being reviewed.\n- `success` — the payment completed. Terminal. Funds can still be held for compliance review; see\n `compliance_status`.\n- `failed` — the payment did not complete. Terminal.\n" }, "compliance_status": { "type": [ "string", "null" ], "readOnly": true, "enum": [ "action_required", "under_review", "approved", "rejected", null ], "description": "The compliance review status of the payment. Present only for payments that have been screened for\nsanctions or transaction-monitoring holds; `null` for payments that were not screened. This is\nseparate from `status` — a payment can be `status: success` while `compliance_status` is\n`action_required`, meaning the payment itself completed but funds are held pending compliance\nreview. See the `rfi` field for what's required when `action_required`.\n\n- `under_review` — the payment is being reviewed and its funds are held.\n- `action_required` — documents are needed before the review can finish. Respond to the open RFI.\n- `approved` — the review passed and the funds are released.\n- `rejected` — the payment did not pass the review.\n", "example": "action_required" }, "rfi": { "type": "object", "readOnly": true, "description": "Present only when a compliance-related Request For Information exists on this payment. Describes why the payment was flagged and what's required to resolve it.\n", "properties": { "id": { "type": "string", "description": "The unique identifier for the RFI.\n", "example": "rfi_6a72a39b38jDD" }, "reason_code_description": { "type": "string", "description": "A human-readable description of why this payment was flagged for compliance review.\n", "example": "The payment has been flagged for a compliance review and requires additional information before it can credited to your account." }, "reason_code": { "type": "string", "description": "A machine-readable code for the compliance review reason.\n", "example": "COMPLIANCE_REVIEW" }, "response_deadline": { "type": [ "string", "null" ], "format": "date-time", "description": "The deadline by which the requested documents must be submitted. `null` when no deadline has been set.\n", "example": "2026-08-21T10:29:00Z" }, "documents_required": { "type": "array", "description": "Present only when `compliance_status` is `action_required`. The documents needed to resolve this RFI. Submit documents against a specific requirement using its `rfi_doc_id` via the [Respond to an RFI](/api-reference/openapi/rfi/respondrfi) endpoint, passing the `rfi.id` as the RFI identifier.\n", "items": { "type": "object", "properties": { "rfi_doc_id": { "type": "string", "description": "The unique identifier for this document requirement.\n", "example": "rfidoc_6a72a39b38jDD" }, "description": { "type": "string", "description": "A human-readable description of what document is needed.\n", "example": "Passport" }, "multiple_allowed": { "type": "boolean", "description": "Whether more than one document can be submitted for this requirement.\n", "example": false }, "max_count": { "type": "integer", "description": "The maximum number of documents that can be submitted for this requirement, as a count of documents. `1` when the requirement does not set a higher limit.\n", "example": 1 } } } } } }, "payment_currency": { "type": "string", "format": "iso-4217", "description": "The currency in which the customer pays. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, AED.\n", "example": "AED" }, "payment_amount": { "type": "number", "minimum": 1, "description": "The total amount the customer pays (includes customer-borne fees if applicable), in the smallest unit of `payment_currency`, the customer-side currency. `374580` is 3,745.80 AED when `payment_currency` is AED.\n", "example": 374580 }, "converted_currency": { "type": "string", "format": "iso-4217", "description": "The settlement currency after conversion. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "converted_amount": { "type": "number", "minimum": 1, "description": "The payment amount in the smallest unit of `converted_currency`, the merchant-side currency. `100000` is $1,000.00 when `converted_currency` is USD. Always the same value as `requested_amount`. For a payment against an order, payment link or subscription, it is the amount requested and excludes customer-borne fees, which are counted only in `payment_amount`. A bank transfer that is not yet connected to an order or payment link shows the amount and currency received. Once it is connected and the amount received matches the payin's quote, it shows the merchant-side amount like any other payment.\n", "example": 100000 }, "requested_currency": { "type": "string", "format": "iso-4217", "description": "The currency that was originally requested by the merchant. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "requested_amount": { "type": "number", "minimum": 1, "description": "The amount requested by the merchant, in the smallest unit of `requested_currency`, the merchant-side currency. `100000` is $1,000.00 when `requested_currency` is USD. Always the same value as `converted_amount`. For a payment against an order, payment link or subscription, it excludes customer-borne fees, which are counted only in `payment_amount`. A bank transfer that is not yet connected to an order or payment link shows the amount and currency received. Once it is connected and the amount received matches the payin's quote, it shows the merchant-side amount like any other payment.\n", "example": 100000 }, "purpose_code": { "type": "string", "description": "Purpose code recorded against this payment, from the fixed set of [payin purpose codes](/payin/purpose-codes). For a payment connected to a payin this is normally the payin's purpose code. It can be empty.\n", "example": "S0001" }, "sender_name": { "type": "string", "description": "The name of the sender.\n", "example": "John Doe" }, "notes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom field values for this payment. See [Custom Fields](/payin/custom-fields).\n", "example": { "policy_number": "POL-001" } }, "request_id": { "type": [ "string", "null" ], "readOnly": true, "description": "The `request_id` you sent when creating this payment; `null` if you sent none. Look the payment up with `GET /v1/payments?request_id=`.\n", "example": "your-internal-id" }, "error_code": { "type": "string", "readOnly": true, "description": "The error code for the respective error. Error code mappings can be found in the [product guide](/payin/payment#error-codes).\n", "example": "PAYMENT_DECLINED" }, "error_description": { "type": "string", "readOnly": true, "description": "The merchant-facing error description corresponding to the error code. Operational copy for the merchant. See `customer_error_description` for the copy meant for the end-customer.\n", "example": "The payment attempt was declined. This could be due to issuer rejection, risk assessment, or restrictions on the card or account. The customer should contact their bank or try a different payment method." }, "customer_error_description": { "type": [ "string", "null" ], "readOnly": true, "description": "Customer-facing error copy, written for the merchant to relay to their end-customer. Derives from the same `error_code` as `error_description` but targets a different audience. `null` when there is no `error_code`, or when the error code has no customer-facing variant (some codes are merchant-only, e.g. `ACCOUNT_LOCKED`, `LOGGED_IN_ELSEWHERE`, `FUNCTIONALITY_RESTRICTED`).\n", "example": "Your payment could not be completed. Please try a different payment method or contact your bank." }, "paid_at": { "type": [ "string", "null" ], "readOnly": true, "format": "date-time", "description": "When the payment was completed, as an ISO 8601 date-time in UTC. `null` if the payment has not been paid.\n", "example": "2024-12-06T11:38:37.130Z" }, "fee_bearer": { "type": "string", "enum": [ "customer", "merchant", "split" ], "description": "The party bearing the fees for the payment.\n", "example": "customer" }, "fee_collection_mode": { "type": [ "string", "null" ], "enum": [ "immediate", "deferred", null ], "description": "When merchant-borne fees are collected. `immediate` deducts fees up front; `deferred` invoices them later. `null` when not applicable.\n", "example": "immediate" }, "created_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the payment was created, as an ISO 8601 date-time in UTC.\n", "example": "2024-12-06T11:38:37.130Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the payment was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2024-12-06T11:38:37.130Z" }, "customer_id": { "type": "string", "description": "The unique identifier for the customer.\n", "example": "cust_E602sMzgjpDC" }, "merchant_id": { "type": "string", "description": "The unique identifier for the merchant (business) that owns the payment.\n", "example": "merch_68c777fcOOMpl" }, "product_name": { "type": [ "string", "null" ], "readOnly": true, "description": "The name of the product associated with the payment.\n", "example": "ShieldGuard Insurance" }, "product_description": { "type": [ "string", "null" ], "readOnly": true, "description": "The description of the product associated with the payment.\n", "example": "Simple, monthly insurance plan that covers your basic belongings and key digital assets" }, "country": { "type": "string", "format": "iso-3166-1-alpha-3", "description": "The country of the sender. Country should be sent as a [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code.\n", "example": "Ind" }, "fees": { "type": "object", "deprecated": true, "description": "**Deprecated.** Use `fee_breakdown` instead. The fees charged for the payment, aggregated per fee type. `fee_breakdown` provides a per-bearer breakdown including any applicable taxes.\n", "properties": { "txn_fee": { "$ref": "#/components/schemas/Money", "description": "The transaction fee charged for the payment.\n" }, "fx_fee": { "$ref": "#/components/schemas/Money", "description": "The foreign exchange fee charged for the payment.\n" }, "referral_fee": { "$ref": "#/components/schemas/Money", "description": "The referral fee charged for the payment.\n" } } }, "fee_breakdown": { "type": "object", "description": "A detailed breakdown of the fees charged for the payment, grouped by fee type. Each fee type holds one entry per fee bearer, with any applicable taxes (for example, GST) nested under the entry's `taxes` array.\n", "properties": { "fx_fee": { "type": "array", "items": { "$ref": "#/components/schemas/FeeBreakdownEntry" }, "description": "Foreign exchange fee lines.\n" }, "txn_fee": { "type": "array", "items": { "$ref": "#/components/schemas/FeeBreakdownEntry" }, "description": "Transaction fee lines.\n" }, "referral_fee": { "type": "array", "items": { "$ref": "#/components/schemas/FeeBreakdownEntry" }, "description": "Referral fee lines.\n" } } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/AttachedDocument" }, "description": "The attached documents for the payment.\n" }, "settlement_id": { "type": "string", "description": "A unique identifier generated by Glomo for the settlement batch in which this payment is included. This ID can be used to track and reconcile payments against corresponding settlements.\n" }, "funds_available": { "type": "boolean", "description": "Indicates whether the funds for this payment are currently available with Glomo.\n\n**Values:**\n\n- `true` - Funds are available with Glomo and can be included in a payout or settlement\n- `false` - Funds are still in transit with Glomo's payment partners and are not yet available for use\n" }, "partner_transaction_reference_id": { "type": "string", "readOnly": true, "description": "Transaction ID common to both partners in a partnership payment, so both partners can match the same remittance. Present only for partnership payments.\n", "example": "ptr_6819d8046mpKt" }, "payment_method": { "type": "object", "description": "Specifies the method used by the customer to complete the payment.\n", "properties": { "type": { "type": "string", "enum": [ "bank_transfer", "pay_via_bank", "card" ], "description": "The type of payment method used for the transaction.\n", "example": "bank_transfer" }, "details": { "type": "object", "description": "Additional details specific to the payment method type. The structure varies based on the payment method type.\n", "oneOf": [ { "title": "Bank Transfer Details", "properties": { "sender_name": { "type": "string", "description": "The name of the sender as provided by the sending bank.\n", "example": "Vaibhav LRS" }, "sender_country": { "type": [ "string", "null" ], "description": "The ISO 3166-1 alpha-3 country code of the sender.\n", "example": "IND" }, "sender_account_number": { "type": "string", "description": "The account number of the sender.\n", "example": "5454545454" }, "receiver_account_number": { "type": "string", "description": "The account number credited by the transfer — the virtual account assigned to you.\n", "example": "98765432109876" }, "sender_bank_name": { "type": [ "string", "null" ], "description": "The name of the sender's bank.\n", "example": "JPMORGAN CHASE BANK,N.A." }, "sender_bank_country": { "type": [ "string", "null" ], "description": "The ISO 3166-1 alpha-3 country code of the sender's bank. This is the country of the bank, which can differ from `sender_country`.\n", "example": "USA" }, "sender_bank_address": { "type": [ "string", "null" ], "description": "The registered address of the sender's bank.\n", "example": "270 Park Avenue, New York" }, "swift_code": { "type": [ "string", "null" ], "description": "The sender bank's ISO 9362 BIC. `null` while the identifier is not available.\n", "example": "CHASUS33" }, "local_routing_number": { "type": [ "string", "null" ], "description": "The sender bank's domestic routing identifier — a US ABA routing number, a UK sort code, or an Australian BSB. `null` while the identifier is not available.\n", "example": "300129" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference supplied by the partner bank for the incoming transfer, for reconciliation against your own records.\n", "example": "GLM7A2C1" }, "transfer_type": { "type": [ "string", "null" ], "enum": [ "swift", "local", null ], "description": "The rail the funds arrived on. `swift` for a cross-border SWIFT transfer, `local` for a domestic scheme such as ACH, Faster Payments or SEPA.\n", "example": "swift" }, "remittance_information": { "type": [ "string", "null" ], "description": "Additional remittance information provided with the payment.\n", "example": "PaymentForLrs" } } }, { "title": "Pay Via Bank Details", "properties": { "sender_name": { "type": [ "string", "null" ], "description": "The name of the sender as provided by the sending bank.\n", "example": "Vaibhav LRS" }, "sender_country": { "type": [ "string", "null" ], "description": "The ISO 3166-1 alpha-3 country code of the sender.\n", "example": "IND" }, "sender_account_number": { "type": [ "string", "null" ], "description": "The account number debited.\n", "example": "5454545454" }, "sender_bank_name": { "type": [ "string", "null" ], "description": "The name of the sender's bank.\n", "example": "HDFC Bank" }, "sender_bank_country": { "type": [ "string", "null" ], "description": "The ISO 3166-1 alpha-3 country code of the sender's bank.\n", "example": "IND" }, "sender_bank_address": { "type": [ "string", "null" ], "description": "The registered address of the sender's bank.\n", "example": "Senapati Bapat Marg, Mumbai" }, "swift_code": { "type": [ "string", "null" ], "description": "The sender bank's ISO 9362 BIC. `null` while the identifier is not available.\n", "example": "HDFCINBB" }, "local_routing_number": { "type": [ "string", "null" ], "description": "The sender bank's domestic routing identifier — a US ABA routing number, a UK sort code, or an Australian BSB. `null` while the identifier is not available.\n", "example": "300129" }, "external_reference": { "type": [ "string", "null" ], "description": "The reference supplied by the partner bank, for reconciliation against your own records.\n", "example": "GLM7A2C1" }, "transfer_type": { "type": [ "string", "null" ], "enum": [ "swift", "local", null ], "description": "The rail used to debit the sender.\n", "example": "swift" }, "remittance_information": { "type": [ "string", "null" ], "description": "Additional remittance information provided with the payment.\n", "example": "PaymentForLrs" } } }, { "title": "Card Details", "properties": { "card_network": { "type": "string", "description": "The card network (e.g., Visa, Mastercard, American Express).\n", "example": "Visa" }, "card_type": { "type": "string", "description": "The type of card (e.g., credit, debit).\n", "example": "credit" }, "end_digits": { "type": "string", "description": "The last few digits of the card number for identification.\n", "example": "1234" }, "country_code": { "type": "string", "description": "The country code associated with the card.\n", "example": "US" }, "card_holder_name": { "type": "string", "description": "The name of the card holder.\n", "example": "John Doe" }, "card_bin": { "type": "string", "description": "The IIN (also known as BIN) is the card-number prefix that identifies the network, card type and issuing country.\n", "example": "400000" }, "issuer_name": { "type": "string", "description": "The name of the card issuing bank or financial institution.\n", "example": "Chase Bank" } } } ] } }, "examples": [ { "summary": "Bank Transfer Payment Method (SWIFT, sender bank identified by BIC)", "value": { "type": "bank_transfer", "details": { "sender_name": "Vaibhav LRS", "sender_account_number": "5454545454", "receiver_account_number": "98765432109876", "sender_country": "IND", "sender_bank_name": "JPMORGAN CHASE BANK,N.A.", "sender_bank_country": "USA", "sender_bank_address": "270 Park Avenue, New York", "swift_code": "CHASUS33", "local_routing_number": null, "external_reference": "GLM7A2C1", "transfer_type": "swift", "remittance_information": "PaymentForLrs" } } }, { "summary": "Bank Transfer Payment Method (local, sender bank identified by a UK sort code)", "value": { "type": "bank_transfer", "details": { "sender_name": "Vaibhav LRS", "sender_account_number": "5454545454", "receiver_account_number": "98765432109876", "sender_country": "GBR", "sender_bank_name": "ICICI BANK UK PLC", "sender_bank_country": "GBR", "sender_bank_address": "One Thomas More Square, London", "swift_code": null, "local_routing_number": "300129", "external_reference": "GLM7A2C1 INVOICE 4471", "transfer_type": "local" } } }, { "summary": "Pay Via Bank Payment Method (LRS remittance)", "value": { "type": "pay_via_bank", "details": { "sender_name": "Vaibhav LRS", "sender_country": "IND", "sender_account_number": "5454545454", "sender_bank_name": "HDFC Bank", "sender_bank_country": null, "sender_bank_address": null, "swift_code": null, "local_routing_number": null, "external_reference": null, "transfer_type": "swift", "remittance_information": "PaymentForLrs" } } }, { "summary": "Card Payment Method", "value": { "type": "card", "details": { "card_network": "Visa", "card_type": "credit", "end_digits": "1234", "country_code": "US", "card_holder_name": "John Doe", "card_bin": "400000", "issuer_name": "Chase Bank" } } } ] }, "auto_debit?": { "type": [ "boolean", "null" ], "readOnly": true, "description": "Indicates whether the payment was made via auto-debit. Present only for subscription payments; `true` for an auto-debit payment, `false` for a manual subscription payment.\n", "example": true } } }, "CreatePaymentRequest": { "type": "object", "x-internal": true, "properties": { "order_id": { "type": "string", "description": "The unique identifier for the order. Either `order_id` or `subscription_id` must be provided, but not both.\n", "example": "order_68c00b7btsthf" }, "subscription_id": { "type": "string", "description": "The unique identifier for the subscription. Either `order_id` or `subscription_id` must be provided, but not both.\n", "example": "sub_5JU9yv0lGSUP" }, "method": { "type": "string", "enum": [ "card" ], "description": "Payment method. Must be `card`. Required for initial payments. Not required for subsequent payments (defaults to `card`).\n", "example": "card" }, "sequence": { "type": "string", "enum": [ "initial", "subsequent" ], "default": "initial", "description": "Payment sequence. Use `initial` (default) for first-time payments or `subsequent` for merchant-initiated payments on `as_presented` subscriptions.\n", "example": "initial" }, "card": { "type": "object", "description": "Card details. Required for initial payments. Not required for subsequent payments — the card from the last successful payment is reused.\n", "properties": { "holder_name": { "type": "string", "description": "The name of the card holder.\n", "example": "John Doe" }, "number": { "type": "string", "description": "The card number: 13 to 19 digits, spaces are stripped. In sandbox, use one of the [test card numbers](/payin/payment-methods/cards#test-card-details); any other number is rejected with `400` and the message `Card is not a valid test card`. Each test card's outcome is listed on the [Cards page](/payin/payment-methods/cards#test-card-details).\n", "example": "4111111111111111" }, "expiry_month": { "type": "string", "description": "The card expiry month, two digits from `01` to `12`. The expiry must not be in the past.\n", "example": "09" }, "expiry_year": { "type": "string", "description": "The card expiry year in 2-digit (YY) format. Send the last two digits of the expiry year (e.g. for 2030, send '30'); the 4-digit year (`2030`) is also accepted. The expiry must not be in the past.\n", "example": "30" }, "cvv": { "type": "string", "description": "The card CVV/CVC code, 3 or 4 digits.\n", "example": "123" } }, "required": [ "holder_name", "number", "expiry_month", "expiry_year", "cvv" ] }, "callback_url": { "type": "string", "format": "uri", "description": "HTTPS URL where the customer is redirected after payment processing. Required for initial payments. Not required for subsequent payments as there is no customer redirect involved. When sent, it must be an `https://` URL: an `http://` URL returns `400` with a message containing `Callback url must be a valid HTTPS URL`, and a value that is not a web URL returns `400` with `Callback url is not a valid URL`.\n", "example": "https://server.yoursite.com/payment/callback" }, "request_id": { "type": "string", "description": "Your unique identifier for this payment, used to reject duplicates. Required for subsequent payments, optional for initial payments. On a subsequent payment, a `request_id` already used on your account is rejected with `400` and the message `Payment already exists for this request_id`. Retrying an initial payment is rejected first by the order or subscription state check (for example `Order has an ongoing payment` or `Order is not in a valid state for payment`). In neither case is the existing payment returned; look it up with `GET /v1/payment?request_id=`.\n", "example": "unique_request_id_123" }, "amount": { "type": "integer", "minimum": 1, "description": "Payment amount in the smallest unit of `currency`, which must be the subscription's currency (cents for USD). `1500` is $15.00 when `currency` is USD. Read only when `sequence` is `subsequent`, where it is required, must be greater than 0 and cannot exceed the subscription's `max_amount`. Ignored on initial payments.\n", "example": 1500 }, "currency": { "type": "string", "format": "iso-4217", "description": "Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format, case-insensitive. Checked only on subsequent payments, where it must match the subscription's currency; otherwise the request is rejected with `400`. Ignored on initial payments.\n", "example": "USD" }, "split_ids": { "allOf": [ { "$ref": "#/components/schemas/SplitIds" } ], "description": "The pricing splits to apply to this charge. Supported on a `subsequent` auto debit for an `as_presented` subscription; sending `split_ids` for a fixed-frequency subscription returns a `400 Bad Request`.\n\nThe splits apply to this charge only. They override the subscription's own declaration for this charge and do not modify it. Omit `split_ids` and Glomo prices the charge from the subscription's declaration.\n" }, "notes": { "$ref": "#/components/schemas/Notes" } } }, "CreatePaymentResponse": { "type": "object", "x-internal": true, "properties": { "payment_id": { "type": "string", "description": "The unique identifier for the created payment.\n", "example": "payt_691eeb9aV79Uk" }, "status": { "type": "string", "enum": [ "in_progress", "action_required", "under_review", "success", "failed" ], "description": "The current status of the payment. Uses the same values as the payment's `status` field. A payment that still needs the customer to act is `in_progress` and carries `next_steps`.\n", "example": "in_progress" }, "next_steps": { "type": "array", "description": "A list of actions to be taken to complete the payment. For initial payments, this typically includes a redirect URL for 3DS/OTP authentication and a polling URL to check payment status.\n", "items": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "redirect", "poll" ], "description": "The type of action to perform.\n", "example": "redirect" }, "payload": { "type": "object", "description": "The payload for the action. Structure varies based on the action type.\n", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL for the action. For `redirect`, this is the URL to redirect the customer to. For `poll`, this is the URL to poll for payment status updates.\n", "example": "https://secure.glomopay.com?paymentId=payt_691eeb9aV79Uk&authToken=ey...&redirectUrl=encoded_url" }, "interval_in_ms": { "type": "integer", "description": "The recommended polling interval in milliseconds. Only present for `poll` actions.\n", "example": 5000 } } } } } } } }, "Refund": { "type": "object", "x-tags": [ "Refund" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the refund.\n", "example": "refund_6776d57dnbTWj" }, "customer_id": { "type": "string", "description": "The unique identifier of customer linked to refund.\n", "example": "cust_E602dMzgjpDC" }, "payment_id": { "type": "string", "description": "The unique identifier of payment linked to refund.\n", "example": "payt_E602dMzgjpDC" }, "reason": { "type": "string", "enum": [ "Requested By Customer", "Fraudulent", "Duplicate", "Others", "Refunded For Subscription Verification", "Refunded For Subscription Card Update" ], "description": "The reason for the refund. For a refund you created, this is the `reason` you sent.\n\nGlomo also refunds some payments itself, and those refunds appear in your refund list with one of\ntwo further reasons that you cannot send:\n\n- `Refunded For Subscription Verification` — the refund of a small charge used to verify the card\n when a subscription was set up.\n- `Refunded For Subscription Card Update` — the refund of a small charge used to verify a new card\n when the card on a subscription was replaced.\n", "example": "Requested By Customer" }, "fees": { "type": "object", "description": "The fees charged for the refund.\n", "properties": { "fx_fees": { "$ref": "#/components/schemas/Money", "description": "The foreign exchange fee charged for the refund.\n" }, "txn_fees": { "$ref": "#/components/schemas/Money", "description": "The transaction fee charged for the refund.\n" } } }, "balance_used": { "type": "object", "description": "The balance deducted to process the refund, with `amount` in the smallest unit of `currency`.\n", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "USD" }, "amount": { "type": "integer", "description": "The amount deducted, in the smallest unit of `balance_used.currency` (cents for USD). `1000` is $10.00 when that currency is USD.\n", "example": 1000 } } }, "documents": { "type": "array", "items": { "anyOf": [ { "type": "object", "description": "The document attached to the refund.\n", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the Document.\n", "example": "doc_nYUqLpuYQ0M8" }, "type": { "type": "string", "description": "The type of the document.\n", "example": "rfi" }, "status": { "type": "string", "enum": [ "pending", "uploaded", "approved", "rejected" ], "description": "The status of the document.\n", "example": "pending" } } }, { "type": "object", "description": "The document required to be uploaded to respond to rfi.\n", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the Document.\n", "example": null }, "rfi_doc_id": { "type": "string", "description": "The identifier that needs to be sent when responding to rfi.\n", "example": "rfidoc_nYUqLpuYQ0M8" }, "type": { "type": "string", "description": "The type of the document.\n", "example": "rfi" }, "status": { "type": "string", "enum": [ "pending", "uploaded", "approved", "rejected" ], "description": "The status of the document.\n", "example": "pending" } } } ] } }, "status": { "type": "string", "readOnly": true, "enum": [ "in_progress", "under_review", "action_required", "success", "failed", "cancelled" ], "description": "The status of the refund.\n\n- `in_progress` — the refund has been accepted and is being sent back to the customer.\n- `under_review` — the refund is being reviewed by Glomo before it is processed.\n- `action_required` — Glomo needs more information before the refund can proceed. Respond to the\n open RFI to continue.\n- `success` — the refund has been paid out. Terminal.\n- `failed` — the refund could not be completed. Terminal.\n- `cancelled` — the refund was stopped before it was paid out. Terminal.\n", "example": "success" }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "amount": { "type": "number", "minimum": 1, "description": "The refund amount, in the smallest unit of `currency` (cents for USD). `1000` is $10.00 when `currency` is USD. `currency` is the payment's `payment_currency` (the currency the customer paid in), or its `converted_currency` when the payment has no `payment_currency`, so it can differ from the currency of the `amount` you send when creating the refund.\n", "example": 1000 }, "utr": { "type": "string", "readOnly": true, "description": "The Unique Transaction Reference (UTR) number associated with the refund.\n", "example": "UTR123456789" }, "partial_refund": { "type": "boolean", "readOnly": true, "description": "Indicates whether the refund is a partial refund.\n", "example": false }, "request_id": { "type": [ "string", "null" ], "readOnly": true, "description": "The `request_id` you sent when creating this refund; `null` if you sent none. Look the refund up with `GET /v1/refunds?request_id=`.\n", "example": "your-internal-id" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the refund was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the refund was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" } } }, "Price": { "type": "object", "x-tags": [ "Price" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the price. Pass this value as `price_id` when creating a payin or an order to apply this referral fee to it.\n", "example": "price_DdWp_HUbOnlg" }, "pricing_type": { "type": "string", "enum": [ "fixed", "percentage" ], "description": "The type of pricing to be applied.\n", "example": "fixed" }, "fees_amount": { "type": "number", "minimum": 1, "description": "The amount that will be deducted from your balance for this pricing. A positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295\n", "example": 1000 }, "fees_currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "USD" }, "bps": { "type": "number", "minimum": 1, "description": "The percentage fee, in basis points: 1 basis point is 0.01%, so `1000` is 10%. Required when `pricing_type` is `percentage`, and must not be sent when it is `fixed`.\n", "example": 1000 }, "set_as_default": { "type": "boolean", "description": "Set this pricing as default for the business. Overrides the previously set default if set to `true`.\n", "example": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the price was created, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the price was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2021-06-01T12:00:00Z" } } }, "DynamicPrice": { "type": "object", "x-tags": [ "pricing_split" ], "description": "A payin pricing rule configured by Glomo whose fee bearer is dynamic. Your business declares its own share of such a rule's fee by creating a pricing split against the rule's `id`, and the customer bears the remainder. Until a split is declared the rule is never applied, and pricing falls back to your normal (non-dynamic) rules.\n", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier of the pricing rule. Pass this value as `price_id` when you create a pricing split.\n", "example": "price_5JU9yv0lGSUP" }, "fee_type": { "type": "string", "readOnly": true, "enum": [ "transaction_fees" ], "description": "The fee this rule prices. Only `transaction_fees` rules can be declared against, so only they are listed.\n", "example": "transaction_fees" }, "payment_type": { "type": "string", "readOnly": true, "enum": [ "payin" ], "description": "The direction this rule prices. Only `payin` rules can be declared against, so only they are listed.\n", "example": "payin" }, "pricing_type": { "type": "string", "readOnly": true, "enum": [ "percentage", "fixed" ], "description": "How the fee is computed. A `percentage` rule charges `bps` of the amount. A `fixed` rule charges `fees_amount` in `fees_currency`. Declare `bps` against a `percentage` rule and `fixed_amount` against a `fixed` rule.\n", "example": "percentage" }, "payment_rail": { "type": [ "string", "null" ], "readOnly": true, "enum": [ "visa", "mastercard", "amex", null ], "description": "The card network this rule applies to. Set only on card rules, to price one network differently from the others; `null` when the rule applies to every network, and always `null` on non-card rules.\n", "example": "visa" }, "from_currency": { "type": [ "string", "null" ], "format": "iso-4217", "readOnly": true, "description": "The currency the payment is collected in, in ISO 4217 format. The rule applies only to payments in this currency. `null` when the rule applies to every currency.\n", "example": "USD" }, "bps": { "type": [ "integer", "null" ], "readOnly": true, "description": "The full fee in basis points, where 100 bps is 1%. Present on `percentage` rules and `null` on `fixed` rules. Your declared `bps` cannot exceed this value.\n", "example": 300 }, "fees_amount": { "type": [ "integer", "null" ], "readOnly": true, "description": "The full fee in the smallest unit of `fees_currency` (cents for USD). `500` is $5.00 when `fees_currency` is USD. Present on `fixed` rules and `null` on `percentage` rules. Your declared `fixed_amount` cannot exceed this value.\n", "example": 500 }, "fees_currency": { "type": [ "string", "null" ], "format": "iso-4217", "readOnly": true, "description": "The currency of `fees_amount`, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Present on `fixed` rules and `null` on `percentage` rules.\n", "example": "USD" }, "min_fee": { "type": [ "integer", "null" ], "readOnly": true, "description": "The floor the rule applies to the computed fee, in the smallest unit of `min_max_fee_currency` (cents for USD). `100` is $1.00 when `min_max_fee_currency` is USD. `null` when the rule has no floor.\n", "example": 100 }, "max_fee": { "type": [ "integer", "null" ], "readOnly": true, "description": "The cap the rule applies to the computed fee, in the smallest unit of `min_max_fee_currency` (cents for USD). `2000` is $20.00 when `min_max_fee_currency` is USD. `null` when the rule has no cap.\n", "example": 2000 }, "min_max_fee_currency": { "type": [ "string", "null" ], "format": "iso-4217", "readOnly": true, "description": "The currency of `min_fee` and `max_fee`, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. `null` when the rule has neither.\n", "example": "USD" }, "display_label": { "type": [ "string", "null" ], "readOnly": true, "description": "The label shown to your customer at checkout for the fee this rule charges.\n", "example": "Processing fee" }, "effective_from": { "type": "string", "format": "date", "readOnly": true, "description": "The date from which this version of the rule applies, in IST.\n", "example": "2026-07-01" }, "payment_method": { "type": "object", "readOnly": true, "description": "The payment method this rule applies to. A split declared against this rule prices only this payment method.\n", "properties": { "type": { "type": [ "string", "null" ], "description": "The payment method this rule applies to. One of `bank_transfer`, `pay_via_bank` or `card`.\n", "example": "bank_transfer" }, "subtype": { "type": [ "string", "null" ], "description": "The payment method subtype this rule applies to, for example `local_transfer` or `swift_transfer`. `null` when the rule applies to every subtype of `type`.\n", "example": "swift_transfer" } } } } }, "PricingSplit": { "type": "object", "x-tags": [ "pricing_split" ], "description": "Your declared share of a dynamic pricing rule's fee. The customer bears the remainder. Pass the split `id` in `split_ids` when you create a payment link, an order, a payin quote, a subscription or an auto debit.\n", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the pricing split.\n", "example": "psplit_7Kq2mXbTdLp9" }, "price_id": { "type": "string", "readOnly": true, "description": "The unique identifier of the dynamic pricing rule this split was declared against. See [List dynamic pricing rules](#tag/pricing_split).\n", "example": "price_5JU9yv0lGSUP" }, "bps": { "type": [ "integer", "null" ], "readOnly": true, "description": "Your share of the fee in basis points, where 100 bps is 1%. Present when the split was declared with `bps` and `null` otherwise.\n", "example": 150 }, "fixed_amount": { "type": [ "integer", "null" ], "readOnly": true, "description": "Your share of the fee, in the smallest unit of `fee_currency` (cents for USD). `200` is $2.00 when `fee_currency` is USD. Present when the split was declared with `fixed_amount` and `null` otherwise.\n", "example": 200 }, "min_fee": { "type": [ "integer", "null" ], "readOnly": true, "description": "The floor you declared for your share, in the smallest unit of `fee_currency` (cents for USD). `100` is $1.00 when `fee_currency` is USD. `null` when you declared no floor.\n", "example": 100 }, "max_fee": { "type": [ "integer", "null" ], "readOnly": true, "description": "The cap you declared for your share, in the smallest unit of `fee_currency` (cents for USD). `1000` is $10.00 when `fee_currency` is USD. `null` when you declared no cap.\n", "example": 1000 }, "fee_currency": { "type": [ "string", "null" ], "format": "iso-4217", "readOnly": true, "description": "The currency of `fixed_amount`, `min_fee` and `max_fee`, in ISO 4217 format.\n", "example": "USD" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the pricing split was created, as an ISO 8601 date-time in UTC.\n", "example": "2026-08-01T09:12:44Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the pricing split was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2026-08-01T09:12:44Z" } } }, "CreatePricingSplitRequest": { "type": "object", "title": "CreatePricingSplitRequest", "additionalProperties": false, "description": "Declare your share of a dynamic pricing rule's fee. The customer bears the remainder.\n\nProvide exactly one of `bps` or `fixed_amount`, and match the rule's `pricing_type`: `bps` on a `percentage` rule, `fixed_amount` on a `fixed` rule. All amounts are in minor units (cents) and `bps` is basis points, so 100 is 1%.\n", "properties": { "price_id": { "type": "string", "description": "The dynamic pricing rule to declare against, from [List dynamic pricing rules](#tag/pricing_split). The rule must belong to your business, have a dynamic fee bearer, price `payin` `transaction_fees`, be currently effective, and be the latest effective version of the rule.\n", "example": "price_5JU9yv0lGSUP" }, "bps": { "type": "integer", "minimum": 0, "description": "Your share of the fee in basis points, where 100 bps is 1%. Required on a `percentage` rule. Cannot exceed the rule's own `bps`. `0` is valid and means the customer bears the whole fee. Must be a whole number sent as a JSON integer: no decimal point (`1.5` and `1.0` are both rejected) and not a string (`\"150\"` is rejected). A negative value returns `400`.\n\nProvide exactly one of `bps` or `fixed_amount`, not both.\n", "example": 150 }, "fixed_amount": { "type": "integer", "minimum": 0, "description": "Your share of the fee, in the smallest unit of the rule's `fees_currency` (cents for USD). `200` is $2.00 when that currency is USD. Must be a whole number sent as a JSON integer: no decimal point (`1.5` and `1.0` are both rejected) and not a string (`\"150\"` is rejected). A negative value returns `400`. Required on a `fixed` rule, and cannot exceed the rule's own `fees_amount`. If you also send `fee_currency`, it must match the rule's `fees_currency`.\nProvide exactly one of `bps` or `fixed_amount`, not both.\n", "example": 200 }, "min_fee": { "type": "integer", "minimum": 0, "description": "The floor to apply to your share, in the smallest unit of `fee_currency` (cents for USD). `100` is $1.00 when `fee_currency` is USD. Must be a whole number sent as a JSON integer: no decimal point (`1.5` and `1.0` are both rejected) and not a string (`\"150\"` is rejected). A negative value returns `400`. Supported only on a `percentage` rule, and only together with `fee_currency`. Must be less than or equal to `max_fee`.\n", "example": 100 }, "max_fee": { "type": "integer", "minimum": 0, "description": "The cap to apply to your share, in the smallest unit of `fee_currency` (cents for USD). `1000` is $10.00 when `fee_currency` is USD. Must be a whole number sent as a JSON integer: no decimal point (`1.5` and `1.0` are both rejected) and not a string (`\"150\"` is rejected). A negative value returns `400`. Supported only on a `percentage` rule, and only together with `fee_currency`.\n", "example": 1000 }, "fee_currency": { "type": "string", "format": "iso-4217", "description": "The currency of `fixed_amount`, `min_fee` and `max_fee`, in ISO 4217 format. Required when you declare `min_fee` or `max_fee`. On a `fixed` rule it must equal the rule's `fees_currency`; omit it and Glomo derives it from the rule.\n", "example": "USD" } }, "required": [ "price_id" ] }, "Amount": { "type": "number", "description": "The amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.\n", "example": 1000 }, "Currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "USD" }, "IntervalType": { "type": "string", "description": "Used in combination with interval_count to define the billing cycle frequency.", "enum": [ "month", "year", "as_presented" ] }, "IntervalCount": { "type": [ "integer", "null" ], "description": "Number of intervals between a billing cycle, used in combination with interval_type.\nValid combinations:\n- Monthly: interval_type='month', interval_count=1\n- Quarterly: interval_type='month', interval_count=3\n- Half-yearly: interval_type='month', interval_count=6\n- Yearly: interval_type='year', interval_count=1\n- As Presented: interval_type='as_presented', interval_count=null\n", "enum": [ 1, 3, 6, null ] }, "Subscription": { "x-tags": [ "Subscription" ], "type": "object", "description": "Subscription resource represents a recurring billing agreement for a customer", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "sub_5JU9yv0lGSUP" }, "customer_id": { "type": "string", "description": "Unique identifier of the customer associated with this subscription.", "example": "cust_5JU9yv0lGSUP" }, "product_name": { "type": "string", "description": "Name of the product being subscribed to.", "example": "ShieldGuard Insurance" }, "product_description": { "type": "string", "description": "Description of the product.", "example": "Flexible, monthly insurance for belongings, travel, and digital assets, easy to manage" }, "plan_name": { "type": "string", "description": "Name of the subscription plan.", "example": "ShieldGuard Lite" }, "plan_description": { "type": "string", "description": "Description of the subscription plan.", "example": "Simple, monthly insurance plan that covers your basic belongings and key digital assets" }, "reference_number": { "type": "string", "description": "optional identifier to be sent for reconciliations\n", "example": "R0001" }, "status": { "type": "string", "description": "Current status of the subscription.\n\n- `created` — the subscription exists and is waiting for the customer to authorise it.\n- `authorized` — the customer has authorised the subscription and it has not become `active` yet.\n- `active` — the subscription is charging on its schedule.\n- `paused` — you paused the subscription. Resume it to continue charging.\n- `halted` — charging stopped automatically; `halt_reason` says why. It returns to `active` after\n its next successful payment, for example once the customer updates the card. The resume endpoint\n applies only to `paused` subscriptions.\n- `action_required` — Glomo needs more information before the subscription can proceed. Respond to\n the open RFI to continue.\n- `under_review` — the information you submitted is being reviewed. The subscription becomes\n `active` if the review passes and `failed` if it does not.\n- `completed` — every billing cycle has been charged. Terminal.\n- `cancelled` — the subscription was cancelled. Terminal.\n- `expired` — the customer did not authorise the subscription in time. Terminal.\n- `failed` — the subscription could not be set up, or did not pass review. Terminal.\n", "enum": [ "created", "authorized", "active", "paused", "halted", "action_required", "under_review", "completed", "cancelled", "expired", "failed" ], "example": "active" }, "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "$ref": "#/components/schemas/Currency" }, "interval_type": { "$ref": "#/components/schemas/IntervalType" }, "interval_count": { "$ref": "#/components/schemas/IntervalCount" }, "billing_cycles": { "type": [ "integer", "null" ], "description": "Total number of billing cycles for the subscription. Each cycle lasts `interval_count` units of `interval_type`, so 12 cycles with `interval_count` 1 and `interval_type` `month` span 12 months. `null` for `as_presented` subscriptions.\n", "example": 12 }, "max_amount": { "type": [ "integer", "null" ], "description": "Maximum allowed amount per payment, in the smallest unit of `currency` (cents for USD). `5000` is $50.00 when `currency` is USD. Present only for `as_presented` subscriptions, `null` for regular subscriptions.\n", "example": 5000 }, "start_date": { "type": "string", "format": "date", "description": "Start date of the subscription in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-01-01" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "The date on which the subscription ends in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-12-01" }, "expires_at": { "type": "string", "format": "date", "description": "Expiration date for the subscription payment link in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-01-07" }, "next_payment_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the next scheduled payment in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-02-01" }, "subscription_link_url": { "type": "string", "format": "uri", "description": "URL for the subscription payment page. Your customer can use this URL to make the first payment and activate the subscription. The path is `/subscription-links/{id}`; in sandbox the URL ends with `?sandbox=true`. The host depends on your account, so share the URL exactly as returned rather than building it yourself.\n", "example": "https://your-dashboard-host.example/subscription-links/sub_5JU9yv0lGSUP" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date", "description": "Date when the subscription was cancelled in UTC timezone and ISO 8601 format (YYYY-MM-DD). This field is null unless the subscription status is 'cancelled'.", "example": "2025-01-15" }, "halt_reason": { "type": [ "object", "null" ], "description": "Present only when `status` is `halted`. Describes why the subscription was halted. Absent for all other statuses.\n", "properties": { "code": { "type": "string", "description": "Machine-readable halt reason code.\n\n- `MAX_RETRIES_REACHED` — every retry of a failed charge was used up without a successful payment.\n- `CARD_EXPIRED` — the card saved on the subscription has expired.\n- `MIGRATION_INCOMPLETE` — the Visa card was not re-registered with Glomo's new card-processing\n setup within the migration window.\n", "enum": [ "MAX_RETRIES_REACHED", "CARD_EXPIRED", "MIGRATION_INCOMPLETE" ], "example": "MAX_RETRIES_REACHED" }, "description": { "type": "string", "description": "Human-readable explanation of the halt reason.", "example": "The maximum number of auto-debit retry attempts was reached without a successful payment." } }, "required": [ "code", "description" ] }, "notes": { "$ref": "#/components/schemas/Notes" }, "payment_method": { "type": [ "object", "null" ], "description": "The active payment method on the subscription, derived from the most recent successful payment. Returns `null` if no successful payment has been made yet (e.g. a newly created subscription or one where the first payment attempt failed).\n", "properties": { "type": { "type": "string", "enum": [ "card" ], "description": "The type of payment method. Currently only `card` is supported for subscriptions. Additional types (e.g. UPI, wallets) will be added as subscription support is extended.\n", "example": "card" }, "details": { "type": "object", "description": "Details specific to the payment method type.\n", "properties": { "card_network": { "type": "string", "description": "The card network (e.g., Visa, Mastercard, American Express).\n", "example": "Visa" }, "card_type": { "type": "string", "description": "The type of card (e.g., credit, debit).\n", "example": "credit" }, "end_digits": { "type": "string", "description": "The last four digits of the card number.\n", "example": "4242" }, "country_code": { "type": "string", "description": "The country code associated with the card.\n", "example": "IN" }, "card_holder_name": { "type": "string", "description": "The name of the cardholder.\n", "example": "John Doe" }, "card_bin": { "type": "string", "description": "The IIN (also known as BIN) — the card-number prefix that identifies the network, card type, and issuing country.\n", "example": "424242" }, "issuer_name": { "type": "string", "description": "The name of the card issuing bank or financial institution.\n", "example": "HDFC Bank" } } } }, "example": { "type": "card", "details": { "card_network": "Visa", "card_type": "credit", "end_digits": "4242", "country_code": "IN", "card_holder_name": "John Doe", "card_bin": "424242", "issuer_name": "HDFC Bank" } } } }, "required": [ "id", "customer_id", "product_name", "product_description", "status", "amount", "currency", "interval_type", "start_date", "expires_at", "subscription_link_url" ] }, "CreateSubscriptionRequest": { "type": "object", "description": "Request payload for creating a new subscription", "properties": { "customer_id": { "type": "string", "description": "Unique identifier of the customer associated with this subscription.", "example": "cust_5JU9yv0lGSUP" }, "product_name": { "type": "string", "maxLength": 128, "description": "Name of the product being subscribed to. Up to 128 characters, using only letters `A`–`Z` and `a`–`z`, digits, whitespace, hyphens, underscores, periods, commas, parentheses and ampersands. Accented letters and any other symbol are rejected. A value that breaks either rule returns `400` with a message such as `Product name contains invalid characters…` or `Product name is too long (maximum is 128 characters)`.\n", "example": "ShieldGuard Insurance" }, "product_description": { "type": "string", "maxLength": 512, "description": "Description of the product. Up to 512 characters. Allows the same characters as `product_name`, plus exclamation marks, colons, single quotes and asterisks; accented letters and any other symbol are rejected. A value that breaks either rule returns `400`.\n", "example": "Flexible monthly insurance for belongings travel and digital assets easy to manage" }, "plan_name": { "type": "string", "maxLength": 128, "description": "Name of the subscription plan. Optional. A non-blank value follows the same rules as `product_name`: up to 128 characters, and the same allowed characters.\n", "example": "ShieldGuard Lite" }, "plan_description": { "type": "string", "maxLength": 512, "description": "Description of the subscription plan. Optional. A non-blank value follows the same rules as `product_description`: up to 512 characters, and the same allowed characters.\n", "example": "Simple, monthly insurance plan that covers your basic belongings and key digital assets" }, "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "$ref": "#/components/schemas/Currency" }, "interval_type": { "$ref": "#/components/schemas/IntervalType" }, "interval_count": { "$ref": "#/components/schemas/IntervalCount" }, "billing_cycles": { "type": "integer", "minimum": 2, "description": "Total number of billing cycles for the subscription. Required for regular subscriptions, must not be provided for 'as_presented' subscriptions.\nA subscription can have a lifetime of 30 years.\nMaximum billing cycles therefore depend on interval:\n- Monthly (interval_type='month', interval_count=1): max 360 cycles\n- Quarterly (interval_type='month', interval_count=3): max 120 cycles\n- Half-yearly (interval_type='month', interval_count=6): max 60 cycles\n- Yearly (interval_type='year', interval_count=1): max 30 cycles\n\nSend an integer of at least `2` as a JSON number; a string such as `\"12\"` is rejected. A value below\n`2` or above the interval's maximum returns `400`.\n", "example": 12 }, "max_amount": { "type": "integer", "minimum": 1, "description": "Maximum allowed amount per payment for `as_presented` subscriptions, in the smallest unit of `currency` (cents for USD). `5000` is $50.00 when `currency` is USD. A positive integer. Required when `interval_type` is `as_presented`, and must not be provided for regular subscriptions.\nSubsequent payments on the subscription cannot exceed this amount.\n", "example": 5000 }, "start_date": { "type": "string", "format": "date", "description": "Start date of the subscription in UTC timezone and ISO 8601 format (YYYY-MM-DD). Must be today or in the future.\nRequired for regular subscriptions, must not be provided for 'as_presented' subscriptions.\n", "example": "2025-01-01" }, "expires_at": { "type": "string", "format": "date", "description": "Expiration date for the subscription payment link in UTC timezone and ISO 8601 format (YYYY-MM-DD). Must be today (UTC) or later, and at most 1 calendar month after today (UTC). An earlier date returns `400` with the message `Validation failed: Expires at must be today or in the future`, and a later one returns `400` with `Validation failed: Expires at cannot be more than 1 months from today`. It is not compared with `start_date`.\n", "example": "2026-10-15", "x-glomo-relative-example": "P7D" }, "notify_customer": { "type": "boolean", "description": "Whether to send notification e-mails to customers for subscription lifecycle changes.", "example": true }, "notes": { "$ref": "#/components/schemas/Notes" }, "reference_number": { "type": "string", "description": "optional identifier to be sent for reconciliations\n", "example": "R0001" }, "starts_with_first_payment": { "type": "boolean", "description": "Whether the subscription payment schedule should get synchronized with the first payment.", "example": true }, "split_ids": { "allOf": [ { "$ref": "#/components/schemas/SplitIds" } ], "description": "Supported only when `interval_type` is `as_presented`. Sending `split_ids` on a fixed-frequency subscription returns a `400 Bad Request`, because a fixed-frequency plan auto debits without you and so has no point at which to pass a split or replace one that goes stale.\n\nThe declaration applies to the first payment, and to every subsequent auto debit that does not pass `split_ids` of its own. See [Create a payment](#tag/Payment) for the auto debit override.\n" } }, "required": [ "customer_id", "product_name", "product_description", "amount", "currency", "interval_type", "expires_at", "notify_customer", "starts_with_first_payment" ] }, "CreateSubscriptionResponse": { "x-tags": [ "Subscription" ], "type": "object", "description": "Subscription resource represents a recurring billing agreement for a customer", "properties": { "id": { "type": "string", "description": "Unique identifier for the subscription.", "example": "sub_5JU9yv0lGSUP" }, "customer_id": { "type": "string", "description": "Unique identifier of the customer associated with this subscription.", "example": "cust_5JU9yv0lGSUP" }, "product_name": { "type": "string", "description": "Name of the product being subscribed to.", "example": "ShieldGuard Insurance" }, "product_description": { "type": "string", "description": "Description of the product.", "example": "Flexible, monthly insurance for belongings, travel, and digital assets, easy to manage" }, "plan_name": { "type": "string", "description": "Name of the subscription plan.", "example": "ShieldGuard Lite" }, "plan_description": { "type": "string", "description": "Description of the subscription plan.", "example": "Simple, monthly insurance plan that covers your basic belongings and key digital assets" }, "reference_number": { "type": "string", "description": "optional identifier to be sent for reconciliations\n", "example": "R0001" }, "status": { "type": "string", "description": "Current status of the subscription.\n\n- `created` — the subscription exists and is waiting for the customer to authorise it.\n- `authorized` — the customer has authorised the subscription and it has not become `active` yet.\n- `active` — the subscription is charging on its schedule.\n- `paused` — you paused the subscription. Resume it to continue charging.\n- `halted` — charging stopped automatically; `halt_reason` says why. It returns to `active` after\n its next successful payment, for example once the customer updates the card. The resume endpoint\n applies only to `paused` subscriptions.\n- `action_required` — Glomo needs more information before the subscription can proceed. Respond to\n the open RFI to continue.\n- `under_review` — the information you submitted is being reviewed. The subscription becomes\n `active` if the review passes and `failed` if it does not.\n- `completed` — every billing cycle has been charged. Terminal.\n- `cancelled` — the subscription was cancelled. Terminal.\n- `expired` — the customer did not authorise the subscription in time. Terminal.\n- `failed` — the subscription could not be set up, or did not pass review. Terminal.\n", "enum": [ "created", "authorized", "active", "paused", "halted", "action_required", "under_review", "completed", "cancelled", "expired", "failed" ], "example": "active" }, "amount": { "$ref": "#/components/schemas/Amount" }, "currency": { "$ref": "#/components/schemas/Currency" }, "interval_type": { "$ref": "#/components/schemas/IntervalType" }, "interval_count": { "$ref": "#/components/schemas/IntervalCount" }, "billing_cycles": { "type": [ "integer", "null" ], "description": "Total number of billing cycles for the subscription. Each cycle lasts `interval_count` units of `interval_type`, so 12 cycles with `interval_count` 1 and `interval_type` `month` span 12 months. `null` for `as_presented` subscriptions.\n", "example": 12 }, "max_amount": { "type": [ "integer", "null" ], "description": "Maximum allowed amount per payment, in the smallest unit of `currency` (cents for USD). `5000` is $50.00 when `currency` is USD. Present only for `as_presented` subscriptions, `null` for regular subscriptions.\n", "example": 5000 }, "start_date": { "type": "string", "format": "date", "description": "Start date of the subscription in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-01-01" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "The date on which the subscription ends in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-12-01" }, "expires_at": { "type": "string", "format": "date", "description": "Expiration date for the subscription payment link in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-01-07" }, "next_payment_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the next scheduled payment in UTC timezone and ISO 8601 format (YYYY-MM-DD).", "example": "2025-02-01" }, "subscription_link_url": { "type": "string", "format": "uri", "description": "URL for the subscription payment page. Your customer can use this URL to make the first payment and activate the subscription. The path is `/subscription-links/{id}`; in sandbox the URL ends with `?sandbox=true`. The host depends on your account, so share the URL exactly as returned rather than building it yourself.\n", "example": "https://your-dashboard-host.example/subscription-links/sub_5JU9yv0lGSUP" }, "cancelled_at": { "type": [ "string", "null" ], "format": "date", "description": "Date when the subscription was cancelled in UTC timezone and ISO 8601 format (YYYY-MM-DD). This field is null unless the subscription status is 'cancelled'.", "example": "2025-01-15" }, "notes": { "$ref": "#/components/schemas/Notes" } }, "required": [ "id", "customer_id", "product_name", "product_description", "status", "amount", "currency", "interval_type", "start_date", "expires_at", "subscription_link_url" ] }, "UpdateSubscriptionNextPaymentDate": { "type": "object", "properties": { "next_payment_date": { "type": "string", "description": "The next payment date in ISO 8601 format.\n", "example": "2025-11-19" } } }, "Settlement": { "type": "object", "x-tags": [ "Settlement" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the settlement.\n", "example": "setl_6878e266jt1P3" }, "status": { "type": "string", "description": "The status of the settlement.\n", "example": "success" }, "payment_method": { "type": "string", "description": "The payment method used for the settlement.\n", "example": "swift_transfer" }, "amount": { "type": "number", "minimum": 1, "description": "The amount of the settlement, in the smallest unit of `currency` (paise for INR, cents for USD). `1000` is $10.00 when `currency` is USD.\n", "example": 1000 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency in which the settlement is made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" }, "fees": { "type": "object", "description": "The fees associated with the settlement.\n", "properties": { "fx_fee": { "type": "object", "description": "The foreign-exchange fee charged for the settlement in cents.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The foreign exchange fee, in the smallest unit of this fee's `currency`. `10` is $0.10 when that currency is USD.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } }, "txn_fee": { "type": "object", "description": "The transaction fee charged for the settlement in cents.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The transaction fee, in the smallest unit of this fee's `currency`. `10` is $0.10 when that currency is USD.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } } } }, "utr": { "type": "string", "description": "The Unique Transaction Reference (UTR) for the settlement.\n", "example": "1568176960vxp0rj" }, "created_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the settlement was created, as an ISO 8601 date-time in UTC.\n", "example": "2024-12-06T11:38:37.130Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the settlement was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2024-12-06T11:38:37.130Z" } } }, "CreateSettlementRequest": { "type": "object", "x-internal": true, "required": [ "amount", "balance_currency" ], "properties": { "amount": { "type": "number", "minimum": 1, "description": "The amount to settle, in the smallest unit of `balance_currency` (paise for INR, cents for USD). `1000` is $10.00 when `balance_currency` is USD. A fractional value is truncated to a whole number.\n", "example": 1000 }, "balance_currency": { "type": "string", "format": "iso-4217", "description": "The balance you want to settle from, as an upper-case [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code such as `USD`. The amount is deducted from this balance. It must match the currency of an active withdrawal account on your account, and the match is exact: a lower-case code, or a currency with no active withdrawal account, returns `404` with `Withdrawal account not found`.\n", "example": "USD" } } }, "Transaction": { "type": "object", "x-tags": [ "Transaction" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the transaction.\n", "example": "txn_687f1f8ePcIYg" }, "source_id": { "type": "string", "description": "The unique identifier of the source for the transaction.\n", "example": "payt_687f1f833Hdgx" }, "source_type": { "type": "string", "description": "The type of the source for the transaction.\n", "example": "payment" }, "transaction_type": { "type": "string", "enum": [ "credit", "debit" ], "description": "The direction of the transaction. A credit adds to your balance. A debit takes from it.\n", "example": "credit" }, "credit": { "type": "object", "description": "The credit details for the transaction, with `amount` in the smallest unit of `currency`.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The amount credited, in the smallest unit of `currency` (cents for USD). `1000` is $10.00 when `currency` is USD.\n", "example": 1000 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } }, "debit": { "type": "object", "description": "The debit details for the transaction, with `amount` in the smallest unit of `currency`.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The amount debited, in the smallest unit of `currency` (cents for USD). `1000` is $10.00 when `currency` is USD.\n", "example": 0 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } }, "fees": { "type": "object", "description": "The fees associated with the transaction.\n", "properties": { "fx_fee": { "type": "object", "description": "The foreign-exchange fee charged for the transaction in cents.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The foreign exchange fee, in the smallest unit of this fee's `currency` (cents for USD). `10` is $0.10 when that currency is USD.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } }, "txn_fee": { "type": "object", "description": "The transaction fee charged for the transaction in cents.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The transaction fee, in the smallest unit of this fee's `currency` (cents for USD). `10` is $0.10 when that currency is USD.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } } } }, "settled_amount": { "type": "object", "description": "The details of the amount settled in this transaction, with `amount` in the smallest unit of `currency`.\n", "properties": { "amount": { "type": "number", "minimum": 1, "description": "The amount settled, in the smallest unit of `currency` (cents for USD). `980` is $9.80 when `currency` is USD.\n", "example": 980 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n", "example": "USD" } } }, "processed_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the transaction was processed, as an ISO 8601 date-time in UTC.\n", "example": "2024-12-06T11:38:37.130Z" }, "created_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the transaction was created, as an ISO 8601 date-time in UTC.\n", "example": "2024-12-06T11:38:37.130Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the transaction was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2024-12-06T11:38:37.130Z" } } }, "VirtualAccount": { "type": "object", "x-tags": [ "virtual_account" ], "properties": { "account_id": { "type": "string", "readOnly": true, "description": "The unique identifier for the virtual account.\n", "example": "va_6943ae9eFO3GW" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The currency of the virtual account in ISO 4217 format.\n", "example": "USD" }, "name": { "type": "string", "readOnly": true, "description": "The name associated with the virtual account, typically the business name.\n", "example": "test response" }, "status": { "type": "string", "enum": [ "active", "inactive", "disabled" ], "readOnly": true, "description": "The current status of the virtual account.\n\n- `active` — the account can receive funds.\n- `inactive` — the account exists but cannot receive funds yet.\n- `disabled` — the account has been closed and does not receive funds.\n", "example": "active" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the virtual account was created, as an ISO 8601 date-time in UTC.\n", "example": "2025-08-19T07:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the virtual account was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2025-08-19T07:00:00Z" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the virtual account was disabled, as an ISO 8601 date-time in UTC. `null` if the account has not been disabled.\n", "example": null }, "merchant_id": { "type": "string", "readOnly": true, "description": "The unique identifier for the merchant associated with the virtual account.\n", "example": "merch_694bb0289P4Cz" }, "account_number": { "type": "string", "readOnly": true, "description": "The unique account number for the virtual account, formatted according to the country's banking standards. Applicable for AED, GBP, AUD, and USD accounts.\n", "example": "AE580863912382801669068" }, "iban": { "type": "string", "readOnly": true, "description": "The International Bank Account Number (IBAN) for the virtual account. Applicable for EUR accounts.\n", "example": "DK2089000025417759" }, "sort_code": { "type": "string", "readOnly": true, "description": "The sort code for the virtual account. Applicable for GBP accounts.\n", "example": "608382" }, "bsb_number": { "type": "string", "readOnly": true, "description": "The Bank State Branch (BSB) number for the virtual account. Applicable for AUD accounts.\n", "example": "252000" }, "routing_number": { "type": "string", "readOnly": true, "description": "The routing number for the virtual account. Applicable for USD accounts.\n", "example": "026009593" }, "payment_rails": { "type": "string", "readOnly": true, "description": "The payment rail type for the virtual account. Applicable for USD accounts. Possible values are 'ach' for ACH transfers and 'wire' for Fedwire transfers.\n", "enum": [ "ach", "wire" ], "example": "ach" } }, "required": [ "account_id", "currency", "name", "status", "created_at", "updated_at", "merchant_id" ] }, "CreateMerchantRequestBase": { "type": "object", "x-internal": true, "properties": { "name": { "type": "string", "description": "Name of the merchant business", "example": "Child Business Name" }, "address_line1": { "type": "string", "description": "Primary address line", "example": "456 Commerce Street" }, "address_line2": { "type": "string", "description": "Secondary address line (optional)", "example": "Suite 101" }, "city": { "type": "string", "description": "City name", "example": "Mumbai" }, "state": { "type": "string", "description": "State or province", "example": "Maharashtra" }, "pincode": { "type": "string", "description": "Postal/ZIP code", "example": "400001" }, "registration_number": { "type": "string", "description": "Registration number of the merchant. For a `business`, the company registration number. For an `individual`, the PAN (Permanent Account Number), for example `ABCDE1234F`.", "example": "REG123456" }, "registration_country": { "type": "string", "description": "Country where the business is registered (ISO 3166-1 alpha-3)", "example": "IND" }, "category": { "type": "string", "description": "Merchant business category", "enum": [ "Agricultural Services", "Contracted Services", "Transportation Services", "Telecommunications", "Utilities", "Retail and Goods", "Financial Services", "Business Services", "Professional Services", "Government Services" ], "example": "Agricultural Services" }, "sub_category": { "type": "string", "description": "Merchant business sub-category (must be paired with correct category, check examples)", "enum": [ "Veterinary Services", "Agricultural Cooperatives", "Horticultural and Landscaping Services", "General Contractors—Residential and Commercial", "Air Conditioning Heating and Plumbing Contractors", "Electrical Contractors", "Insulation Masonry Plastering Stonework and Tile Setting Contractors", "Carpentry Contractors", "Roofing and Siding Sheet Metal Work Contractors", "Concrete Work Contractors", "Contractors Special Trade—not elsewhere classified", "Miscellaneous Publishing and Printing", "Typesetting Plate Making and Related Services", "Sanitation Polishing and Specialty Cleaning Preparations", "Railroads—Freight", "Transportation—Suburban and Local Commuter Passenger including Ferries", "Passenger Railways", "Ambulance Services", "Limousines and Taxicabs", "Bus Lines", "Motor Freight Carriers Trucking—Local/Long Distance Moving and Storage Companies Local Delivery", "Courier Services—Air and Ground Freight Forwarders", "Public Warehousing—Farm Products Refrigerated Goods Household Goods Storage", "Cruise Lines", "Boat Leases and Boat Rentals", "Marinas Marine Service/Supplies", "Air Carriers Airlines—Not Elsewhere Classified", "Airports Airport Terminals Flying Fields", "Travel Agencies and Tour Operators", "Bridge and Road Fees Tolls", "Transportation Services—not elsewhere classified", "Telecommunication Equipment Including Telephone Sales", "Key-entry Telecom Merchant providing single local and long-distance phone calls using a central access number in a non-face-to-face environment using key entry", "Telecommunication Services including but not limited to prepaid phone services and recurring phone services", "Computer Network/Information Services", "Telegraph Services", "Money Transfer", "Cable Satellite and Other Pay Television and Radio Services", "Utilities—Electric Gas Heating Oil Sanitary Water", "Motor Vehicle Supplies and New Parts", "Office and Commercial Furniture", "Construction Materials—not elsewhere classified", "Office Photographic Photocopy and Microfilm Equipment", "Computers Computer Peripheral Equipment Software", "Commercial Equipment—not elsewhere classified", "Dental/Laboratory/Medical/Ophthalmic Hospital Equipment and Supplies", "Metal Service Centers and Offices", "Electrical Parts and Equipment", "Hardware Equipment and Supplies", "Plumbing and Heating Equipment", "Industrial Supplies—not elsewhere classified", "Precious Stones and Metals Watches and Jewelry", "Durable Goods—not elsewhere classified", "Stationery Office Supplies Printing and Writing Paper", "Drugs Drug Proprietors and Druggists Sundries", "Piece Goods Notions and Other Dry Goods", "Men's Women's and Children's Uniforms and Commercial Clothing", "Commercial Footwear", "Chemicals and Allied Products—not elsewhere classified", "Petroleum and Petroleum Products", "Books Periodicals and Newspapers", "Florists Supplies Nursery Stock and Flowers", "Paints Varnishes and Supplies", "Nondurable Goods—not elsewhere classified", "Home Supply Warehouse Stores", "Building Materials Lumber Stores", "Glass Paint Wallpaper Stores", "Hardware Stores", "Lawn and Garden Supply Stores", "Mobile Home Dealers", "Wholesale Clubs", "Duty Free Stores", "Discount Stores", "Department Stores", "Variety Stores", "Miscellaneous General Merchandise Stores", "Grocery Stores Supermarkets", "Freezer Locker Meat Provisioners", "Candy Nut Confectionery Stores", "Dairy Products Stores", "Bakeries", "Miscellaneous Food Stores—Convenience Stores Markets Specialty Stores", "Automobile and Truck Dealers—Sales Service Repairs Parts and Leasing", "Automobile and Truck Dealers—(Used Only)—Sales", "Auto Store Home Supply Stores", "Automotive Tire Stores", "Automotive Parts Accessories Stores", "Service Stations (with or without Ancillary Services)", "Fuel Dispenser Automated", "Boat Dealers", "Camper Dealers Recreational and Utility Trailers", "Motorcycle Shops and Dealers", "Motor Home Dealers", "Snowmobile Dealers", "Miscellaneous Automotive Aircraft and Farm Equipment Dealers—not elsewhere classified", "Men's and Boys' Clothing and Accessories Stores", "Women's Ready to Wear Stores", "Women's Accessory and Specialty Stores", "Children's and Infants' Wear Stores", "Family Clothing Stores", "Sports Apparel Riding Apparel Stores", "Shoe Stores", "Furriers and Fur Shops", "Men's and Women's Clothing Stores", "Alterations Mending Seamstresses Tailors", "Wig and Toupee Shops", "Accessory and Apparel Stores—Miscellaneous", "Equipment Furniture and Home Furnishings Stores (except Appliances)", "Floor Covering Stores", "Drapery Upholstery and Window Coverings Stores", "Fireplace Fireplace Screens and Accessories Stores", "Miscellaneous House Furnishing Specialty Shops", "Household Appliance Stores", "Electronic Sales", "Music Stores—Musical Instruments Pianos Sheet Music", "Computer Software Stores", "Record Shops", "Caterers", "Eating Places Restaurants", "Bars Cocktail Lounges Discotheques Nightclubs and Taverns—Drinking Places (Alcoholic Beverages)", "Fast Food Restaurants", "Digital Goods—Audiovisual Media Including Books Movies and Music", "Digital Goods—Games", "Digital Goods—Software Applications (Excluding Games)", "Digital Goods—Multi-Category", "Drug Stores Pharmacies", "Package Stores Beer Wine and Liquor", "Second Hand Stores Used Merchandise Stores", "Antique Shops—Sales Repairs and Restoration Services", "Pawn Shops", "Salvage and Wrecking Yards", "Antique Reproduction Stores", "Bicycle Shops—Sales and Service", "Sporting Goods Stores", "Book Stores", "Office School Supply and Stationery Stores", "Clock Jewelry Watch and Silverware Store", "Game Toy and Hobby Shops", "Camera and Photographic Supply Stores", "Card Gift Novelty and Souvenir Shops", "Leather Goods and Luggage Stores", "Fabric Needlework Piece Goods and Sewing Stores", "Crystal and Glassware Stores", "Direct Marketing—Insurance Services", "Direct Marketing—Travel-Related Arrangement Services", "Door-to-Door Sales", "Direct Marketing—Catalog Merchants", "Direct Marketing—Combination Catalog and Retail Merchants", "Direct Marketing—Outbound Telemarketing Merchants", "Direct Marketing—Inbound Telemarketing Merchants", "Direct Marketing—Continuity/Subscription Merchants", "Direct Marketing—Other Direct Marketers—not elsewhere classified", "Artist Supply Stores Craft Shops", "Art Dealers and Galleries", "Stamp and Coin Stores—Philatelic and Numismatic Supplies", "Religious Goods Stores", "Hearing Aids—Sales Service Supply Stores", "Orthopedic Goods—Artificial Limb Stores", "Cosmetic Stores", "Typewriter Stores—Rentals Sales Service", "Fuel Dealers—Coal Fuel Oil Liquefied Petroleum Wood", "Florists", "Cigar Stores and Stands", "News Dealers and Newsstands", "Pet Shops—Pet Food and Supplies", "Swimming Pools—Sales and Supplies", "Electric Razor Stores—Sales and Service", "Tent and Awning Shops", "Miscellaneous and Specialty Retail Stores", "Manual Cash Disbursements—Customer Financial Institution", "Automated Cash Disbursements—Customer Financial Institution", "Merchandise and Services—Customer Financial Institution", "Quasi Cash—Customer Financial Institution", "Quasi Cash—Merchant", "Securities—Brokers/Dealers", "Insurance Sales Underwriting and Premiums", "Real Estate Agents and Managers—Rentals", "Payment Transaction—Customer Financial Institution", "Payment Transaction—Merchant", "MoneySend Intracountry", "MoneySend Intercountry", "MoneySend Funding", "POI Funding Transactions (Excluding MoneySend)", "Lodging—Hotels Motels Resorts—not elsewhere classified", "Timeshares", "Recreational and Sporting Camps", "Campgrounds and Trailer Parks", "Cleaning Garment and Laundry Services", "Laundry Services—Family and Commercial", "Dry Cleaners", "Carpet and Upholstery Cleaning", "Photographic Studios", "Barber and Beauty Shops", "Hat Cleaning Shops Shoe Repair Shops Shoe Shine Parlors", "Funeral Service and Crematories", "Dating Services", "Tax Preparation Service", "Debt Marriage Personal—Counseling Service", "Buying/Shopping Clubs Services", "Clothing Rental—Costumes Uniforms and Formal Wear", "Massage Parlors", "Health and Beauty Spas", "Other Services—not elsewhere classified", "Advertising Services", "Consumer Credit Reporting Agencies", "Commercial Art Graphics Photography", "Quick Copy Reproduction and Blueprinting Services", "Stenographic and Secretarial Support Services", "Exterminating and Disinfecting Services", "Cleaning and Maintenance Janitorial Services", "Employment Agencies Temporary Help Services", "Computer Programming Data Processing and Integrated Systems Design Services", "Information Retrieval Services", "Computer Maintenance Repair and Services—not elsewhere classified", "Consulting Management and Public Relations Services", "Detective Agencies Protective Agencies Security Services including Armored Cars Guard Dogs", "Equipment Rental and Leasing Services Furniture Rental Tool Rental", "Photo Developing Photofinishing Laboratories", "Business Services—not elsewhere classified", "Automobile Rental Agency—not elsewhere classified", "Truck Rental", "Motor Home and Recreational Vehicle Rental", "Automobile Parking Lots and Garages", "Automotive Body Repair Shops", "Tire Retreading and Repair Shops", "Automotive Paint Shops", "Automotive Service Shops", "Car Washes", "Towing Services", "Electronic Repair Shops", "Air Conditioning and Refrigeration Repair Shops", "Appliance Repair Shops Electrical and Small", "Clock Jewelry and Watch Repair Shops", "Furniture—Reupholstery and Repair Refinishing", "Welding Repair", "Miscellaneous Repair Shops and Related Services", "Government Owned Lottery (U.S. Region Only)", "Internet Gambling (U.S. Region Only)", "Government Licensed Horse/Dog Racing (U.S. Region Only)", "Motion Picture and Video Tape Production and Distribution", "Motion Picture Theaters", "Video Entertainment Rental Stores", "Dance Halls Schools and Studios", "Theatrical Producers (except Motion Pictures) Ticket Agencies", "Bands Orchestras and Miscellaneous Entertainers—not elsewhere classified", "Pool and Billiard Establishments", "Bowling Alleys", "Athletic Fields Commercial Sports Professional Sports Clubs Sports Promoters", "Tourist Attractions and Exhibits", "Golf Courses Public", "Video Amusement Game Supplies", "Video Game Arcades/Establishments", "Gambling Transactions", "Amusement Parks Carnivals Circuses Fortune Tellers", "Clubs—Country Clubs Membership (Athletic Recreation Sports) Private Golf Courses", "Aquariums Dolphinariums Zoos and Seaquariums", "Recreation Services—not elsewhere classified", "Doctors—not elsewhere classified", "Dentists Orthodontists", "Osteopathic Physicians", "Chiropractors", "Optometrists Ophthalmologists", "Opticians Optical Goods and Eyeglasses", "Chiropodists Podiatrists", "Nursing and Personal Care Facilities", "Hospitals", "Dental and Medical Laboratories", "Health Practitioners Medical Services—not elsewhere classified", "Attorneys Legal Services", "Schools Elementary and Secondary", "Colleges Universities Professional Schools and Junior Colleges", "Schools Correspondence", "Schools Business and Secretarial", "Schools Trade and Vocational", "Schools and Educational Services—not elsewhere classified", "Child Care Services", "Organizations Charitable and Social Service", "Associations—Civic Social and Fraternal", "Organizations Political", "Organizations Religious", "Automobile Associations", "Organizations Membership—not elsewhere classified", "Testing Laboratories (Non-Medical)", "Architectural Engineering and Surveying Services", "Accounting Auditing and Bookkeeping Services", "Professional Services—not elsewhere classified", "Court Costs including Alimony and Child Support", "Fines", "Bail and Bond Payments", "Tax Payments", "Government Services—not elsewhere classified", "Postal Services—Government Only", "Intra-Government Purchases—Government Only", "Government-owned Lottery (Specific Countries)" ], "example": "Veterinary Services" }, "operation_countries": { "type": "array", "description": "List of countries where the merchant operates", "items": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "example": [ "IND", "USA" ] } }, "required": [ "name", "address_line1", "city", "state", "pincode", "registration_number", "registration_country", "entity_type", "category", "sub_category", "operation_countries" ] }, "CreateIndividualMerchantRequest": { "x-internal": true, "allOf": [ { "$ref": "#/components/schemas/CreateMerchantRequestBase" }, { "type": "object", "properties": { "entity_type": { "type": "string", "description": "Type of entity", "enum": [ "individual" ], "example": "individual" }, "date_of_birth": { "type": "string", "format": "date", "description": "Date of birth. Format YYYY-MM-DD", "example": "2001-08-04" }, "gender": { "type": "string", "description": "Gender", "enum": [ "male", "female", "undefined" ], "example": "male" }, "passport": { "type": "object", "description": "Passport identification", "properties": { "number": { "type": "string", "description": "Passport number", "example": "P1234567" }, "expiry_date": { "type": "string", "format": "date", "description": "Passport expiry date. Must be a future date. Format YYYY-MM-DD", "example": "2030-06-01" }, "country_of_issuance": { "type": "string", "description": "Country that issued the passport (ISO 3166-1 alpha-3)", "example": "IND" } }, "required": [ "number", "expiry_date", "country_of_issuance" ] } }, "required": [ "entity_type", "date_of_birth", "gender", "passport" ] } ] }, "CreateBusinessMerchantRequest": { "x-internal": true, "allOf": [ { "$ref": "#/components/schemas/CreateMerchantRequestBase" }, { "type": "object", "properties": { "entity_type": { "type": "string", "description": "Type of entity", "enum": [ "business" ], "example": "business" }, "registration_date": { "type": "string", "format": "date", "description": "Business registration/incorporation date. Must be a past date. Format YYYY-MM-DD", "example": "2020-06-01" }, "dba_name": { "type": "string", "description": "Trading (doing-business-as) name, if it differs from the registered name", "example": "Acme Retail" }, "business_type": { "type": "string", "description": "Legal type of the registered entity", "enum": [ "corporation", "foreign_entity", "foundation", "government_entity", "huf", "llp", "non_profit_organization", "one_person_company", "partnership", "private_limited", "public_limited", "society", "sole_proprietorship", "trust", "unincorporated_association" ], "example": "private_limited" }, "registration_document_id": { "type": "string", "description": "ID of a document you previously uploaded via [Create a document](/api-reference/openapi/document/createdocument), used as the merchant's certificate of incorporation", "example": "doc_nYUqLpuYQ0M8" }, "website": { "type": "string", "description": "Public website of the merchant", "example": "https://acme.example.com" }, "annual_turnover": { "type": "string", "description": "Annual business turnover band, in USD", "enum": [ "below_100k", "100k_to_1m", "1m_to_5m", "above_5m" ], "example": "1m_to_5m" }, "ubos": { "type": "array", "description": "Ultimate beneficial owners of the merchant. `ownership_percentage` across all entries must not sum above 100.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the individual, or legal name of the company", "example": "Jane Doe" }, "type": { "type": "string", "description": "Whether this owner is a natural person or a legal entity", "enum": [ "individual", "company" ], "example": "individual" }, "ownership_percentage": { "type": "number", "description": "Share of the merchant held by this owner. Greater than 0 and at most 100.", "exclusiveMinimum": 0, "maximum": 100, "example": 60 }, "country": { "type": "string", "description": "Nationality of the individual, or country of incorporation of the company (ISO 3166-1 alpha-3)", "example": "IND" } }, "required": [ "name", "type", "ownership_percentage", "country" ] }, "example": [ { "name": "Jane Doe", "type": "individual", "ownership_percentage": 60, "country": "IND" }, { "name": "Doe Holdings Pte Ltd", "type": "company", "ownership_percentage": 40, "country": "SGP" } ] }, "settlement_account": { "type": "object", "description": "Bank account the merchant's funds are settled to", "properties": { "account_holder_name": { "type": "string", "description": "Name on the bank account", "example": "Acme Trading Private Limited" }, "account_number": { "type": "string", "description": "Bank account number, or IBAN where the bank uses one", "example": "123456789" }, "bank_name": { "type": "string", "description": "Name of the bank that holds the account", "example": "JPMorgan Chase Bank" }, "swift_code": { "type": "string", "description": "SWIFT/BIC code of the bank", "example": "CHASUS33" }, "currency": { "type": "string", "format": "iso-4217", "description": "Currency of the account, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format", "enum": [ "USD", "EUR", "GBP", "AED", "SGD", "AUD", "INR" ], "example": "USD" }, "bank_address": { "type": "object", "description": "Address of the bank branch that holds the account", "properties": { "address_line1": { "type": "string", "description": "Primary address line", "example": "270 Park Avenue" }, "address_line2": { "type": "string", "description": "Secondary address line" }, "city": { "type": "string", "description": "City name", "example": "New York" }, "administrative_area": { "type": "string", "description": "State, province or region", "example": "NY" }, "postal_code": { "type": "string", "description": "Postal/ZIP code", "example": "10017" }, "country_code": { "type": "string", "description": "Country of the bank branch (ISO 3166-1 alpha-3)", "example": "USA" } }, "required": [ "address_line1", "city", "administrative_area", "country_code" ] } }, "required": [ "account_holder_name", "account_number", "bank_name", "swift_code", "currency", "bank_address" ] } }, "required": [ "entity_type", "registration_date", "dba_name", "business_type", "registration_document_id", "website", "annual_turnover", "ubos" ] } ] }, "CreateMerchantRequest": { "x-internal": true, "oneOf": [ { "$ref": "#/components/schemas/CreateIndividualMerchantRequest", "x-title": "individual" }, { "$ref": "#/components/schemas/CreateBusinessMerchantRequest", "x-title": "business" } ], "discriminator": { "propertyName": "entity_type", "mapping": { "individual": "#/components/schemas/CreateIndividualMerchantRequest", "business": "#/components/schemas/CreateBusinessMerchantRequest" } } }, "Merchant": { "type": "object", "x-tags": [ "platform" ], "properties": { "owner_merchant_id": { "type": "string", "description": "The ID of the platform/owner merchant", "example": "merch_68511919RVuf6" }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merch_68c777fcOOMpl" }, "status": { "type": "string", "enum": [ "created", "action_required", "pending", "success", "failed", "offboarded" ], "description": "Current onboarding status of the merchant.\n\n- `created` — the merchant has been submitted and screening has not finished.\n- `action_required` — screening flagged the merchant and Glomo is reviewing it before onboarding\n can continue.\n- `pending` — screening passed and the merchant's KYC or KYB review is in progress.\n- `success` — the merchant is onboarded and can transact.\n- `failed` — onboarding was rejected. Terminal.\n- `offboarded` — a previously onboarded merchant has been removed. Its API keys stop working and it\n can no longer transact. Terminal.\n", "example": "success" }, "name": { "type": "string", "description": "Name of the merchant", "example": "John Doe" }, "category": { "type": "string", "description": "Business category", "example": "Agricultural Services" }, "entity_type": { "type": "string", "enum": [ "individual", "business" ], "description": "Type of merchant entity", "example": "individual" }, "sub_category": { "type": "string", "description": "Business sub-category (must be paired with correct category)", "example": "Veterinary Services" }, "gender": { "type": "string", "enum": [ "male", "female", "undefined" ], "description": "Gender (only required for individual entity_type)", "example": "male" }, "date_of_birth": { "type": "string", "format": "date", "description": "Date of birth, as a calendar date in `YYYY-MM-DD` format with no time or time zone. Present only when `entity_type` is `individual`.\n", "example": "2001-08-04" }, "registration_number": { "type": "string", "description": "Business registration number or individual ID", "example": "REG123456" }, "registration_country": { "type": "string", "description": "Country where the merchant is registered (ISO 3166-1 alpha-3)", "example": "IND" }, "address": { "type": "object", "description": "Merchant address", "properties": { "address_line1": { "type": "string", "description": "Primary address line", "example": "123 Main St" }, "address_line2": { "type": "string", "description": "Secondary address line (optional)", "example": "" }, "city": { "type": "string", "description": "City name", "example": "Bangalore" }, "state": { "type": "string", "description": "State or province", "example": "Karnataka" }, "pincode": { "type": "string", "description": "Postal/ZIP code", "example": "560060" }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)", "example": "IND" } }, "required": [ "address_line1", "city", "state", "pincode", "country" ] }, "operation_countries": { "type": "array", "description": "List of countries where the merchant operates", "items": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "example": [ "IND" ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the merchant was created, as an ISO 8601 date-time in UTC.\n", "example": "2025-10-07T06:11:47Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the merchant was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2025-10-07T06:11:47Z" }, "jwt_token": { "type": "string", "description": "JWT token for the merchant", "example": "child_merchant_JWT" }, "public_key": { "type": "string", "description": "public key for the merchant", "example": "live_6889e287VfqrPVPg" } }, "required": [ "owner_merchant_id", "merchant_id", "status", "name", "registration_number", "registration_country", "address", "operation_countries", "created_at", "updated_at", "jwt_token" ] }, "MerchantCreateResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message", "example": "Merchant created successfully!" }, "data": { "$ref": "#/components/schemas/Merchant" } } }, "MerchantKybReviewResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "Review-pending message. The merchant is created in `created` status and stays there until the KYB review completes.", "example": "Merchant created and submitted for review. You will be notified once it is approved." }, "data": { "type": "object", "properties": { "owner_merchant_id": { "type": "string", "description": "The ID of the platform/owner merchant", "example": "merch_68511919RVuf6" }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merch_68c777fcOOMpl" }, "status": { "type": "string", "description": "Status of the merchant onboarding. `created` while the KYB review is pending.", "enum": [ "created" ], "example": "created" }, "name": { "type": "string", "description": "Name of the merchant", "example": "John Doe" }, "category": { "type": "string", "description": "Business category", "example": "Agricultural Services" }, "entity_type": { "type": "string", "enum": [ "individual", "business" ], "description": "Type of merchant entity", "example": "individual" }, "sub_category": { "type": "string", "description": "Business sub-category (must be paired with correct category)", "example": "Veterinary Services" }, "gender": { "type": "string", "enum": [ "male", "female", "undefined" ], "description": "Gender (only required for individual entity_type)", "example": "male" }, "date_of_birth": { "type": "string", "format": "date", "description": "Date of birth, as a calendar date in `YYYY-MM-DD` format with no time or time zone. Present only when `entity_type` is `individual`.\n", "example": "2001-08-04" }, "registration_number": { "type": "string", "description": "Business registration number or individual ID", "example": "REG123456" }, "registration_country": { "type": "string", "description": "Country where the merchant is registered (ISO 3166-1 alpha-3)", "example": "IND" }, "address": { "type": "object", "description": "Merchant address", "properties": { "address_line1": { "type": "string", "description": "Primary address line", "example": "123 Main St" }, "address_line2": { "type": "string", "description": "Secondary address line (optional)", "example": "" }, "city": { "type": "string", "description": "City name", "example": "Bangalore" }, "state": { "type": "string", "description": "State or province", "example": "Karnataka" }, "pincode": { "type": "string", "description": "Postal/ZIP code", "example": "560060" }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)", "example": "IND" } }, "required": [ "address_line1", "city", "state", "pincode", "country" ] }, "operation_countries": { "type": "array", "description": "List of countries where the merchant operates", "items": { "type": "string", "description": "Country code (ISO 3166-1 alpha-3)" }, "example": [ "IND" ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the merchant was created, as an ISO 8601 date-time in UTC.\n", "example": "2025-10-07T06:11:47Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the merchant was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2025-10-07T06:11:47Z" } }, "required": [ "owner_merchant_id", "merchant_id", "status", "name", "registration_number", "registration_country", "address", "operation_countries", "created_at", "updated_at" ] } } }, "UpdateMerchantRequest": { "x-internal": true, "description": "Fields to update on an existing merchant. Currently supports `passport` for\nindividual merchants and `registration_date` for business merchants; more\nfields may be supported in future. The applicable field is determined by the\nmerchant's entity type, set at onboarding, rather than by the request body. A\nfield that does not apply to the merchant's entity type is ignored.\n", "oneOf": [ { "x-title": "individual", "type": "object", "properties": { "passport": { "type": "object", "description": "Passport identification (individual merchants)", "properties": { "number": { "type": "string", "description": "Passport number", "example": "P1234567" }, "expiry_date": { "type": "string", "format": "date", "description": "Passport expiry date. Must be a future date. Format YYYY-MM-DD", "example": "2030-06-01" }, "country_of_issuance": { "type": "string", "description": "Country that issued the passport (ISO 3166-1 alpha-3)", "example": "IND" } }, "required": [ "number", "expiry_date", "country_of_issuance" ] } }, "required": [ "passport" ] }, { "x-title": "business", "type": "object", "properties": { "registration_date": { "type": "string", "format": "date", "description": "Business registration/incorporation date. Must be a past date. Format YYYY-MM-DD", "example": "2020-06-01" } }, "required": [ "registration_date" ] } ] }, "CreateInternalTransferRequest": { "type": "object", "required": [ "amount", "currency", "reference", "from_merchant_id", "to_merchant_id" ], "properties": { "amount": { "type": "integer", "minimum": 1, "description": "The amount to transfer, in the smallest unit of `currency` (cents for USD). `10000` is $100.00 when `currency` is USD. A positive integer, sent as a JSON number.\n", "example": 10000 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency in which the transfer is made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format, case-insensitive.\n", "example": "AED" }, "reference": { "type": "string", "maxLength": 100, "description": "A reference identifier for the transfer. Maximum length is 100 characters.\n", "example": "sample-reference" }, "from_merchant_id": { "type": "string", "description": "The unique identifier of the merchant account from which funds will be transferred.\n", "example": "merch_68cc1216xPrdU" }, "to_merchant_id": { "type": "string", "description": "The unique identifier of the merchant account to which funds will be transferred. Must be different from `from_merchant_id`.\n", "example": "merch_68cc0571y5S4h" } } }, "InternalTransfer": { "type": "object", "x-tags": [ "internal_transfer" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the internal transfer.\n", "example": "inttransfer_68f1f9126GDCB" }, "from_merchant_id": { "type": "string", "description": "The unique identifier of the merchant account from which funds were transferred.\n", "example": "merch_68cc1216xPrdU" }, "to_merchant_id": { "type": "string", "description": "The unique identifier of the merchant account to which funds were transferred.\n", "example": "merch_68cc0571y5S4h" }, "owner_merchant_id": { "type": "string", "description": "The unique identifier of the merchant account that owns/initiated this transfer.\n", "example": "merch_68cc0571y5S4h" }, "transfer_amount": { "type": "integer", "description": "The amount transferred, in the smallest unit of `transfer_currency` (cents for USD). `1000` is $10.00 when `transfer_currency` is USD.\n", "example": 1000 }, "transfer_currency": { "type": "string", "format": "iso-4217", "description": "The currency in which the transfer was made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.\n", "example": "AED" }, "reference": { "type": "string", "description": "The reference identifier provided for the transfer.\n", "example": "123" }, "fees": { "type": "object", "description": "The fees associated with the internal transfer.\n", "properties": { "txn_fee": { "$ref": "#/components/schemas/Money", "description": "The transaction fee charged for the internal transfer.\n" }, "fx_fee": { "$ref": "#/components/schemas/Money", "description": "The foreign exchange fee charged for the internal transfer.\n" } }, "example": { "txn_fee": { "currency": "AED", "amount": 0 }, "fx_fee": { "currency": "AED", "amount": 0 } } }, "error_code": { "type": [ "string", "null" ], "readOnly": true, "description": "The error code if the internal transfer failed, null otherwise.\n", "example": null }, "error_description": { "type": [ "string", "null" ], "readOnly": true, "description": "The error description if the internal transfer failed, null otherwise.\n", "example": null }, "created_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the internal transfer was created, as an ISO 8601 date-time in UTC.\n", "example": "2025-10-17T08:06:42Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "When the internal transfer was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2025-10-17T08:06:42Z" } } }, "KycDocument": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the KYC document record.\n", "example": "kycdoc_69b3f97ef0bmk" }, "document_id": { "type": [ "string", "null" ], "readOnly": true, "description": "The identifier of the uploaded document file. This is populated once the customer has uploaded the document (i.e. when `status` is `captured`). Use this value with `GET /api/v1/document/{document_id}` to retrieve the full document details including the preview URL.\n", "example": "doc_69b3f9b4MJgKZ" }, "type": { "type": "string", "readOnly": true, "description": "The type of KYC document.\n", "example": "pan_card", "enum": [ "pan_card", "aadhaar", "photograph", "passport", "driving_license", "selfie_proof", "signature", "contribution_agreement", "photo_on_aadhaar", "applicant_esign", "bank_statement", "vkyc", "digilocker_zip", "other" ] }, "status": { "type": "string", "readOnly": true, "description": "The capture status of this KYC document.\n", "example": "captured", "enum": [ "not_captured", "captured" ] }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the KYC document record was created, as an ISO 8601 date-time in UTC.\n", "example": "2026-03-13T11:48:14.458Z" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "When the document file was uploaded, as an ISO 8601 date-time in UTC. `null` if the document has not yet been captured.\n", "example": "2026-03-13T11:49:08.093Z" } } }, "KycLinkDetail": { "type": "object", "x-tags": [ "KycLink" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the KYC link.\n", "example": "kyc_69b3f97eSThQY" }, "status": { "type": "string", "readOnly": true, "enum": [ "initiated", "in_progress", "submitted", "action_required", "under_review", "completed", "failed", "expired", "rejected" ], "description": "The current status of the KYC link.\n\n- `initiated` — the link has been created and the customer has not started.\n- `in_progress` — the customer has started the verification.\n- `submitted` — the customer has finished and the verification result is pending.\n- `action_required` — more information is needed from the customer.\n- `under_review` — the information provided is being reviewed.\n- `completed` — the customer has been verified. Terminal.\n- `failed` — the verification could not be completed. Terminal.\n- `expired` — the link expired before the customer finished. Terminal.\n- `rejected` — the verification was rejected on review. Terminal.\n", "example": "completed" }, "link_url": { "type": "string", "readOnly": true, "description": "The URL to share with the customer to complete the KYC verification.\n", "example": "https://app.glomopay.com/kyc-links/kyc_69b3f97eSThQY" }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the KYC link expires, as an ISO 8601 date-time in UTC.\n", "example": "2026-06-11T11:48:14.361Z" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the KYC link was created, as an ISO 8601 date-time in UTC.\n", "example": "2026-03-13T11:48:14.363Z" }, "customer_id": { "type": [ "string", "null" ], "readOnly": true, "description": "The unique identifier of the customer associated with this KYC link. `null` if the KYC link was created with an email address only (no existing customer).\n", "example": "cust_abc123XYZ" }, "tracker": { "type": "array", "readOnly": true, "description": "A chronological list of status events for the KYC verification process.\n", "items": { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the tracker event happened, as an ISO 8601 date-time in UTC.\n", "example": "2026-03-13T12:00:00.000Z" }, "text": { "type": "string", "description": "Human-readable description of the tracker event.\n", "example": "KYC verification completed" } } } }, "documents": { "type": "array", "readOnly": true, "description": "The list of KYC documents associated with this KYC link. Each document has a `document_id` field that can be used with `GET /api/v1/document/{document_id}` to retrieve full document details (e.g. preview URL, file name) once the document has been captured.\n", "items": { "$ref": "#/components/schemas/KycDocument" } } } }, "PaymentSessionSnapshot": { "type": "object", "description": "The state of a payment session and the records it has produced so far. The same body is returned by [Retrieve a payment session](/api-reference/openapi/payment_session/getpaymentsession), by each item of [List payment sessions](/api-reference/openapi/payment_session/listpaymentsessions), and as `data` in the [payment_session webhook](/platform/webhooks/payment-session).\n", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment session, prefixed with `psess_`.", "example": "psess_6819d8046mpKt" }, "session_type": { "type": "string", "enum": [ "kyc_lrs", "kyc_lrs_folio", "kyc_nri_individual_verification", "kyc_nri_joint_verification", "kyc_inbound_folio" ], "description": "The workflow type of the session. See `session_type` on [Create a payment session](/api-reference/openapi/payment_session/createpaymentsession).\n", "example": "kyc_lrs_folio" }, "status": { "type": "string", "enum": [ "created", "kyc_in_progress", "kyc_done", "payment_pending", "remittance_claimed", "paid", "completed", "failed", "expired" ], "description": "Where the investor is in the session. This is a finer status than the `active` returned when the\nsession is created.\n\n- `created` — the session exists; the investor has not started KYC.\n- `kyc_in_progress` — the investor is going through KYC.\n- `kyc_done` — KYC is complete; no money has moved yet.\n- `payment_pending` — a payment has started but has not succeeded.\n- `remittance_claimed` — the investor's bank is not supported for LRS on Glomo, so they paid the\n fund directly and gave the transfer reference (UTR). It is the investor's claim until units are\n allotted.\n- `paid` — a payment on the session's order succeeded.\n- `completed` — the investor finished every step. Final.\n- `failed` — the session ended without finishing. `failure` says why. Final.\n- `expired` — the session passed `expires_at` before any money moved. Final.\n\nOnce money has moved (`payment_pending`, `remittance_claimed` or `paid`), the session keeps that\nstatus after `expires_at`, because units can still be allotted.\n", "example": "paid" }, "failure": { "type": [ "object", "null" ], "description": "Why the session failed. `null` unless `status` is `failed`.", "properties": { "code": { "type": [ "string", "null" ], "enum": [ "kyc_failed", "kyc_expired", "kyc_rejected", "bank_not_supported", "payment_failed", "sanction_hit", "ineligible_country", "prospect_folio_creation_failed", "inbound_checkout_failed", "shareable_link_unavailable", null ], "description": "Machine-readable reason.", "example": "kyc_rejected" }, "message": { "type": [ "string", "null" ], "description": "Human-readable reason, safe to show to the investor.", "example": "KYC verification was rejected" } } }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the session was created.", "example": "2026-11-03T05:12:40Z" }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the session expires if no money has moved.", "example": "2026-11-10T05:12:40Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of the last change to the session record.", "example": "2026-11-03T06:02:11Z" }, "customer_id": { "type": [ "string", "null" ], "description": "The customer (`cust_` prefix) the investor's KYC belongs to. `null` until KYC starts.", "example": "cust_6819d7d0lrLvP" }, "scheme": { "type": [ "object", "null" ], "description": "The AMC scheme the session is for. `null` for session types without a scheme. Before the investor chooses, this is the scheme of the prefilled plan.\n", "properties": { "scheme_code": { "type": "string", "example": "SCH001" }, "name": { "type": "string", "example": "Example Global Equity Fund - Regular Plan" }, "plan": { "type": "string", "enum": [ "regular", "direct" ], "example": "regular" }, "distributor_arn": { "type": [ "string", "null" ], "description": "The distributor ARN on the session, from the request or the fund relationship.", "example": "ARN12345" } } }, "amount": { "type": [ "object", "null" ], "description": "The investment amount: the investor's confirmed amount, or the prefilled amount until they confirm. `null` when neither is set.\n", "properties": { "value": { "type": "integer", "description": "Amount in the smallest currency unit (cents), so `500000` is $5,000.00.", "example": 500000 }, "currency": { "type": "string", "enum": [ "USD" ], "example": "USD" } } }, "expected_entities": { "type": "array", "items": { "type": "string", "enum": [ "kyc", "folio", "order", "payments", "folio_transaction" ] }, "description": "The keys of `entities` this session will produce, from its `session_type`. A key listed here and\nstill `null` (or an empty array) means \"not created yet\"; a key not listed will never appear,\nexcept `refunds`.\n\n- `kyc_lrs` — `kyc`, `order`, `payments`\n- `kyc_lrs_folio`, `kyc_inbound_folio` — `kyc`, `folio`, `order`, `payments`, `folio_transaction`\n- `kyc_nri_individual_verification` — `kyc`\n- `kyc_nri_joint_verification` — `kyc`, `folio`\n\nFor `kyc_lrs_folio`, once KYC completes with a bank that is not supported for LRS on Glomo, the list\nbecomes `kyc`, `folio`, `folio_transaction`: the investor pays the fund directly, so no order or\npayment is created.\n", "example": [ "kyc", "folio", "order", "payments", "folio_transaction" ] }, "entities": { "type": "object", "description": "The records the session has produced. Every key in `expected_entities` is present: `null` (or `[]` for `payments`) until its record exists. `refunds` is added only when a refund exists.\n", "properties": { "kyc": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "KYC journey ID, prefixed with `kyc_`.", "example": "kyc_6819d8046mpKt" }, "status": { "type": "string", "enum": [ "in_progress", "under_review", "action_required", "completed", "failed", "expired" ], "example": "completed" }, "failure_reason": { "type": [ "string", "null" ], "description": "Why KYC failed or was rejected. `null` otherwise.", "example": null }, "bank_enabled": { "type": "boolean", "description": "Whether the investor's bank is supported for LRS remittance on Glomo.", "example": true }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-11-03T05:40:02Z" } } }, "folio": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "amcfolio_6819e1a2kQwRt" }, "folio_number": { "type": [ "string", "null" ], "description": "The folio number the RTA allotted. `null` until allotted.", "example": "91234567/89" }, "status": { "type": "string", "enum": [ "pending", "active", "failed" ], "example": "active" } } }, "order": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "order_678a4c88hpAjf" }, "status": { "type": "string", "enum": [ "active", "paid", "failed", "action_required", "cancelled", "partially_paid", "under_review", "expired" ], "example": "paid" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-11-04T05:45:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-11-03T06:01:58Z" } } }, "payments": { "type": "array", "description": "Payments on the order, newest first.", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "payt_6819e5b1nTzXc" }, "status": { "type": "string", "enum": [ "in_progress", "under_review", "success", "failed", "action_required" ], "example": "success" }, "amount": { "type": "integer", "description": "Amount in the smallest currency unit.", "example": 500000 }, "currency": { "type": "string", "example": "USD" }, "method": { "type": [ "string", "null" ], "description": "The payment method type, such as `pay_via_bank` or `bank_transfer`.", "example": "pay_via_bank" }, "payer": { "type": [ "object", "null" ], "description": "Who paid. `null` until the payment method is known.", "properties": { "name": { "type": [ "string", "null" ], "example": "Asha Verma" }, "country": { "type": [ "string", "null" ], "example": "IND" }, "bank_name": { "type": [ "string", "null" ], "description": "The remitter's bank. `null` for card payments.", "example": "HDFC bank" }, "account_number": { "type": [ "string", "null" ], "description": "The remitter's account number, masked to its last four digits. A number of four digits or fewer is masked whole (`••••`). `null` for methods without an account number.\n", "example": "••••1234" } } }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-11-03T06:01:55Z" }, "error_code": { "type": [ "string", "null" ], "example": null }, "error_message": { "type": [ "string", "null" ], "example": null }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-11-03T06:01:58Z" } } } }, "folio_transaction": { "type": [ "object", "null" ], "description": "The RTA purchase for the session. A zero-amount prospect folio request is not shown here.", "properties": { "id": { "type": "string", "example": "amcftxn_6819f0c3pLmNb" }, "type": { "type": "string", "enum": [ "fresh_purchase", "additional_purchase" ], "example": "fresh_purchase" }, "status": { "type": "string", "enum": [ "pending", "folio_allotted", "units_allotted", "failed" ], "example": "pending" }, "payment_id": { "type": [ "string", "null" ], "example": "payt_6819e5b1nTzXc" }, "units": { "type": [ "string", "null" ], "description": "Units allotted, as a decimal string. `null` until units are allotted.", "example": null }, "nav": { "type": [ "string", "null" ], "description": "NAV the units were allotted at, as a decimal string.", "example": null }, "nav_date": { "type": [ "string", "null" ], "format": "date", "example": null }, "error_code": { "type": [ "string", "null" ], "example": null }, "error_message": { "type": [ "string", "null" ], "example": null } } }, "refunds": { "type": "array", "description": "Refunds on the session's payments, newest first. Present only when a refund exists.", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "refund_681a02d4hGfDs" }, "payment_id": { "type": "string", "example": "payt_6819e5b1nTzXc" }, "status": { "type": "string", "enum": [ "in_progress", "success", "failed", "action_required", "cancelled", "under_review" ], "example": "success" }, "amount": { "type": "integer", "example": 500000 }, "currency": { "type": "string", "example": "USD" }, "partial_refund": { "type": "boolean", "example": false }, "error_code": { "type": [ "string", "null" ], "example": null }, "error_message": { "type": [ "string", "null" ], "example": null }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-11-04T09:15:30Z" } } } } } } } }, "PaymentSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment session, prefixed with `psess_`.", "example": "psess_6819d8046mpKt" }, "status": { "type": "string", "enum": [ "active", "completed", "failed", "expired" ], "description": "Current status of the payment session.\n\n- `active` — the customer can go through the session.\n- `completed` — the customer finished every step. Terminal.\n- `failed` — the session ended without finishing. Terminal.\n- `expired` — the session passed `expires_at` before it finished. Terminal.\n", "example": "active" }, "session_type": { "type": "string", "enum": [ "kyc_lrs", "kyc_lrs_folio", "kyc_nri_individual_verification", "kyc_nri_joint_verification", "kyc_inbound_folio" ], "description": "The workflow type configured for this session, which determines the pre-steps and/or\npost-steps in the payment journey. The value is configured per business by Glomo; you do not\nchoose it per request.\n\n- `kyc_lrs` — KYC, then an LRS remittance checkout.\n- `kyc_lrs_folio` — mutual fund investment from India under LRS: folio and scheme selection, KYC,\n then an LRS remittance checkout.\n- `kyc_nri_individual_verification` — onboarding of an individual NRI investor, ending when KYC\n (including video KYC) completes.\n- `kyc_nri_joint_verification` — NRI investor verification that collects folio and scheme selection\n before KYC.\n- `kyc_inbound_folio` — mutual fund investment by an NRI investor: folio and scheme selection, NRI\n KYC, folio creation, then an inbound checkout.\n", "example": "kyc_lrs" }, "token": { "type": "string", "description": "Short-lived JWT token. Pass it, together with the session `id`, to the [Unified SDK (Web)](/platform/sdk/unified-sdk) as `paymentSessionToken` to launch the session UI for the customer.\n", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the session expires.", "example": "2026-05-07T10:30:00Z" } } }, "RfiListItem": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the RFI.\n", "example": "rfi_6a7c5018ZGuKP" }, "business_id": { "type": "string", "readOnly": true, "description": "The unique identifier of the business the RFI belongs to.\n", "example": "merch_685bb99eFhPGA" }, "entity_type": { "type": "string", "readOnly": true, "description": "The type of the underlying resource the RFI was raised against, for example `Payment`, `Payin`, `Payout`, `Refund`, `Order`, `Subscription` or `Chargeback`.\n", "example": "Payment" }, "entity_id": { "type": "string", "readOnly": true, "description": "The unique identifier of the underlying resource the RFI was raised against.\n", "example": "payt_6a7c50089mMiB" }, "status": { "type": "string", "readOnly": true, "enum": [ "action_required", "under_review", "approved", "rejected", "superseded", "expired", "cancelled" ], "description": "The current status of the RFI. `action_required` means documents are still owed — respond using [Respond to an RFI](/api-reference/openapi/rfi/respondrfi). `under_review` means documents have been submitted and are pending a decision; Glomo can ask for more, which moves the RFI back to `action_required`. The final decision (`approved` or `rejected`) is communicated via the [`rfi` webhook](/platform/webhooks/rfi). `superseded` means the RFI was closed without a decision and needs no further response. `expired` means the response deadline passed before documents were submitted. `cancelled` means Glomo withdrew the request while documents were still owed; no response is needed. `approved`, `rejected`, `superseded`, `expired` and `cancelled` are terminal.\n", "example": "approved" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the RFI was created, as an ISO 8601 date-time in UTC.\n", "example": "2026-08-12T10:51:04.747Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "When the RFI was last updated, as an ISO 8601 date-time in UTC.\n", "example": "2026-08-13T06:42:00.878Z" } } }, "RfiDetail": { "allOf": [ { "$ref": "#/components/schemas/RfiListItem" }, { "type": "object", "properties": { "documents_required": { "type": "array", "readOnly": true, "description": "The documents needed to resolve this RFI. Submit documents against a specific requirement using its `rfi_doc_id` via the [Respond to an RFI](/api-reference/openapi/rfi/respondrfi) endpoint. Empty when the RFI does not require documents.\n", "items": { "type": "object", "properties": { "rfi_doc_id": { "type": "string", "readOnly": true, "description": "The unique identifier for this document requirement.\n", "example": "rfidoc_6a72a39b38jDD" }, "description": { "type": "string", "readOnly": true, "description": "A human-readable description of what document is needed.\n", "example": "Last 3 months bank statement" }, "multiple_allowed": { "type": "boolean", "readOnly": true, "description": "Whether more than one document can be submitted for this requirement.\n", "example": true }, "max_count": { "type": "integer", "readOnly": true, "description": "The maximum number of documents that can be submitted for this requirement.\n", "example": 3 } } } }, "fields_required": { "type": "array", "readOnly": true, "description": "The structured values needed to resolve this RFI, alongside any documents. Submit them as the `fields` object via the [Respond to an RFI](/api-reference/openapi/rfi/respondrfi) endpoint, keyed by `name`. Empty when the RFI does not ask for any values.\n", "items": { "type": "object", "properties": { "name": { "type": "string", "readOnly": true, "description": "The key to send this value under in the `fields` object.\n", "example": "invoice_number" }, "type": { "type": "string", "readOnly": true, "enum": [ "string", "integer", "date", "enum", "address" ], "description": "The expected type. `integer` values are in minor units, `date` values are strings in the format given by `format`, and `address` values are objects matching `schema`.\n", "example": "string" }, "required": { "type": "boolean", "readOnly": true, "description": "Whether the value must be supplied.\n", "example": true }, "format": { "type": "string", "readOnly": true, "description": "Present on `date` fields. The format the value must be sent in.\n", "example": "YYYY-MM-DD" }, "allowed_values": { "type": "array", "readOnly": true, "description": "Present on `enum` fields. The values this field accepts.\n", "items": { "type": "object", "properties": { "key": { "type": "string", "example": "services" }, "label": { "type": "string", "example": "Services" } } } }, "schema": { "type": "array", "readOnly": true, "description": "Present on `address` fields. The keys the address object must contain.\n", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "address_line1" }, "type": { "type": "string", "example": "string" }, "required": { "type": "boolean", "example": true } } } } } } }, "instructions": { "type": "string", "readOnly": true, "description": "Human-readable guidance on what is required to resolve the RFI. Falls back to a generic message when no specific instructions were set.\n", "example": "Upload your latest bank statement" }, "review_comments": { "type": [ "string", "null" ], "readOnly": true, "description": "Comments left by the reviewer, for example why a previous submission was rejected. `null` when there are none.\n", "example": "Please re-upload a clearer copy." }, "uploader_comments": { "type": [ "string", "null" ], "readOnly": true, "description": "The note recorded against the RFI when documents were last submitted. `null` when there are none.\n", "example": "Uploaded the statement." } } } ] }, "Rfi": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the RFI.\n", "example": "rfi_6a72a39b38jDD" }, "status": { "type": "string", "readOnly": true, "enum": [ "information_required", "submitted", "approved", "rejected", "superseded", "expired", "cancelled" ], "description": "The current status of the RFI. A successful response transitions the RFI from\n`information_required` to `submitted`. The final decision (`approved` or `rejected`) is\ncommunicated via the [`rfi` webhook](/platform/webhooks/rfi).\n\nThis response uses different names for two statuses than the RFI list and detail endpoints:\n`information_required` here is `action_required` there, and `submitted` here is `under_review`\nthere.\n\n- `information_required` — documents are still owed.\n- `submitted` — documents have been submitted and are awaiting a decision. Glomo can ask for more,\n which moves the RFI back to `information_required`.\n- `approved` — the RFI was accepted. Terminal.\n- `rejected` — the RFI was declined. Terminal.\n- `superseded` — the RFI was closed without a decision and needs no further response. Terminal.\n- `expired` — the response deadline passed before documents were submitted. Terminal.\n- `cancelled` — Glomo withdrew the request while documents were still owed; no response is needed.\n Terminal.\n", "example": "submitted" } } } }, "parameters": { "BeforeParam": { "in": "query", "name": "before", "schema": { "type": "string" }, "description": "Return only resources created at or before this time. Send an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp with an offset, such as `2025-02-18T12:03:44Z` or `2025-02-18T17:33:44+05:30`. A timestamp without an offset is read as UTC. A bare date (`YYYY-MM-DD`) means the end of that day in UTC (`23:59:59.999999Z`). An invalid value returns `400 Bad Request`. Use this to avoid page drift. See [Pagination parameters](/platform/pagination#parameters) for more details.\n", "example": "2025-02-18T12:03:44Z" }, "AfterParam": { "in": "query", "name": "after", "schema": { "type": "string" }, "description": "Return only resources created at or after this time. Send an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp with an offset, such as `2025-01-18T12:03:44Z` or `2025-01-18T17:33:44+05:30`. A timestamp without an offset is read as UTC. A bare date (`YYYY-MM-DD`) means the start of that day in UTC (`00:00:00Z`). An invalid value returns `400 Bad Request`. Use this to avoid page drift. See [Pagination parameters](/platform/pagination#parameters) for more details.\n", "example": "2025-01-18T12:03:44Z" }, "PerPageParam": { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 20 }, "description": "Number of resources per page. Should be between 1 and 100." }, "PageParam": { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "Page number for pagination. Starts from 1. Get the next page number from the `next` field in the response." } } } }