--- title: "New Checkout" method: POST path: "/checkout" tags: ["Hosted Checkout"] --- # New Checkout `POST /checkout` ## Request - Base URL: `https://api.finmo.net/v1` - URL: `https://api.finmo.net/v1/checkout` - Auth: HTTP basic Checkout generates a secure, Finmo-hosted payment page that facilitates the collection of payments via local methods such as bank transfers, cards, direct debit, and wallets swiftly. It functions seamlessly across devices, potentially boosting your conversion rates. Checkout simplifies the process of creating an optimal payment experience: * Designed to minimize friction * Mobile-ready * Supports multiple global payment methods * White Label – Customize by adding logo, support details, and payment instructions specific to the payment method * Customizable buttons and background color ### Optimizing the Checkout Experience **Step 1:** Determine the time frame for the customers to complete the payment and set an expiration date-time. Typically, if the payment method supports expiration, it will share the same date-time. For example, PayID in Australia usually expires within 24 hours. **Step 2:** Decide on offering specific payment methods, an entire set, or just a category to the customer. This can be managed using include & exclude options. Categories refer to types of payment methods like Bank, E-Wallet, Card, etc. **Step 3:** Choose how the Checkout completion should work, i.e., if the user be redirected to a single URL or multiple URLs. The field called ```REDIRECT_URL``` stands for a common redirect URL. The status message can be handled based on the parameters provided in the ```REDIRECT_URL```. Alternatively, four different or identical URLs can also be provided under ```ADVANCED_REDIRECT_URL```, allowing the capability to display the appropriate status message based on events on the checkout page. **Step 4:** Customers can be notified about the checkout link via email or SMS. Finmo will send them the link to pay the invoice amount through the checkout link. ### Checkout Status & Webhook Notifications Finmo will notify about any status updates of the Checkout object via webhooks. Static webhook listener URL can also be configured via the dashboard or a dynamic webhook URL can be sent in the Create Checkout request. * **CHECKOUT_CREATED:** Triggered when a Checkout page is created. The Checkout status will be ```CREATED```. * **PAYIN_CREATED:** Triggered once the customer selects the payment method on the Checkout page and submits. This webhook includes the ```CHECKOUT_ID``` to link the payment to the customer. The Checkout status remains ```CREATED```, while the payment status updates to ```PENDING```. * **CHECKOUT_COMPLETED and PAYIN_COMPLETED:** Triggered once the consumer makes the payment. Both the Checkout and Payment status updates to ```COMPLETED```. * **CHECKOUT_EXPIRED and PAYIN_EXPIRED:** Triggered if the Checkout page expires. Both the Checkout and payment status updates to ```EXPIRED```. * **CHECKOUT_CANCELLED:** Triggered if the consumer cancels the Checkout page. If the payment method ```is_cancellable = true```, the payment will also be cancelled. Both the Checkout and payment status updates to ```CANCELLED```. ### Creating a Checkout Page Create a checkout page that builds a Payin. This method can be used without requiring PCI certification. ## Request body - object - `amount` integer, required: Transaction amount. The number of decimal place will be different for each currency according to ISO 4217 - `amount_breakdown` object: List of items that sum up together to match 'amount'. Example: { 'laptop': 2000, 'taxes': 100 } - `currency` string, required: Transaction currency - `country` string, required: Merchant country code. ISO 3166-1, 2-char alphabetic code - `redirect_url` string, uri, required: The link that the page will be redirected to after transaction. Either advanced_redirect_url or redirect_url should be present - `advanced_redirect_url` object: The link that the page will be redirected in the different cases. Either advanced_redirect_url or redirect_url should be present - `cancelled_url` string: The link that the page will be redirected in the case of cancellation - `completed_url` string: The link that the page will be redirected in the case of completion - `expired_url` string: The link that the page will be redirected in the case of expiration - `failed_url` string: The link that the page will be redirected in the case of failure - `succeeded_url` string: The link that the page will be redirected in the case of success - `awaiting_funds_url` string: The link that the page will be redirected while awaiting funds - `description` string: Transaction Description - `include_category` string[]: Category to include for the transaction (For e.g. BANK, EWALLET, CARD etc) Currently only 'BANK' and 'EWALLET' are supported - `exclude_category` string[]: Category to exclude for the transaction (For e.g. BANK, EWALLET, CARD etc) Currently only 'BANK' and 'EWALLET' are supported If the include_category parameter is present then this parameter will not be considered - `include_payin_method` string[]: Payin-Method to be included for the transaction - `exclude_payin_method` string[]: Payin-Method to be excluded for the transaction If the include_payin_method parameter is present then this parameter will not be considered - `credit_wallet_id` string: Provide the Wallet ID where the funds are to be credited. If no wallet id is provided, we assume its the Organization Payin wallet - `customer_id` string: Customer reference (customer_*) - `fees_wallet_id` string: Fees Wallet ID (wallet_*) - `organization_reference_id` string: A reference you can later use to identify this payment, such as an order number. Can only be alphanumeric and must be unique for Benefit. - `notification_email` string, email: Email to recieve the checkout link - `notification_phone_country_code` string: Country code of the mobile number to receive the checkout link - `notification_phone_number` string: Mobile Number to receive the checkout link without the country code - `expire_at` integer: Epoch timestamp at which the payment expires - `metadata` object: Custom Data - `any-custom-ref` string - `receipt_email` string, email: Provide an email if you would like to send a receipt to your customer or yourself after the payin or refund is successfully completed - `webhook_url` string, uri: Dynamic webhook URL of the transaction otherwise the one configured on the dashboard would be used - `payin_method_name` string: Name of payin method - `payin_method_param` object: Required parameters of payin method - `payid_reference` string - `payin_type` string: Type of payin - `recurring_payin` object: Configuration for recurring payments - `frequency` 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'YEARLY': Frequency of recurring payments - `start_at` string, date-time: Start date for recurring payments - `is_recurring_amount_fixed` boolean: Whether the recurring amount is fixed - `capture_config` object: Configuration for payment capture - `capture_delay` integer: Delay in seconds before capturing the payment - `capture_type` 'IMMEDIATE' | 'DELAYED' | 'MANUAL': Type of capture (immediate , delayed , manual) - `tnc_and_policies_url` object: Configure links to your legal policies so customers can review them before completing the payment. - `tnc_url` string, uri: Terms and conditions URL - `refund_policy_url` string, uri: Refund policy URL - `return_policy_url` string, uri: Return policy URL ## Response `201` Created - object - `data` object - `advanced_redirect_url` string, uri, nullable - `amount` number - `amount_breakdown` string, nullable - `associated_payin_id` string[] - `cancelled_at` string, date-time, nullable - `checkout_id` string - `checkout_token` string - `checkout_url` string, uri - `country` string - `created_at` string, date-time - `credit_wallet_id` string - `currency` string - `customer_id` string, nullable - `description` string, nullable - `expire_at` string, date-time - `expired_at` string, date-time, nullable - `is_cancelled` boolean - `is_expired` boolean - `metadata` string, nullable - `notification_email` string, nullable - `notification_phone_country_code` string, nullable - `notification_phone_number` string, nullable - `notification_phone_number_e164` string, nullable - `org_id` string - `organization_reference_id` string, nullable - `payin_id` string, nullable - `receipt_email` string - `redirect_url` string, uri - `status` string - `updated_at` string, date-time - `webhook_url` string, uri, nullable - `tnc_and_policies_url` object, nullable - `tnc_url` string, uri, nullable: Terms and conditions URL - `refund_policy_url` string, uri, nullable: Refund policy URL - `return_policy_url` string, uri, nullable: Return policy URL - `request_id` string - `request_time` string, date-time - `status_code` integer - `status_text` string - `success` boolean ## Other responses - `400`: Bad Request - `406`: Not Acceptable ## Changes - **2026-11-03** `39e5e5ab5c3a`: 1 info - endpoint added [Operation history](https://skmtc.dev/finmo/apis/finmo-api/changes/checkout/post.md) --- [API](https://skmtc.dev/finmo/apis/finmo-api.md) - [All operations](https://skmtc.dev/finmo/apis/finmo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/finmo/apis/finmo-api/revisions/39e5e5ab5c3a?raw)