Create Payin

post https://api.finmo.net/v1/payin

Payin is the basic mechanism for collecting money from customers and depositing it in the Merchant Payin wallet or other Finmo Customer wallets.

Create Payin

Customers can make payments using different payment methods in payment method categories such as Bank Transfers, E-Wallets, Cards (Domestic or International), Online Banking, Direct Debit or Virtual Accounts.

Finmo supports the following use-cases for collecting funds from your end consumer:

eCommerce Purchases : Merchants can use Direct API or Hosted Checkout method to accept Payments from consumers. Payin Methods include PUSH-DEBIT where we create a one-time/dynamic virtual accounts or PayID and the consumer is required to make a transfer from their bank account. Another option is PULL-DEBIT such as Cards, E-Wallets or Direct Debit where the consumer authenticates themselves and completes the payment using the card details provided or bank accounts.
Wallet Top-ups: Finmo can issue a static Virtual account or PayID for every customer who has registered with you. Customers can make funds transfers to these Virtual Accounts on as needs basis. Finmo sends real-time webhook notifications to the merchant once the funds are received. These funds will be settled back to you as per your settlement terms with Finmo.
Recurring payments: Merchants can request for a payment token that can be used for CARD-ON-FILE purchases or an eMandate like a Direct Debit Authority to periodically debit their accounts.

To be able to successfully perform a Payin via the Finmo platform you would need the following APIs in consideration:

Step 1 : List all Payin methods by Currency & Country - This API will provide you all the Payin methods supported for a country/currency combination.
Step 2 : Get the required fields by Payin method - This API will provide you the required parameter to capture the details from the consumer or let your platform take care of it. For e.g. if its a card payment then the consumer provides the card details but if the Payin requires an invoice reference can you create and pass it in the API.
Step 3 : Create the Payin by passing the required fields for the Payin method.
Step 4 : To complete your simulation in the sandbox, you must run Simulate Payin.

To collect funds to a Customer wallet, first create a customer and add a wallet to it. Funds collected in the Customer wallet are not settled to your account.

Payin Status & Webhook Notifications

Finmo will notify you of the incoming funds or status change of Payin object via webhooks. You can always choose to configure a static webhook listener URL via the dashboard or you can send a dynamic webhook URL in the Create Payin request.

When a Payin is created, Finmo sends a PAYIN_CREATED webhook. Payin status changes to PENDING.
When a Payin is completed i.e. the consumer makes the payment, Finmo will send you PAYIN_COMPLETED webhook. Payin status changes to COMPLETED.
If the customer has completed the transfer but Finmo is still waiting to receive funds from the partner bank, then a PAYIN_AWAITING_FUNDS webhook is sent. Payin status changes to AWAITING_FUNDS.
In case a Payin expires before the Payin is completed, Finmo will send you PAYIN_EXPIRED webhook. Payin status changes to EXPIRED.
If a Payin can be cancelled (it's an attribute that we setup for every Payin method and it's returned in Get Required Fields by Payin Method API), Finmo will send you a PAYIN_CANCELLED webhook. Payin status changes to CANCELLED.

How to identify partial vs full payment made by the consumer?

Typically, If a consumer tried to make a partial payment against a PENDING payin, Finmo platform tries to return the funds back to the consumer. But in some cases the sender bank or network provider may not support a return so still have to accept incoming funds.

However you can identify a partial payment vs a full payment very easily through webhooks and also via retrieving the Payin details.

You need to look at 2 fields in the PAYIN_COMPLETED webhook:

paid_amount : This is the actual amount the consumer paid against that Payin transaction
is_partially_paid : This is will be set to true if a partial payment was made.

Payin Types

Finmo supports the following Payin types i.e. the various ways Payin can be created

DIRECT_PAYIN : Payin created using Create Payin API
CHECKOUT_PAYIN: Payin created using Hosted Checkout API
VA_PAYIN: Payin created by incoming funds on an existing Virtual Account
TOPUP: Payin created by incoming funds on an existing Virtual Account created on an Organization Payin or Payout wallet.
FEES_PAYMENT: Payin created by incoming funds when you make a payment against the Finmo invoice using an existing Virtual Account on your Organization Fee wallet.