Guides
API Reference

Direct Settlement

Suggest Edits

What is direct settlement

Direct settlement collection / disbursement is a transaction type where we handle the crypto disbursement / collection part of the transaction as well.

Basically

  • Collection direct settlement - customer sends in fiat, we send the customer crypto.
  • Disbursement direct settlement - customer sends crypto, we send the customer fiat.

Collection Request and Response

For collection the following fields should be included in the collection request

  • forceAccept - set to true
  • directSettlement - set to true
  • settlementInfo - crypto destination object 
{
  "recipient": {
    "name": "John Doe",
    "country": "Nigeria",
    "phone": "+2349092916898",
    "address": "Home Address, Sea of tranquility, Moon",
    "dob": "02/01/1997",
    "idNumber": "314159",
    "idType": "license"
  },
  "source": {
    "accountType": "bank",
    "accountNumber": "1111111111" // only needed in sandbox to simulate success 
  },
  "channelId": "af944f0c-ba70-47c7-86dc-1bad5a6ab4e4",
  "sequenceId": "53f7c7fa-f2bb-450c-8f6d-9ff0000f99",
  "amount": 50,
  "currency": "NGN",
  "country": "NG",
  "reason": "other",
  "forceAccept": true,
  "directSettlement": true,
  "settlementInfo": {
    "walletAddress": "TFtbBrsWw5DGHoKQE8VY2WzTY3VnanQ2hz", // destination address
    "cryptoCurrency": "USDT", // 
    "cryptoNetwork": "TRC20"
  }
}

{
  "currency": "NGN",
    "settlementInfo": {
      "cryptoNetwork": "TRC20",
      "cryptoLocalRate": 1617.3,
      "cryptoUSDRate": 1,
      "walletAddress": "TFtbBrsWw5DGHoKQE8VY2WzTY3VnanQ2hz", 
      "cryptoAmount": 48.36654808,
      "cryptoCurrency": "USDT"
   },
   "status": "processing",
   "networkFeeAmountUSD": 1.13, // network fee 
   "serviceFeeAmountUSD": 0.5,
   "partnerFeeAmountLocal": 0,
   "country": "NG",
   "reference": "JJ5275168",
   "recipient": {
   "country": "Nigeria",
   "address": "Home Address",
   "idType": "license",
   "phone": "+23490XXXXXXXX",
   "dob": "02/01/1997",
   "name": "John Doe",
   "idNumber": "314159"
   },
   "expiresAt": "2024-11-26T21:05:13.393Z",
   "requestSource": "api",
   "directSettlement": true,
   "refundRetry": 0,
   "id": "0a89dce0-d8d2-59a6-ab9d-1d9d8b4593e2",
   "partnerId": "9ecf5248-17e7-4a2b-b5a8-3bd58ff0fe01",
   "rate": 1617.3,
   "bankInfo": {  // bank account for deposit
     "name": "PAGA",
     "accountNumber": "4550440202",
     "accountName": "Ken Adams"
   },
   "createdAt": "2024-11-26T20:55:13.393Z",
   "forceAccept": true,
   "source": {
     "accountNumber": "1111111111",
     "accountType": "bank"
   },
   "sequenceId": "53f7c7fa-f2bb-450c-8f6d-9ff0000f7",
   "reason": "other",
   "networkFeeAmountLocal": 1833.13,
   "convertedAmount": 80865,
   "channelId": "af944f0c-ba70-47c7-86dc-1bad5a6ab4e4",
   "serviceFeeAmountLocal": 808.65,
   "updatedAt": "2024-11-26T20:55:17.487Z",
   "partnerFeeAmountUSD": 0,
   "amount": 50,
   "depositId": "a29e596a-0ae5-4386-b2a3-eacf9fc70575"
}

Disbursement Request and Response

The following fields need to be included in the disbursement request

  • directSettlement - set to true
  • forceAccept - set to true
  • settlementInfo - info for receive crypto currency and network
{
    "sender": {
        "name": "Jimothy Charlamet",
        "country": "N",
        "address": "12dsa",
        "dob": "09/03/1987",
        "email": "[email protected]",
        "idNumber": "123492992",
        "idType": "passport"
    },
    "destination": { // customer's bank account, where fiat is disbursed
        "accountName": "Héloïse D'arban",
        "accountNumber": "+26711111111",
        "accountType": "momo",
        "networkId": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb"
    },
    "channelId": "a3f3a711-c50e-4e53-b867-7d1d148cd43b",
    "sequenceId": "00f000-0000002-000000-000002710",
    "currency": "KES",
    "country": "Kenya",
    "reason": "other",
    "forceAccept": true,
    "directSettlement": true,
    "settlementInfo": {
        "cryptoCurrency": "USDT",
        "cryptoNetwork": "TRC20",
        "cryptoAmount": 20 // amount in crypto
    }
}

