{ "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.glomopay.com/openapi.yaml](https://docs.glomopay.com/openapi.yaml)\n- [https://docs.glomopay.com/openapi.json](https://docs.glomopay.com/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": "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.", "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" ] }, { "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 and GBP.\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 and GBP.\n", "example": "USD" }, "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 and GBP.\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 and GBP.\n", "example": "USD" }, "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 } ] } } } }, "responses": { "201": { "description": "Refund 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 and GBP.\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 and GBP.\n", "example": "USD" }, { "$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. FX fees are charged on top of this rate.\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", "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", "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, case-insensitive", "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" }, "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" } } } } } }, "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 the beneficiary.", "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", "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": "**Applicable only to the LRS (Liberalised Remittance Scheme / resident-India remittance) flow.** Filter customers by PAN (tax identification 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", "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", "operationId": "updateCustomer", "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": { "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" } } } } } }, "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", "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": [] } ] } }, "/document": { "post": { "tags": [ "Document" ], "summary": "Create a new document", "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": "ID of the document to retrieve", "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": "Invalid document id" } } } } } }, "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 with given id does not exist" } } } } } } }, "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\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" } } } } } } }, "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", "paid", "failed", "action_required", "under_review", "expired" ] }, "description": "Status of order to filter" }, { "in": "query", "name": "request_id", "schema": { "type": "string" }, "description": "Filter orders by the merchant-provided idempotency key.", "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", "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.\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", "paid", "failed", "action_required", "cancelled", "partially_paid", "under_review", "expired" ] }, "description": "Status of payment link to filter" }, { "$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 payin", "example": "payin_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", "operationId": "updatePayin", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the payment link to update.", "schema": { "type": "string", "example": "e092be15-e614-4401-8cea-7ca3df7da987" } } ], "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": "timestamp", "description": "The new expiry date for the payin. Expiry cannot be less than or equal to the current date and can be up to 6 months in the future.\n", "example": "2025-02-15T00:00:00.000Z" } }, "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", "example": "e092be15-e614-4401-8cea-7ca3df7da987" } ], "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": "payin_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", "example": "payin_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 and the balance in the source currency does not cover the amount plus fees, the payout is accepted with `status: queued` instead of being rejected. Glomo releases it automatically once the balance covers it. 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": "PYR002", "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": "PYR002", "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", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Conflict" }, "message": { "type": "string", "example": "A payout with this request_id already exists" } } } } } } }, "security": [ { "JWT": [] } ] }, "get": { "tags": [ "Payout" ], "summary": "List all payouts", "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", "operationId": "getPayoutById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the payout.", "example": "pout_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.", "schema": { "type": "string", "example": "pout_DdWp_HUbOnlg" } } ], "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": [] } ] } }, "/payouts/{id}/update_rfi": { "patch": { "tags": [ "Payout" ], "summary": "Update RFI for Payout", "operationId": "updateRfiPayout", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The unique identifier for the payout.", "example": "payout_E602dMzgjpDC" } } ], "security": [ { "JWT": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/AttachedDocument", "required": [ "rfi_doc_id", "id" ] } } }, "required": [ "documents" ] } } } }, "responses": { "200": { "description": "Document attached successfully", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/components/schemas/Payout" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } } } }, "/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", "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" ] } } } } } }, "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`, `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", "value": { "error": "Bad Request", "message": "payment_method.subtype is required" } }, "unsupported_payment_method": { "summary": "Unsupported payment method", "value": { "error": "Bad Request", "message": "'card' is not a supported payment method" } }, "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": [] } ] } }, "/payouts/mock": { "patch": { "tags": [ "Payout" ], "summary": "Mock update a payout status", "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", "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.", "example": "payin_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", "schema": { "type": "string", "format": "iso-4217, case-insensitive", "description": "The currency in which the payment is made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. For example, USD.\n" }, "example": "USD" }, { "in": "query", "name": "request_id", "schema": { "type": "string" }, "description": "Filter payments by the merchant-provided idempotency key.", "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. Creates a mock payment of specified amount for any given Payment link.\n", "operationId": "createMockPayment", "security": [ { "JWT": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 100, "description": "Amount in minor units (cents), minimum 100.\nReserved sandbox test amount: use exactly `6623` (in any currency) to force a sanctions-screening hit. The payment still succeeds, but its `compliance_status` is set to `action_required` and a payment-screening RFI is raised against it, with settlement held until the RFI is resolved. This works for any payment method and whether or not a customer is attached. See [Compliance Reviews & RFIs on Successful Payments](/request-for-information/compliance-reviews-and-rfis-on-successful-payments).\n", "example": 10000 }, "currency": { "type": "string", "format": "iso-4217", "description": "The currency code in ISO 4217 format", "example": "AED" }, "payment_method": { "type": "string", "description": "Required if no `payin_id` is passed.", "enum": [ "BankTransfer" ], "example": "BankTransfer" }, "payin_id": { "type": "string", "description": "The unique identifier for the payin. Required if no `payment_method` is passed.", "example": "payin_E602dMzgjpDC" }, "remitter_name": { "type": "string", "description": "Name of the remitter. Optional, defaults to `Non_Sanctioned_Entity`", "enum": [ "Sanctioned_Entity", "Non_Sanctioned_Entity" ], "example": "Non_Sanctioned_Entity" } }, "required": [ "amount", "currency" ] } } } }, "responses": { "201": { "description": "Payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "400": { "description": "Bad request" } } } }, "/payment/{id}": { "get": { "tags": [ "Payment" ], "summary": "Retrieve a payment\n", "operationId": "getPaymentById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the payment.", "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}/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, "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- **Gateway Error:** `Payment must be from LRS gateway`\n- **Settlement Error:** `Payment must not have direct settlement enabled`\n- **Transaction Error:** `No transaction found for payment`\n- **Funds Already Available:** `Transaction already has funds available`\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", "Fradulent", "Others" ], "description": "The reason for the refund.\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 cents. Required for partial refunds. If not provided, the full payment amount will be refunded. For example, 1000 cents is $10.00. The currency is determined by the payment's currency.\n", "example": 1000 }, "request_id": { "type": "string", "description": "Optional idempotency key.\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": "Filter refunds by the merchant-provided idempotency key.", "example": "unique_refund_request_id_123" }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "success", "failed", "action_required", "pending", "under_review" ] }, "description": "Refund status to filter" }, { "$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", "operationId": "getRefundById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the payout.", "example": "pout_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": "Mark an in_progress refund as successful\n", "operationId": "mockUpdateRefund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The ID of the refund", "example": "refund_E602dMzgjpDC" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "The new status of the refund. You can only mark a refund as `success`", "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", "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", "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", "operationId": "getPriceById", "security": [ { "JWT": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier for the payout.", "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", "active", "paused", "expired", "failed", "halted", "cancelled", "completed" ] }, "description": "Filter subscriptions by status.", "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": "2025-01-07", "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": "2025-01-07", "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": "2025-01-07", "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", "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", "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", "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", "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 to update next payment date", "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", "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", "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", "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/glomo-webhooks#virtual-account-webhooks) 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": "REG123456", "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" } ] } } } } } }, "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", "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", "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", "completed", "action_required", "under_review", "rejected" ] }, "description": "Filter KYC links by status.", "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.", "example": "https://app.glomopay.com/kyc-links/kyc_69b3f97eSThQY" }, "expires_at": { "type": "string", "format": "date-time", "description": "Timestamp when the link expires.", "example": "2026-06-11T11:48:14.361Z" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the link was created.", "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": { "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\nThe `token` returned in the response should be passed to the Glomo Web SDK to launch the guided UI for the customer.\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`) used to prefill the scheme plan and amount step. `amount`\n and `currency` must be supplied together.\n\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.\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.", "properties": { "plan": { "type": "string", "enum": [ "regular", "direct" ], "description": "AMC scheme plan.", "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`.\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.\n", "example": "ARN12345" } } } } } } }, "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" } } } } } } } }, "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, mutually exclusive fields provided, prefill fields supplied without an identifier, or KYC prefill supplied both at the top level (v1) and under `data` (v2).\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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Forbidden" }, "message": { "type": "string", "example": "Payment sessions are not enabled for this business" } } } } } }, "422": { "description": "Unprocessable entity — invalid format for `email`, `customer_id`, `pan`, `phone`, `country`, or `dob`, or `phone` supplied without `country`.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unprocessable Entity" }, "message": { "type": "string", "example": "email is invalid" } } } } } } }, "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", "example": "investor@example.com" }, "pan": { "type": "string", "pattern": "^[A-Z]{3}P[A-Z][0-9]{4}[A-Z]$", "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", "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" ] }, "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).\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 webhook.\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, or expired — 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). 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.\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.\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. 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. 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.\n", "type": "array", "items": { "$ref": "#/components/schemas/Balance" } }, "pending": { "description": "The pending balance, by currency, awaiting maturity to available.\n", "type": "array", "items": { "$ref": "#/components/schemas/Balance" } }, "deficit": { "description": "The amount, by currency, owed to Glomo. 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": "The the conversion rate used for the currency(ies) for a given transaction.\n", "example": 1.4 } } }, "BalanceConversion": { "type": "object", "x-tags": [ "balance_conversions" ], "properties": { "id": { "type": "string", "format": "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": [ "success", "failed", "pending" ], "description": "The status of the balance conversion.\n", "example": "success" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date and time the balance conversion was created.\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": { "$ref": "#/components/schemas/Money", "description": "The fee charged for the bank account validation process.\n" } } }, "BankAccount": { "type": "object", "x-tags": [ "bank_account" ], "properties": { "country": { "type": "string", "format": "iso-3166-1-alpha-3, case-insensitive", "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" }, "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. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. 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", "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", "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.\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", "postal_code" ], "description": "The address of the beneficiary. All fields except address_line2 are required.\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 (required).", "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", "postal_code" ], "description": "The address of the bank. Required for `category: lrs`, optional for `category: payout`. When sent, all fields except address_line2 are required.\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 (required).", "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.\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", "description": "The date of birth of the customer\n", "example": "2003-11-29" }, "nationality": { "type": "string", "description": "The nationality of the customer\n", "example": "IND" }, "tax_identification_number": { "type": "string", "description": "**Applicable only to the LRS (Liberalised Remittance Scheme / resident-India remittance) flow.** The customer's PAN (tax identification number), populated only for customers onboarded under LRS and absent otherwise. Searchable via the `tax_identification_number` query parameter on the list-customers endpoint.\n", "example": "BFQPG7654R" }, "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": "timestamp", "readOnly": true, "description": "Timestamp representing when the customer was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the customer was last updated\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" } } }, "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": "timestamp", "readOnly": true, "description": "Timestamp representing when the document was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the document was last updated\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" } }, "Orders": { "type": "object", "x-tags": [ "Orders" ], "properties": { "id": { "type": "string", "format": "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", "paid", "failed", "action_required", "under_review", "expired" ], "description": "The status of the Order.\n", "example": "active" }, "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 and GBP.\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": "Purpose code for why you want to receive this payment\n", "example": "P1401" }, "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 in cents for which invoice was generated. It can be more than the amount requested in this order\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" } }, "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.\n", "example": [ "card" ] }, "created_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the order was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the order was last updated\n", "example": "2021-06-01T12:00:00Z" }, "request_id": { "type": "string", "description": "Optional idempotency key.\n", "example": "unique_order_request_id_123" } } }, "OrderResponse": { "allOf": [ { "$ref": "#/components/schemas/Orders" }, { "type": "object", "properties": { "id": { "type": "string", "format": "string", "readOnly": true, "description": "The unique identifier for the order.\n", "example": "order_678a4c88hpAjf" }, "status": { "type": "string", "readOnly": true, "enum": [ "active", "paid", "failed", "action_required", "under_review", "expired" ], "description": "The status of the Order.\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" } ] }, "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" } }, "created_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the order was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the order was last updated\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" }, "purpose_code": { "type": "string", "description": "Purpose code for why you want to receive this payment.\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 in cents for which invoice was generated. It can be more than the amount requested in this order.\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": "Optional idempotency key.\n", "example": "unique_order_request_id_123" } } }, "PaymentLink": { "type": "object", "x-tags": [ "payment_link" ], "properties": { "id": { "type": "string", "format": "string", "readOnly": true, "description": "The unique identifier for the payment link.\n", "example": "payin_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", "paid", "failed", "action_required", "cancelled", "partially_paid", "under_review", "expired" ], "description": "The status of the payment_link.\n", "example": "success" }, "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.\n", "example": [ "card" ] }, "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 and GBP.\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": "Purpose code for why you want to receive this payment\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": "timestamp", "description": "Date when the payment_link will expire. Expiry can not be less than or equal to current date and can be upto 6 months in future.\n", "example": "2025-02-15T00:00:00.000Z" }, "last_reminder_sent_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Last time when the customer was reminded to complete the payment by visiting the link\n", "example": "2024-09-13T06:32:34.340Z" }, "invoice_amount": { "type": "number", "description": "The amount in cents for which invoice was generated. It can be more than the amount requested in this payment_link\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": "timestamp", "readOnly": true, "description": "Timestamp representing when the payment_link was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the payment_link was last updated\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", "format": "string", "readOnly": true, "description": "The unique identifier for the payment link.\n", "example": "payin_678a4c88hpAjf" }, "status": { "type": "string", "readOnly": true, "enum": [ "active", "paid", "failed", "action_required", "cancelled", "partially_paid", "under_review", "expired" ], "description": "The status of the payment_link.\n", "example": "success" }, "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", "format": "timestamp", "readOnly": true, "description": "Last time when the customer was reminded to complete the payment by visiting the link\n", "example": "2024-09-13T06:32:34.340Z" }, "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" } }, "created_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the payment_link was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the payment_link was last updated\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": "Purpose code for why you want to receive this payment.\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 in cents for which invoice was generated. It can be more than the amount requested in this payment_link.\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", "format": "uuid", "readOnly": true, "description": "The unique identifier for the payin.\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", "example": "success" }, "destination_amount": { "type": "number", "minimum": 1, "description": "The amount the beneficiary will receive, expressed in the smallest unit of the specified currency (e.g., cents for USD, paisa for INR). \n For example, 1000 represents $10.00 in USD. The actual currency is determined by the currency field. Note: \"cents\" is used generically to denote \n the minimal currency unit, not necessarily 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, also specified in the smallest unit of the selected currency. For example, 1000 equates to $10.00 in USD. The currency field determines which currency is used. As with destination_amount, \"cents\" is a placeholder for the minimal unit, not specifically 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", "format": "uuid", "description": "The unique identifier for the beneficiary.\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 for why you want to receive this payment\n", "example": "S0017" }, "mid_market_rate": { "type": "object", "readOnly": true, "properties": { "currency": { "type": [ "string", "null" ], "format": "iso-4217", "description": "The destination currency code", "example": "USD" }, "rate": { "type": [ "number", "null" ], "format": "float", "description": "The conversion rate factor", "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", "format": "iso-4217", "description": "The currency code for the FX fee", "example": "USD" }, "amount": { "type": "number", "description": "The amount of the FX fee", "example": 200 } }, "description": "The foreign exchange fees applied to the payout" }, "txn_fee": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code for the transaction fee", "example": "USD" }, "amount": { "type": "number", "description": "The amount of the transaction fee", "example": 100 } }, "description": "The transaction fees applied to the payout" } }, "description": "The fees applied to this payout\n" }, "created_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the payout was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the payout was last updated\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 client-provided unique identifier for this payout request. Can be used to look up the payout via `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", 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`. `swift` is used for international transfers.\n", "example": "swift" }, "invoice_number": { "type": [ "string", "null" ], "readOnly": true, "maxLength": 50, "description": "The invoice reference provided when the payout was created.\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", "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| `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" }, "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": "Purpose code for this payout.\n", "example": "PYR002" }, "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 from which the amount is deducted from your source balance.\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 the source currency (e.g. 1000 equates to $10.00 in USD).\n\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 the destination currency (e.g. cents for USD, paisa for INR).\n\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", "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`. `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.\n", "example": "INV-2026-001" }, "request_id": { "type": "string", "maxLength": 64, "description": "A unique client-generated identifier for this payout request. If a payout with the same `request_id` already exists for your business, the API returns a `409 Conflict` response. Use this to safely retry payout creation without risk of creating duplicates. You can look up the existing payout using `GET /v1/payouts?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" } } }, "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": "Purpose code for this payout.\n", "example": "PYR002" }, "invoice_number": { "type": "string", "maxLength": 50, "description": "An optional invoice reference for this payout.\n", "example": "INV-2026-001" }, "request_id": { "type": "string", "maxLength": 64, "description": "A unique client-generated identifier for this payout request. If a payout with the same `request_id` already exists for your business, the API returns a `409 Conflict` response. Use this to safely retry payout creation without risk of creating duplicates. You can look up the existing payout using `GET /v1/payouts?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" }, "source_currency": { "type": "string", "format": "iso-4217", "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", "description": "The destination currency code 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 the source currency (e.g., cents for USD, paisa for INR).\nFor example, 10000 represents $100.00 in USD.\n\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 the destination currency.\n\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" ], "description": "The payment method. Card is not supported for quotes.\n", "example": "bank_transfer" }, "subtype": { "type": "string", "enum": [ "local_transfer", "swift_transfer" ], "description": "The payment method subtype. The 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", "subtype" ], "description": "The payment method details to price. `pay_via_bank` only supports the `local_transfer` 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" }, "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" ], "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.", "example": "swift_transfer" }, "rail": { "type": "string", "description": "The derived payment rail for this quote. Present only for payout quotes. Local transfers to INR yield one quote per rail (`upi`, `imps`, `neft`, `rtgs`); SWIFT transfers yield a single `swift` quote.\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 exchange rate applied for this quote.\n", "example": 90 }, "source_amount": { "type": "integer", "readOnly": true, "description": "The total source amount in the smallest unit of the source currency.\n", "example": 10000 }, "destination_amount": { "type": "integer", "readOnly": true, "description": "The destination amount in the smallest unit of the destination currency.\n", "example": 882000 }, "fees": { "type": "object", "readOnly": true, "properties": { "txn_fee": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code for the transaction fee", "example": "USD" }, "amount": { "type": "integer", "description": "The transaction fee in the smallest unit of the currency", "example": 100 } }, "description": "The transaction fee applied to this quote" }, "fx_fee": { "type": "object", "properties": { "currency": { "type": "string", "format": "iso-4217", "description": "The currency code for the FX fee", "example": "USD" }, "amount": { "type": "integer", "description": "The FX fee in the smallest unit of the currency", "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 code for the referral fee", "example": "USD" }, "amount": { "type": "integer", "description": "The referral fee in the smallest unit of the currency", "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" } } }, "MockUpdatePayoutStatusRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the payout.\n", "example": "payout_E602dMzgjpDC" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "action_required", "cancelled" ], "description": "The status of the payout.\n", "example": "success" } } }, "TaxLine": { "type": "object", "properties": { "amount": { "type": "number", "description": "The tax amount in the smallest currency unit (cents). For example, 1800 cents is $18.00.\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 currency unit (cents), aggregated across all rules for this fee bearer. For example, 250 cents is $2.50.\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" ], "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": "payin_E602dMzgjpDC" }, "payin_type": { "type": [ "string", "null" ], "description": "The type of the payin. This is set only for payments associated to a payin.\n", "enum": [ "payment_link", "orders", "add_funds" ] }, "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": [ "success", "failed", "action_required", "in_progress", "under_review" ], "description": "The status of the payment.\n" }, "compliance_status": { "type": [ "string", "null" ], "readOnly": true, "enum": [ "action_required", "under_review", "approved", "rejected" ], "description": "The compliance review status of the payment. Present only for payments that have been screened for sanctions or transaction-monitoring holds; `null` for payments that were not screened. This is separate from `status` — a payment can be `status: success` while `compliance_status` is `action_required`, meaning the payment itself completed but funds are held pending compliance review. See the `rfi` field for what's required when `action_required`.\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.\n", "example": 1 } } } } } }, "payment_currency": { "type": "string", "format": "iso-4217, case-insensitive", "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 in cents (includes customer-borne fees if applicable). For example, 374580 cents is 3,745.80 AED. The currency is determined by the `payment_currency` field.\n", "example": 374580 }, "converted_currency": { "type": "string", "format": "iso-4217, case-insensitive", "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 final amount after currency conversion in cents (includes all fees). For example, 102000 cents is $1,020.00. The currency is determined by the `converted_currency` field.\n", "example": 102000 }, "requested_currency": { "type": "string", "format": "iso-4217, case-insensitive", "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 originally requested by the merchant in cents, excluding customer-borne fees. For example, 100000 cents is $1,000.00. The currency is determined by the `requested_currency` field.\n", "example": 100000 }, "purpose_code": { "type": "string", "description": "The purpose code of the payment. This should match the purpose code of the payin.\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" } }, "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": "The timestamp at which the payment was completed. `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" ], "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": "The creation timestamp of the payment.\n", "example": "2024-12-06T11:38:37.130Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "The last update timestamp of the payment.\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, case-insensitive", "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" }, "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.\n", "example": "4111111111111111" }, "expiry_month": { "type": "string", "description": "The card expiry month (MM format).\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').\n", "example": "30" }, "cvv": { "type": "string", "description": "The card CVV/CVC code.\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.\n", "example": "https://server.yoursite.com/payment/callback" }, "request_id": { "type": "string", "description": "Idempotency key. Required for subsequent payments, optional for initial payments.\n", "example": "unique_request_id_123" }, "amount": { "type": "integer", "minimum": 1, "description": "Payment amount in minor units (cents). Required for subsequent subscription payments. Cannot exceed the subscription's `max_amount`.\n", "example": 1500 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "description": "Currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Must match the subscription's currency for subsequent 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": [ "pending", "success", "failed", "action_required", "in_progress", "under_review" ], "description": "The current status of the payment.\n", "example": "pending" }, "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", "format": "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", "description": "The reason for the refund.\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.\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 cents.\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": [ "success", "failed", "action_required", "pending", "under_review" ], "description": "The status of the refund.\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 amount you want to receive in cents. For example, 1000 cents is $10.00. The currency is determined by the `currency` field. `Cents` is a general term for the smallest unit of currency in any currency. It does not necessarily mean USD cents.\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 }, "created_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the refund was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the refund was last updated\n", "example": "2021-06-01T12:00:00Z" }, "request_id": { "type": "string", "readOnly": true, "description": "Optional idempotency key.\n", "example": false } } }, "Price": { "type": "object", "x-tags": [ "Price" ], "properties": { "id": { "type": "string", "readOnly": true, "description": "The unique identifier for the payin.\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": "Basis points for the pricing.\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": "timestamp", "readOnly": true, "description": "Timestamp representing when the payin was created\n", "example": "2021-06-01T12:00:00Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the payin was last updated\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, "description": "The payment rail this rule applies to. `null` when the rule applies to every rail.\n", "example": "swift" }, "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 minor units of `fees_currency`. 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`. 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 minor units of `min_max_fee_currency`. `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 minor units of `min_max_fee_currency`. `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`. `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 minor units of `fee_currency`. 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 minor units of `fee_currency`. `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 minor units of `fee_currency`. `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": "Timestamp representing when the pricing split was created.\n", "example": "2026-08-01T09:12:44Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "Timestamp representing when the pricing split was last updated.\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.\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 minor units of `fee_currency`. Required on a `fixed` rule. Cannot exceed the rule's own `fees_amount`.\n\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 minor units of `fee_currency`. 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 minor units of `fee_currency`. 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.", "enum": [ "created", "active", "paused", "expired", "failed", "halted", "cancelled", "completed", "authorized" ], "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. Null for 'as_presented' subscriptions.", "example": 12 }, "max_amount": { "type": [ "integer", "null" ], "description": "Maximum allowed amount per payment. Present only for 'as_presented' subscriptions, null for regular subscriptions.", "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.", "example": "https://checkout.glomopay.com/subscription/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.", "enum": [ "MAX_RETRIES_REACHED", "CARD_EXPIRED" ], "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.", "example": "ShieldGuard Insurance" }, "product_description": { "type": "string", "maxLength": 512, "description": "Description of the product.", "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.", "example": "ShieldGuard Lite" }, "plan_description": { "type": "string", "maxLength": 512, "description": "Description of the subscription plan.", "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", "example": 12 }, "max_amount": { "type": "integer", "minimum": 1, "description": "Maximum allowed amount per payment for 'as_presented' subscriptions. Required when interval_type is 'as_presented', 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 >= start_date and cannot be more than 30 days from start_date.", "example": "2025-01-07" }, "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.", "enum": [ "created", "active", "paused", "expired", "failed", "halted", "cancelled", "completed", "authorized" ], "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. Null for 'as_presented' subscriptions.", "example": 12 }, "max_amount": { "type": [ "integer", "null" ], "description": "Maximum allowed amount per payment. Present only for 'as_presented' subscriptions, null for regular subscriptions.", "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.", "example": "https://checkout.glomopay.com/subscription/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 cents. For example, 1000 cents is $10.00. The currency is determined by the `currency` field.\n", "example": 1000 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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 amount of the foreign exchange fee in cents. For example, 1000 cents is $10.00.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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 amount of the transaction fee in cents. For example, 1000 cents is $10.00.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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": "The creation timestamp of the settlement.\n", "example": "2024-12-06T11:38:37.130Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "The last update timestamp of the settlement.\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`.\n", "example": 1000 }, "balance_currency": { "type": "string", "format": "iso-4217", "description": "The balance which you want use to make the settlement. This is the currency in which the amount will be deducted from your balance.\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.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The amount credited in cents. For example, 1000 cents is $10.00.\n", "example": 1000 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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.\n", "properties": { "amount": { "type": "number", "minimum": 0, "description": "The amount debited in cents. For example, 1000 cents is $10.00.\n", "example": 0 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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 amount of the foreign exchange fee in cents. For example, 1000 cents is $10.00.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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 amount of the transaction fee in cents. For example, 1000 cents is $10.00.\n", "example": 10 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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.\n", "properties": { "amount": { "type": "number", "minimum": 1, "description": "The amount settled in cents. For example, 1000 cents is $10.00.\n", "example": 980 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "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": "The timestamp when the transaction was processed.\n", "example": "2024-12-06T11:38:37.130Z" }, "created_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "The creation timestamp of the transaction.\n", "example": "2024-12-06T11:38:37.130Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "The last update timestamp of the transaction.\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", "example": "active" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date and time when the virtual account was created.\n", "example": "2025-08-19T07:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "The date and time when the virtual account was last updated.\n", "example": "2025-08-19T07:00:00Z" }, "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": "Business registration number", "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" } ] } }, "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", "success", "action_required", "pending", "failed", "offboarded" ], "description": "Current merchant status", "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 (only required for individual entity_type)", "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": "Timestamp when the merchant was created", "example": "2025-10-07T06:11:47Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the merchant was last updated", "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 (only required for individual entity_type)", "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": "Timestamp when the merchant was created", "example": "2025-10-07T06:11:47Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the merchant was last updated", "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 cents. For example, 10000 cents is 100.00. The currency is determined by the `currency` field.\n", "example": 10000 }, "currency": { "type": "string", "format": "iso-4217, case-insensitive", "description": "The currency in which the transfer is made. The currency code is in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. Currently only AED is supported for internal transfers.\n", "enum": [ "AED" ], "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 cents. For example, 1000 cents is 10.00.\n", "example": 1000 }, "transfer_currency": { "type": "string", "format": "iso-4217, case-insensitive", "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": "The creation timestamp of the internal transfer.\n", "example": "2025-10-17T08:06:42Z" }, "updated_at": { "type": "string", "readOnly": true, "format": "date-time", "description": "The last update timestamp of the internal transfer.\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", "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": "Timestamp representing when the KYC document record was created.\n", "example": "2026-03-13T11:48:14.458Z" }, "uploaded_at": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true, "description": "Timestamp representing when the document file was uploaded. 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, "description": "The current status of the KYC link. Possible values: `initiated`, `in_progress`, `completed`, `action_required`, `under_review`, `rejected`.\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": "Timestamp representing when the KYC link expires.\n", "example": "2026-06-11T11:48:14.361Z" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "description": "Timestamp representing when the KYC link was created.\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": "Timestamp of the tracker event.\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" } } } }, "PaymentSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the payment session, prefixed with `psess_`.", "example": "psess_6819d8046mpKt" }, "status": { "type": "string", "description": "Current status of the payment session.", "example": "active" }, "session_type": { "type": "string", "description": "The workflow type configured for this session, which determines the pre-steps and/or post-steps in the payment journey. The value is configured per business. For example, `kyc_lrs` adds KYC verification before the LRS remittance checkout.\n", "example": "kyc_lrs" }, "token": { "type": "string", "description": "Short-lived JWT token to be passed to the Glomo Web SDK 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" ], "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. The final decision (`approved` or `rejected`) is communicated via webhook.\n", "example": "approved" }, "created_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the RFI was created.\n", "example": "2026-08-12T10:51:04.747Z" }, "updated_at": { "type": "string", "format": "timestamp", "readOnly": true, "description": "Timestamp representing when the RFI was last updated.\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" ], "description": "The current status of the RFI. A successful response transitions the RFI from `information_required` to `submitted`. The final decision (`approved` or `rejected`) is communicated via webhook.\n", "example": "submitted" } } } }, "parameters": { "BeforeParam": { "in": "query", "name": "before", "schema": { "type": "string", "format": "timestamp" }, "description": "[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp in UTC to filter resources created before this time. Use this to avoid `Page drift` issue. See [Pagination parameters](/platform/pagination#parameters) for more details.\n", "example": "2025-02-18T12:03:44Z" }, "AfterParam": { "in": "query", "name": "after", "schema": { "type": "string", "format": "timestamp" }, "description": "[ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp in UTC to filter resources created after this time. Use this to avoid `Page drift` issue. 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." } } } }