--- title: "Create Payin" method: POST path: "/payin" tags: ["Payin"] --- # Create Payin `POST /payin` ## Request - Base URL: `https://api.finmo.net/v1` - URL: `https://api.finmo.net/v1/payin` - Auth: HTTP basic **Payin** is the primary Method for collecting funds from customers and depositing them into either the customer wallet or the Merchant's Payin wallet. For more information about Payin, use [Finmo’s Client Portal](https://dashboard.finmo.net). Finmo supports the following scenarios for collecting funds from end customers: * **eCommerce Purchases:** Merchants can accept payments through either the Direct API or Hosted Checkout Methods. Payment options include PUSH-DEBIT, where we create one-time or dynamic virtual accounts or PayIDs, requiring customers to transfer funds from their bank accounts. Alternatively, PULL-DEBIT Methods like Cards, E-Wallets, or Direct Debit can be used, where customers authenticate and complete the payment using their card details or bank accounts. * **Wallet Top-ups:** Finmo can issue a static [Virtual Account](/reference/getallvirtualaccount-1) or PayID for each registered customer. Customers can transfer funds to these Virtual Accounts as needed. Finmo provides real-time webhook notifications to merchants upon receipt of funds, which are settled according to your agreement with Finmo. * **Recurring Payments:** Merchants can request a payment token for CARD-ON-FILE purchases or an eMandate, such as a Direct Debit Authority, to periodically debit customer accounts. To successfully perform a Payin via the Finmo platform, the following APIs are required: **Step 1: [List all Payin-Methods by Currency & Country](/reference/listpayinmethodsbycountrycurrency-1)** * This API retrieves all the Payin Methods supported for a specific country and currency. **Step 2: [Get the required fields by Payin-Method](/reference/getrequiredfieldsbypayinmethod-1)** * For example, when making a card payment, a merchant specifies the type of cards he’ll accept, likewise for Payin, an invoice reference is required to create and pass it through the API. **Step 3: Create the Payin** * Pass the required fields for the Payin Method to create a Payin. **Step 4: [Simulate Payin](/reference/simulatepayincompletioncancellation-1)** * To complete your simulation in the sandbox environment, run the Simulate Payin API. **Note:** To collect funds in a customer's wallet, first create the [customer](/reference/newcustomerindividual-1) and add a [wallet](/reference/newwallet-1) to it. Funds collected in the customer's wallet are not settled in your account. ### Payin Status & Webhook Notifications Finmo will notify you about incoming funds or any changes to the status of a Payin object via [webhooks](/reference/getallwebhooknotification-1). You can set up a static webhook listener URL through the [dashboard](https://dashboard.finmo.net/preview/dashboards/setting/developer/webhook-url), or you can provide a dynamic webhook URL in the Create Payin request. * **Payin_CREATED:** When a Payin is initiated, Finmo sends this webhook, and the Payin status updates to ```PENDING```. * **Payin_COMPLETED:** This webhook is triggered when the customer’s payment has been successfully received and the funds have settled into Finmo’s bank account (or one of our network partner accounts). The Payin status updates to ```COMPLETED```. * **Payin_SUCCEEDED:** This webhook is triggered when the customer’s payment is successfully processed by the payment provider, and the transaction is confirmed as successful. You can now proceed to fulfill the order. The Payin status updates to ```SUCCEEDED```. * **Payin_EXPIRED:** If a Payin expires before the payment is completed, Finmo sends this webhook, and the Payin status updates to ```EXPIRED```. * **Payin_CANCELLED:** If a Payin is cancelled (as indicated by an attribute set for each Payin Method and returned by the Get Required Fields by Payin Method API), Finmo sends this webhook, and the Payin status updates to ```CANCELLED```. When a customer attempts to make a partial payment against a PENDING Payin, the Finmo platform usually returns the funds to the customer. However, in some cases, the sender's bank or network provider may not support this return, and the funds must be accepted. You can easily identify a partial payment versus a full payment through webhooks and by retrieving the Payin details. Look at the following two fields in the ```Payin_COMPLETED``` webhook: * **paid_amount:** This field shows the actual amount the customer paid for that Payin transaction. * **is_partially_paid:** This field is set to true if a partial payment was made. ### Payin Types Finmo supports various Payin types, representing the different ways a Payin can be created: * **DIRECT_Payin:** This Payin is created using the [Create Payin](/reference/createpayin-1) API. * **CHECKOUT_Payin:** This Payin is created using the [Hosted Checkout](/reference/newcheckout-1) API. * **VA_Payin:** This Payin is created for collecting funds to an existing [Virtual Account (VA)](/reference/newvirtualaccount-1). * **TOPUP:** This Payin is created for collecting funds to an existing Virtual Account (VA) associated with your Organization's Payin or Payout wallet. * **FEES_PAYMENT:** This Payin is created for collecting funds when making a payment against a Finmo invoice using an existing Virtual Account associated with your Organization Fee wallet. ## Request body - object - `amount` number, required: Transaction amount. The number of decimal place will be different for each currency according to ISO 4217 - `currency` string, required: Transaction currency. It has to be a valid ISO 4217 currency code - `payin_method_name` string, required: Payin method name to be used for this Payin (For e.g. au_bank_npp) - `payin_method_param` object, required: This is an optional field which may be required depending upon payin method. You will receive these params from Get Required Fields by Payin method API - `payid_reference` string - `redirect_url` string, uri: URL link that the page will be redirected in the case of success or failure. It is required only if advanced_redirect_url is not present - `advanced_redirect_url` object - `cancelled_url` string, required: Redirect url when payin is cancelled - `completed_url` string, required: Redirect url when payin is successful - `expired_url` string, required: Redirect url when payin expires - `failed_url` string, required: Redirect url when payin is failed - `fees_wallet_id` string: Fees Wallet ID(wallet_*) - `credit_wallet_id` string: Organization Payin Wallet ID (implicit) or customers Wallet ID. It is mandatory if customer has more than 2 linked wallets. If you dont provide anything in this field, it defaults to Payin wallet and funds will be credit to that wallet - `payin_type` string: Type of the PAYIN, defaults to DIRECT_PAYIN - `receipt_email` string, email: Email of the recipient - `checkout_id` string: Checkout ID (xo_*) - `description` string: Transaction Description - `customer_id` string: Customer_id. Its useful in scenarios where a merchant wants to create a customer profile and save their card tokens for future transactions - `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. - `metadata` object: Custom Data - `any-custom-ref` string - `expire_at` integer: EPOCH timestamp at which the payment expires - `webhook_url` string, uri: Custom webhook url for the payin. If it is not provided, webhook will be triggered to the endpoint configured in the Dashboard ## Response `201` Created - object - `data` object - `additional_data` object: Varies with different payins - `advanced_redirect_url` string, uri, nullable - `amount` integer - `cancelled_at` string, date-time, nullable - `checkout_id` string, nullable - `created_at` string, date-time - `credit_wallet_id` string - `credit_wallet_transaction_id` string, nullable - `currency` string - `customer_id` string, nullable - `description` string - `expire_at` string, date-time - `expired_at` string, date-time, nullable - `fees_currency` string, nullable - `fees_including_tax` string, nullable - `fees_wallet_id` string - `fees_wallet_transaction_id` string, nullable - `fees_without_tax` string, nullable - `is_cancellable` boolean - `is_chargeable` boolean - `is_completely_refunded` boolean - `is_fees_charged` boolean - `is_multiple_refund_allowed` boolean - `is_over_refundable` boolean - `is_paid` boolean - `is_partially_paid` boolean - `is_partially_refundable` boolean - `is_reconciled` boolean - `is_refund_initiated` boolean - `is_refundable` boolean - `metadata` object - `any-custom-ref` string - `org_id` string - `organization_reference_id` string, nullable - `paid_amount` string, nullable - `paid_at` string, date-time, nullable - `paid_currency` string, nullable - `pay_code` object: Object containing payment method–specific information returned after a payin is created. The contents of this object vary based on the payin_method_name. - `text` string - `redirect_url` string, url: Returned when the payment method requires the user to be redirected to complete the payment - `payin_id` string - `payin_method_category` string - `payin_method_description` string - `payin_method_name` string - `payin_method_param` object - `payid_reference` string - `payin_type` string - `reciept_email` string - `redirect_url` string, uri, nullable - `refund_amount_completed` string, nullable - `refund_amount_requested` string, nullable - `refund_currency_completed` string, nullable - `refund_currency_requested` string, nullable - `refund_status` string, nullable - `sender_party_detail` string, nullable - `status` string - `tax_on_fees` string, nullable - `transaction_id` string, nullable - `updated_at` string, date-time - `virtual_account_id` string, nullable - `webhook_url` string, uri, nullable - `request_id` string - `request_time` string, date-time - `status_code` integer - `status_text` string - `success` boolean ## Other responses - `400`: Bad Request - `404`: Not Found ## Changes - **2026-11-03** `39e5e5ab5c3a`: 1 info - endpoint added [Operation history](https://skmtc.dev/finmo/apis/finmo-api/changes/payin/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)