# API specification for Glomo 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. You can download the complete API collection by using the download options on the right. Version: 1.0.0 License: Apache 2.0 ## Servers Production server ``` https://api.glomopay.com/api/v1 ``` ## Security ### JWT Your secret token to access the API. If you don't have one, please contact support. Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [API specification for Glomo](https://docs.glomopay.com/_bundle/api-documentation/apis/openapi.yaml) ## API Key Manage your Glomo API keys. Use this resource to rotate your secret key and maintain secure access to the API. ### Rotate API key - [POST /api-keys/rotate](https://docs.glomopay.com/api-documentation/apis/openapi/api_key/rotateapikey.md): 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. ## Balance 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. ### Retrieve balances - [GET /balances](https://docs.glomopay.com/api-documentation/apis/openapi/balance/getbalance.md): Retrieves available balances for all currencies. ## Balance Conversions 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. ### Convert balances - [POST /balance_conversions](https://docs.glomopay.com/api-documentation/apis/openapi/balance_conversions/createbalanceconversion.md): 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. ### List all Balance Conversions - [GET /balance_conversions](https://docs.glomopay.com/api-documentation/apis/openapi/balance_conversions/getbalanceconversions.md): Returns a list of your balance conversions. The balance conversions are returned sorted by creation date, with the most recent beneficiary appearing first. ## FX 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. ### Get Mid-Market Rate - [GET /fx-rate](https://docs.glomopay.com/api-documentation/apis/openapi/fx_rate/getmidmarketrate.md): 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. Notes: - This returns the mid-market rate only. FX fees are charged separately on top of this rate during actual conversions. - The rate is cached and expires_at indicates when the cached rate expires. ## Payment Link 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. ### Create a new Payment Link - [POST /payin](https://docs.glomopay.com/api-documentation/apis/openapi/payment_link/createpayin.md): Creates a shareable URL for a hosted payment page. To check complete list of API validations, click here. ### List all payment links - [GET /payin](https://docs.glomopay.com/api-documentation/apis/openapi/payment_link/getpayins.md): Returns a list of your payment links. The payment links are returned sorted by creation date, with the most recent payment link appearing first. ### Retrieve a payment link - [GET /payin/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/payment_link/getpayinbyid.md): Retrieve details of a payment link. ### Update an existing payment link - [PATCH /payin/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/payment_link/updatepayin.md) ### Cancel a payment link - [PATCH /payin/{id}/cancel](https://docs.glomopay.com/api-documentation/apis/openapi/payment_link/cancelpayin.md): Invalidate payment link and prevent further transactions ### Update RFI documents for a payment link - [PATCH /payin/{id}/update_rfi](https://docs.glomopay.com/api-documentation/apis/openapi/payment_link/updatepayinrfi.md): 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. ### Mock review a payment link - [PATCH /payin/{id}/mock_mark_reviewed](https://docs.glomopay.com/api-documentation/apis/openapi/payment_link/mockreviewpaymentlink.md): Mark an under_review payment link reviewed ## Orders This resource represents the order details. The order is the request to receive payment from your customer. ### Create a new order - [POST /orders](https://docs.glomopay.com/api-documentation/apis/openapi/orders/createorder.md): Creates an order for checkout. To check complete list of API validations, click here. ### List all orders - [GET /orders](https://docs.glomopay.com/api-documentation/apis/openapi/orders/getorders.md): Returns a list of your orders. The orders are returned sorted by creation date, with the most recent order appearing first. ### Retrieve an order - [GET /orders/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/orders/getorderbyid.md): Retrieve details of an order. ### Update RFI documents for an order - [PATCH /orders/{id}/update-rfi](https://docs.glomopay.com/api-documentation/apis/openapi/orders/updateorderrfi.md): 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. ## Customer This resource represents a customer of your business. The customer can be an individual or a business from whom you will receive payments. ### Create a new customer - [POST /customer](https://docs.glomopay.com/api-documentation/apis/openapi/customer/createcustomer.md): Creates a customer with basic information such as name, contact information, and address. To check complete list of API validations, click here. ### List all customers - [GET /customer](https://docs.glomopay.com/api-documentation/apis/openapi/customer/getcustomers.md): Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first. ### Retrieve a customer - [GET /customer/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/customer/getcustomerbyid.md): Retrieves details of a Customer. ## Payment This resource represents a payment attempt made by your customer. The payment can either be successfully completed or failed, depending on various factors. ### Create a payment - [POST /payment](https://docs.glomopay.com/api-documentation/apis/openapi/payment/createpayment.md): 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. Either order_id or subscription_id must be provided, but not both. ### List all payments - [GET /payment](https://docs.glomopay.com/api-documentation/apis/openapi/payment/getpayments.md) ### Create a mock payment - [POST /payment/mock](https://docs.glomopay.com/api-documentation/apis/openapi/payment/createmockpayment.md): This API is only available in sandbox mode. Creates a mock payment of specified amount for any given Payment link. ### Retrieve a payment - [GET /payment/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/payment/getpaymentbyid.md) ### Update RFI for Payment - [PATCH /payment/{id}/update_rfi](https://docs.glomopay.com/api-documentation/apis/openapi/payment/updaterfipayment.md) ### Mock funds available - [PATCH /payment/{id}/mock-funds-available](https://docs.glomopay.com/api-documentation/apis/openapi/payment/mockupdatepaymentfundsavailable.md): 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. ## Refund 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. ### Create refund for a payment - [POST /refunds](https://docs.glomopay.com/api-documentation/apis/openapi/refund/createrefund.md): Creates refund for a payment entity if the payment is in success state and no other refund exists. ### List all refunds - [GET /refunds](https://docs.glomopay.com/api-documentation/apis/openapi/refund/getrefunds.md): Returns a list of refunds in response. The refunds are returned sorted by creation date, with the most recent refund appearing first. ### Retrieve a refund - [GET /refunds/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/refund/getrefundbyid.md) ### Update RFI for Refund - [PATCH /refunds/{id}/update_rfi](https://docs.glomopay.com/api-documentation/apis/openapi/refund/updaterfirefund.md) ### Mock update a refund - [PATCH /refunds/{id}/mock_update_status](https://docs.glomopay.com/api-documentation/apis/openapi/refund/mockupdaterefund.md): Mark an in_progress refund as successful ## Price 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. ### Create a new price - [POST /prices](https://docs.glomopay.com/api-documentation/apis/openapi/price/createprice.md) ### List all prices - [GET /prices](https://docs.glomopay.com/api-documentation/apis/openapi/price/getprices.md) ### Retrieve a price - [GET /prices/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/price/getpricebyid.md) ## Payment Session 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. ### Create a payment session - [POST /payment-sessions](https://docs.glomopay.com/api-documentation/apis/openapi/payment_session/createpaymentsession.md): 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. 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. The token returned in the response should be passed to the Glomo Web SDK to launch the guided UI for the customer. Optionally 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. KYC prefill fields (pan, phone, country, dob) can be supplied under the nested kyc object to pre-populate KYC data in downstream session steps. These fields are only accepted when either customer_id or email is provided — supplying any prefill field without an identifier returns a 400 error. When phone is supplied, country (ISO 3166-1 alpha-3) is required and is used to validate the phone number format. Contact support if you receive a 403 error — payment sessions must be enabled for your business. ## Subscription 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. ### List subscriptions - [GET /subscriptions](https://docs.glomopay.com/api-documentation/apis/openapi/subscription/getsubscriptions.md): Returns a list of subscriptions matching some criteria. The subscriptions are returned sorted by creation date, with the most recent subscriptions appearing first. ### Create a new subscription - [POST /subscriptions](https://docs.glomopay.com/api-documentation/apis/openapi/subscription/createsubscription.md): 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. ### Retrieve a subscription by ID - [GET /subscriptions/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/subscription/getsubscriptionbyid.md): Retrieves the details of a specific subscription by its unique identifier. ### Pause a subscription - [PATCH /subscriptions/{id}/pause](https://docs.glomopay.com/api-documentation/apis/openapi/subscription/pausesubscription.md): Pauses an active subscription. While paused, the subscription will not process any payments. A paused subscription can be resumed later using the resume endpoint. ### Resume a paused subscription - [PATCH /subscriptions/{id}/resume](https://docs.glomopay.com/api-documentation/apis/openapi/subscription/resumesubscription.md): 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. ### Cancel a subscription - [PATCH /subscriptions/{id}/cancel](https://docs.glomopay.com/api-documentation/apis/openapi/subscription/cancelsubscription.md): 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. ### Update next payment date - [PATCH /subscriptions/{id}/next-payment-date](https://docs.glomopay.com/api-documentation/apis/openapi/subscription/updatenextpaymentdate.md): Updates the next payment date of a subscription. ## Payout This resource represents the disbursement transactions from your Glomo account to your beneficiaries. ### Create a new payout - [POST /payouts](https://docs.glomopay.com/api-documentation/apis/openapi/payout/createpayout.md) ### List all payouts - [GET /payouts](https://docs.glomopay.com/api-documentation/apis/openapi/payout/getpayouts.md) ### Retrieve a payout - [GET /payouts/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/payout/getpayoutbyid.md) ### Cancel a payout - [PATCH /payouts/{id}/cancel](https://docs.glomopay.com/api-documentation/apis/openapi/payout/cancelpayout.md) ### Update RFI for Payout - [PATCH /payouts/{id}/update_rfi](https://docs.glomopay.com/api-documentation/apis/openapi/payout/updaterfipayout.md) ### Create payout quotes - [POST /payouts/quotes](https://docs.glomopay.com/api-documentation/apis/openapi/payout/createpayoutquote.md): Create one or more payout quotes for a given currency pair and beneficiary. Each quote locks in an exchange rate and fee breakdown for 30 minutes. If payment_rail is not specified, quotes for all available payment rails are returned. Either source_amount or destination_amount must be provided, not both. ### Mock update a payout status - [PATCH /payouts/mock](https://docs.glomopay.com/api-documentation/apis/openapi/payout/mockupdatepayoutstatus.md) ## Beneficiary This resource represents a payee of a payout initiated by your business. The beneficiary can be an individual or a business to whom you will send funds. ### List all Beneficiaries - [GET /beneficiaries](https://docs.glomopay.com/api-documentation/apis/openapi/beneficiary/getbeneficiaries.md): Returns a list of your beneficiaries. The beneficiaries are returned sorted by creation date, with the most recent beneficiary appearing first. ### Retrieve a beneficiary - [GET /beneficiaries/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/beneficiary/getbeneficiarybyid.md): Retrieves details of a beneficiary. ### Create a Beneficiary (deprecated) - [POST /beneficiaries](https://docs.glomopay.com/api-documentation/apis/openapi/beneficiary/createbeneficiary.md): Creates a beneficiary with information such as name, contact, address, and banking information. ## Beneficiary V2 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. ### Create a Beneficiary - [POST /v2/beneficiaries](https://docs.glomopay.com/api-documentation/apis/openapi/beneficiary_v2/createbeneficiaryv2.md): Creates a beneficiary with structured nested objects for beneficiary details, address, and bank account or UPI information. ### List Beneficiaries - [GET /v2/beneficiaries](https://docs.glomopay.com/api-documentation/apis/openapi/beneficiary_v2/listbeneficiariesv2.md): Returns a paginated list of beneficiaries. Optionally filter by status. ### Get a Beneficiary - [GET /v2/beneficiaries/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/beneficiary_v2/getbeneficiarybyidv2.md): Retrieves the details of an existing beneficiary by ID. ### Mock Review a Beneficiary - [PATCH /v2/beneficiaries/{id}/mock-review](https://docs.glomopay.com/api-documentation/apis/openapi/beneficiary_v2/mockreviewbeneficiaryv2.md): Simulates a review action (approve or reject) on a beneficiary. This endpoint is only available in sandbox/non-production environments. ## Bank Account Validation Bank Account Validation resource represents the validation details of a bank account. ### Validate any bank account - [POST /bank_account_validation](https://docs.glomopay.com/api-documentation/apis/openapi/bank_account_validation/validatebankaccount.md) ### List all bank account validations - [GET /bank_account_validation](https://docs.glomopay.com/api-documentation/apis/openapi/bank_account_validation/getbankaccountvalidations.md) ## Document Document resource represents the documents details uploaded. This document is used in payin, payout, etc. ### Create a new document - [POST /document](https://docs.glomopay.com/api-documentation/apis/openapi/document/createdocument.md) ### List all documents - [GET /document](https://docs.glomopay.com/api-documentation/apis/openapi/document/getdocuments.md): Returns a list of your documents. The documents are returned sorted by creation date, with the most recent documents appearing first. ### Get a document by ID - [GET /document/{document_id}](https://docs.glomopay.com/api-documentation/apis/openapi/document/getdocumentbyid.md): Retrieve a single document by its unique identifier. ## Internal Transfer 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: | Transfer Type | Description | | ------------------------------ | ------------------------------------------------------------------------------ | | **P → C** | From a **Platform** (P) account to one of its **Child** (C) merchant accounts. | | **C → P** | From a **Child** (C) merchant account back to its **Platform** (P) account. | | **C → C (same P)** | Between **Child** (C) accounts under the same **Platform** (P). | ### Create an internal transfer - [POST /internal-transfer](https://docs.glomopay.com/api-documentation/apis/openapi/internal_transfer/createinternaltransfer.md): Creates an internal transfer between two merchant accounts. ## Settlement This resource represents the settlement details. The settlement is the process of transferring funds from your Glomo account to your bank account. ### Create a new settlement - [POST /settlements](https://docs.glomopay.com/api-documentation/apis/openapi/settlement/createsettlement.md) ### List all settlements - [GET /settlements](https://docs.glomopay.com/api-documentation/apis/openapi/settlement/getsettlements.md): Returns a list of your settlements. The settlements are returned sorted by creation date, with the most recent settlement appearing first. ### Retrieve a settlement - [GET /settlements/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/settlement/getsettlementbyid.md): Returns a specific settlement by its unique identifier. ### Retrieve transactions linked to a settlement - [GET /settlements/{id}/transactions](https://docs.glomopay.com/api-documentation/apis/openapi/settlement/gettransactionslinkedtosettlement.md): Returns a list of transactions that are linked to a specific settlement by its unique identifier. ## Virtual Account 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. ### List all Virtual Accounts - [GET /virtual-accounts](https://docs.glomopay.com/api-documentation/apis/openapi/virtual_account/getvirtualaccounts.md): Returns the customer's virtual accounts, sorted by creation date (newest first), using the customer's JWT token for access. ### Close a Virtual Account - [DELETE /virtual-accounts](https://docs.glomopay.com/api-documentation/apis/openapi/virtual_account/closevirtualaccount.md): 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. ### Create a Virtual Account (v2) - [POST /v2/virtual-accounts](https://docs.glomopay.com/api-documentation/apis/openapi/virtual_account/createvirtualaccountv2.md): 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 when the virtual account is activated. ## Platform This resource provides platform functionality that enables platforms to onboard merchants onto Glomo, with each merchant having their own dedicated Virtual Accounts (VA). ### Onboard a merchant - [POST /platform/merchants](https://docs.glomopay.com/api-documentation/apis/openapi/platform/onboardmerchant.md): Allows platforms to onboard a new merchant onto Glomo. ### Retrieve a merchant - [GET /platform/merchants/{merchant_id}](https://docs.glomopay.com/api-documentation/apis/openapi/platform/getmerchant.md): Retrieves details of a specific merchant by their merchant ID. ### Update merchant status - [PATCH /platform/merchants/status-update](https://docs.glomopay.com/api-documentation/apis/openapi/platform/updatemerchantstatus.md): Allows platforms to update the status of a merchant. This endpoint is available in non-production environments only. ## KYC Link 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. ### List KYC links - [GET /kyc-links](https://docs.glomopay.com/api-documentation/apis/openapi/kyclink/listkyclinks.md): 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. ### Create a KYC link - [POST /kyc-links](https://docs.glomopay.com/api-documentation/apis/openapi/kyclink/createkyclink.md): 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. By 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. The 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}. ### Retrieve a KYC link - [GET /kyc-links/{id}](https://docs.glomopay.com/api-documentation/apis/openapi/kyclink/getkyclinkbyid.md): Retrieves the details of a KYC link by its unique identifier, including the verification status, customer ID and the list of KYC documents submitted. Each 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).