{
    "sender": {
        "name": "Jimothy Charlamet",
        "country": "N",
        "address": "12dsa",
        "dob": "09/03/1987",
        "email": "[email protected]",
        "idNumber": "123492992",
        "idType": "passport"
    },
    "destination": {
        "accountName": "Héloïse D'arban",
        "accountNumber": "+26711111111",
        "accountType": "momo",
        "networkId": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
        "networkName": "Mobile Wallet (M-PESA)"
    },
    "channelId": "a3f3a711-c50e-4e53-b867-7d1d148cd43b",
    "sequenceId": "00f000-0000002-000000-000002710",
    "currency": "KES",
    "country": "KE",
    "reason": "other",
    "forceAccept": true,
    "directSettlement": true,
    "settlementInfo": {
        "cryptoCurrency": "USDT",
        "cryptoNetwork": "TRC20",
        "cryptoAmount": 20,
        "walletAddress": "TCM1FNSZaKQhodGEfPfyZ7FdRT9vrMD677", // address for crypto receive
        "cryptoUSDRate": 1,
        "expiresAt": "2024-12-09T19:07:25.319Z"
    },
    "partnerId": "9ecf5248-17e7-4a2b-b5a8-3bd58ff0fe01",
    "requestSource": "api",
    "id": "d9f031a8-f639-5a2a-b997-adbf8dc3a5e8",
    "attempt": 1,
    "status": "created",
    "convertedAmount": 1165,
    "rate": 116.5,
    "expiresAt": "2024-12-09T16:17:25.319Z",
    "createdAt": "2024-12-09T16:07:25.319Z",
    "updatedAt": "2024-12-09T16:07:25.319Z"
}

{
    "sender": {
        "name": "Jimothy Charlamet",
        "country": "N",
        "address": "12dsa",
        "dob": "09/03/1987",
        "email": "[email protected]",
        "idNumber": "123492992",
        "idType": "passport"
    },
    "destination": { // customer's bank account, where fiat is disbursed
        "accountName": "Héloïse D'arban",
        "accountNumber": "+26711111111",
        "accountType": "momo",
        "networkId": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb"
    },
    "channelId": "a3f3a711-c50e-4e53-b867-7d1d148cd43b",
    "sequenceId": "00f000-0000002-000000-000002710",
    "amount": 10,
    "currency": "KES",
    "country": "Kenya",
    "reason": "other",
    "forceAccept": true,
    "directSettlement": true,
    "settlementInfo": {
        "cryptoCurrency": "BTC",
        "cryptoNetwork": "LIGHTNING",
        "cryptoAmount": 0.0002 // amount in BTC

    }
}

{
    "sender": {
        "name": "Jimothy Charlamet",
        "country": "N",
        "address": "12dsa",
        "dob": "09/03/1987",
        "email": "[email protected]",
        "idNumber": "123492992",
        "idType": "passport"
    },
    "destination": {
        "accountName": "Héloïse D'arban",
        "accountNumber": "+26711111111",
        "accountType": "momo",
        "networkId": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
        "networkName": "Mobile Wallet (M-PESA)"
    },
    "channelId": "a3f3a711-c50e-4e53-b867-7d1d148cd43b",
    "sequenceId": "00f000-0000002-000000-000002710",
    "amount": 10,
    "currency": "KES",
    "country": "KE",
    "reason": "other",
    "forceAccept": true,
    "directSettlement": true,
    "settlementInfo": {
        "cryptoCurrency": "BTC",
        "cryptoNetwork": "LIGHTNING",
        "cryptoAmount": 0.0002 // amount in BTC
        "cryptoUSDRate": 1,
        "lnInvoice": "lntbs580u1pn4wyu0pp505xr4r6080nsh6tjdu9v9j7u2fdypzxr9lz2cxanevnnltvypsjsdzvt9p473z92p84xj25tu6nsve5xpjnwv3dv93njvpdxsex2vfd8p3rzvpdxp3xxctpxdjrwdp38q6qcqzzsxqyz5vqsp5g8qx2jqrwd96sgchvegm0u38gke5n8rqz6q4ccmzj3zhuh2zgqkq9qxpqysgqcsw64ec5stffa8v2an4799lf5hzwe7qughlgcpurz8789ne36lt8dngcyrtyacz3tlx7j26n9lw8c9un6st6t2qx52ut0yy63lgljksqs4fmdq"
        "expiresAt": "2024-12-09T19:07:25.319Z"
    },
    "partnerId": "9ecf5248-17e7-4a2b-b5a8-3bd58ff0fe01",
    "requestSource": "api",
    "id": "d9f031a8-f639-5a2a-b997-adbf8dc3a5e8",
    "attempt": 1,
    "status": "created",
    "convertedAmount": 1165,
    "rate": 116.5,
    "expiresAt": "2024-12-09T16:17:25.319Z",
    "createdAt": "2024-12-09T16:07:25.319Z",
    "updatedAt": "2024-12-09T16:07:25.319Z"
}

Events

Direct settlement transactions events follow the widget events with the exception of PENDING_KYC event.

Updated 4 months ago