API ReferenceGet API keysGet Integration SupportBlog

Same Currency Payouts

Suggest Edits

Local payouts, often known as same currency transfers, are transfers of funds from one account to another denominated in the same currency. For example, transferring money from one EURO account to another EURO account. You can make these transfers using either the portal or via API. This feature is available for both bank accounts and mobile money transfers.

📘

To learn how to make local transfers using the Fincra API, you must read and understand the sections below.

Note

  • All transfers have a timeframe by which they settle in the receiver's account; please review the payment scheme section to ascertain the settlement time.

How to make a local transfer using Fincra API

The following steps need to be taken in order to process payments to a local account:

1 - Topup

You can fund your account by making deposits into your account or by requesting a manual top-up. You can create a virtual account to fund your wallet/account using our virtual account creation endpoints.

Note: To test transactions, you can fund your sandbox account. For more information, please see the test section

📘

For more details on virtual account creation and funding please read the following sections :


We will send a notification to your webhook url whenever your wallet is funded . 
{
  "event": "collection.successful",
  "data": {
    "business": "61602d2950139ad72e619a91",
    "virtualAccount": "61dc08222d2cc64836c5a591",
    "sourceCurrency": "GBP",
    "destinationCurrency": "GBP",
    "sourceAmount": 200000,
    "destinationAmount": 200000,
    "amountReceived": 100,
    "fee": 100,
    "customerName": " Ultimate Global Ventures",
    "settlementDestination": "wallet",
    "status": "successful",
    "initiatedAt": "2022-03-28T07:15:19.402Z",
    "createdAt": "2022-03-28T07:15:19.403Z",
    "updatedAt": "2022-03-28T07:15:19.403Z",
    "reference": "f9121b33-7e15-409e-b588-36c6146d5823"
  }
}

2 - Verify the account number

You must collect the customer's account information and ensure that it is valid before sending money. This is to avoid transferring money to an account that is wrong or inaccurate. Please visit the Verify Account Number API to learn how to verify account numbers.

3 - Request payout

Kindly ensure you fill out all of the necessary fields in order for your payment to be processed. If the wrong payload is sent, the transaction will fail and you will receive a failed response.

  • Some currencies require a payment scheme to be processed. Lists of the currencies can be found on the payment scheme page.
  • Payment status is returned after a request is received, and it can be successful, processing, or failed. Please see our payment status page for additional information.here
  • Only payouts with the explicit status failed should be retried. If you receive a Timeout Message it doesn't mean the transaction has failed. Kindly re-query using this link before you retry.
  • bankCode Lists can be found here
  • We advise that you add a customerReference to your payload to avoid sending duplicate transactions.
{
    "business" : "{{businessId}}",
    "sourceCurrency": "GBP",
    "destinationCurrency": "GBP",
    "amount": 20000,
    "description": "i want to pay my vendor",
    "paymentDestination": "bank_account",
    "customerReference": "b67vfv",
    "beneficiary": {
        "firstName": "john",
        "lastName": "doe",
        "accountHolderName": "john doe",
        "phone": "0803443433",
        "accountNumber": "0124775489",
        "type": "corporate",
        "email": "[email protected]",
        "bankCode": "90909",
        "country": "GB",
        "sortCode": "908282"
    },
    "paymentScheme": "fps"
}

{
    "success": true,
    "message": "Payout processed successfully",
    "data": {
        "id": 14483,
        "reference": "cb2c581b-58a5-4037-be65-1375631a51db",
        "customerReference": null, // this would be returned as your customer reference
      if it is sent in the request payload
        "status": "processing"
    }
}

4- Receive and validate webhook notification

Listen for webhook events. We will send a notification to your webhook URL that indicates the payout or payment order status. Read our guide on securing and validating the webhook notification on your end. Please read the payout webhook page for further details on the webhook structure and body.

{
    "event": "payout.successful",
    "data": {
        "id": 14380,
        "amountCharged": 212000,
        "amountReceived": 500,
        "recipient": {
            "name": "Hassan Sarz",
            "accountNumber": "0124775489",
            "type": "individual",
            "email": "[email protected]"
        },
        "fee": 150,
        "rate": 0.0019,
        "paymentScheme": "fps",
        "paymentDestination": "bank_account",
        "sourceCurrency": "GBP",
        "destinationCurrency": "GBP",
        "status": "successful",
        "createdAt": "2022-04-02T21:23:44.000Z",
        "updatedAt": "2022-04-02T21:23:50.000Z",
        "reference": "bf2eb02e-39fe-490a-b933-63f8c4d42125",
        "reason": "Payout was successful",
        "traceId": null,
        "valuedAt": "2022-04-03T21:23:50.000Z"
    }
}

import crypto from "crypto";

const encryptedData =  crypto
      .createHmac("SHA512", merchantWebhookSecretKey)
      .update(JSON.stringify(payload)) 
      .digest("hex");
const signatureFromWebhook = req.headers['signature'];

if(encryptedData === signatureFromWebhook) {
  console.log("process");
}
else {
  console.log("discard");
}

5 - Verify payment

It is critical that you confirm the transaction using your customerReference. Just because the webhook URL was visited doesn't prove that the transaction was successful or incase the webhook notification fails to hit your server you can confirm the payout by using the fetch a customer reference endpoint

Updated 3 months ago