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.
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 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
- This API retrieves all the Payin Methods supported for a specific country and currency.
Step 2: Get the required fields by Payin-Method
- 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
- 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 and add a wallet 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. You can set up a static webhook listener URL through the dashboard, 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: Once the customer completes the payment, Finmo sends this webhook, and the Payin status updates to
COMPLETED. -
Payin_AWAITING_FUNDS: If the customer has made the transfer but Finmo is still awaiting funds from the partner bank, this webhook is sent, and the Payin status updates to
AWAITING_FUNDS. -
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 API.
-
CHECKOUT_Payin: This Payin is created using the Hosted Checkout API.
-
VA_Payin: This Payin is created for collecting funds to an existing Virtual Account (VA).
-
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.