Skip to main content

Bank Card Transfer

Overview​

This interface allows merchants to transfer funds from their account to a specified bank card account.

Order Status​

StatusDescription
CREATEDOrder created
SUCCESSTransfer completed
FAILURETransfer failed
BANK_FAILBank declined

API URL​

Request​

HTTP Headers​

Attributes
  • Content-Language String
    • The language for the response message. Defaults to English.
    • Example value: en
    • Maximum length: 10
  • Content-Type String Required
    • Media type of the request body.
    • Required for operations with a request body.
    • Format: application/json
  • sign String Required
    • Request signature using private-key cryptography.
    • Ensures the payment gateway can verify the request origin.
    • Example value: RSA_SIGNATURE_BASE64_STRING
  • Partner-Id String Required
    • Unique partner identifier.
    • Example value: 200001200101
    • Maximum length: 12

HTTP Body​

  • requestTime Timestamp Required

    • Time the request was initiated.
    • Example value: 1581493898000

  • bizContent:

    Attributes

    • accountHolderType String(16) Required

      • Recipient account type: Currently only INDIVIDUAL is supported.
      • Example value: INDIVIDUAL

    • merchantOrderNo String(64) Required

      • Unique order identifier from the merchant.
      • Example value: Me23484

    • firstName String Required

      • Encrypted field. Recipient's first name. 2–35 letters after decryption
      • Required when accountHolderType is INDIVIDUAL

    • lastName String Required

      • Encrypted field. Recipient's last name. 2–35 letters after decryption
      • Required when accountHolderType is INDIVIDUAL

    • middleName String

      • Encrypted field. Recipient's middle name. 2–35 letters after decryption

    • countryCode String(2) Required

      • Recipient country code.
      • Example value: AE

    • state String(3)

      • Recipient state.
      • Required when countryCode is US.

    • zipCode String(10)

      • Recipient postal code.
      • Required when countryCode is US.

    • city String(50) Required

      • Recipient city.
      • Example value: Dubai

    • addressLine String(200) Required

      • Recipient full address.
      • Example value: 26th Floor Sky Tower

    • amount Money Required

      • Amount to transfer.
      • Example value: 12.34

    • memo String(50) Required

      • Transfer description or note.
      • Example value: Bonus

    • notifyUrl String(200)

      • URL to receive transfer status notifications.

    • senderType String(16) Required

      • Sender account type: INDIVIDUAL or CORPORATE.
      • When the sender account type is INDIVIDUAL, senderInfoRequest is required.
      • Example value: INDIVIDUAL

    • cardToken String Required

      • Token representing the recipient's card.
      • When provided, cardToken takes precedence and cardNumber, expiryMonth, and expiryYear can be omitted.

    • cardTokenMerchantId String(12)

      • Merchant ID associated with the cardToken.
      • Defaults to the requesting partnerId when omitted.

    • last4 String(4) Required

      • Last 4 digits of the card number.
      • Must match the last 4 digits of the card resolved by cardToken.

    • expiryYear String(4) Required

      • Encrypted field. Card expiration year.
      • Must be current year or later.
      • Not required when cardToken is provided.
      • Example value: 2025

    • expiryMonth String(2) Required

      • Encrypted field. Card expiration month (1–12).
      • Combined year and month must be current month or later.
      • Not required when cardToken is provided.
      • Example value: 12

    • cardNumber String(50) Required

      • Encrypted field. Card number (12–19 digits, numeric only).
      • Not required when cardToken is provided.

    • riskInfo String(255)

      • Risk information for merchant-to-card transfer scenarios in JSON format.
      • Example value: {"scene":"casino","level":"high"}

    • senderInfoRequest TransferBankCardSenderInfo

      • Sender information. It is required and must not be empty when senderType is INDIVIDUAL.

      • firstName String Required

        • Encrypted field. Sender's first name. 2–35 letters after decryption.

      • lastName String Required

        • Encrypted field. Sender's last name. 2–35 letters after decryption.

      • countryCode String(2) Required

        • Sender country code. Must be a valid ISO country code.
        • Example value: AE

      • state String(2–3)

        • Sender state.
        • Required when countryCode is US.

      • zipCode String(10)

        • Sender postal code.
        • Required when countryCode is US.

      • city String(50) Required

        • Sender city.

      • addressLine String(200) Required

        • Sender full address.

      • reference String(15) Required

        • Sender reference number. 5–15 characters, alphanumeric only.
        • Example value: 100000348329

      • sourceOfFunds Enum Required

        • Source of the transferred funds.
        • Possible values: credit, debit, prepaid, deposit_account, mobile_money_account, cash

      • dateOfBirth String

        • Sender date of birth in YYYY-MM-DD format. Format-validated when provided.
        • Example value: 1999-01-01

Request Sample​

{
  "requestTime": 1777636067475,
  "bizContent": {
    "merchantOrderNo": "T1777636061770ZMAY",
    "amount": {
      "amount": 1.00,
      "currency": "AED"
    },
    "memo": "company single pay",
    "notifyUrl": "http://yoursite.com/api/notification",
    "riskInfo": {
      "scene": "casino",
      "level": "high"
    },
    "accountHolderType": "INDIVIDUAL",
    "senderType": "INDIVIDUAL",
    "firstName": "ONVvIuLQB0FCQwCUbLtgUQWvkFTn5E7cK3Xqe/tXAtsHxUky6NKMxcrHYBvH7kVbzgngb/D39l3Jd5L/nWZM7WkmB7L4EXz3CUkGvgOcE+Y8OuT+WCE0lpM0aLoygKXJsZmiTqcRvBq5T669uW8ezEHAFPqql0EJLex9XuGD/T16JdeQDzfomiodKPNrkcEcNxt6FOGmSHrKXZlMsFk6ED+ZkdI6EQFv7/F81+U5BE+WYSVhTn/l/tcbIdqEmgYU3cY1klruz3ge4RZo55/CwNtuM8mH35aw2USwW7I9cP21r0ALvtV8xiUCrYKBmKVYOHI2riC2l4+jtsjdfPzaTg==",
    "lastName": "i/1PAWy7FUw3hQNoyR9WYxmLC5xcOiT9eS/kie4uh+/GQIin91/LTXtjRUQobgRGvA5+Mjokrrip0ak1JPnA4o9bBKmi5Aj6PX7F49/I+Nn9+iTXgFwnaHBknjPtPkVynhVaTIqCgb8JxETtLHouhVrBqMqSbAxRJ/btefg/svuE9pE6q3zbXaUSP1vODEX5NspbiWjmS62VkhbWwZxGbVh/wTWwqYPMlJMbQVrnRmibtZ3zTI9J0yRYsEkDLsz7iBC2Ye+ayGOJVZxXYHVibZSgx6Hc342303ejp6vabDfDa70413YbvQ4wDrotIwWgzEa1qBZZ54VQ6XLxMv8lww==",
    "middleName": "aPDNDh0PVMU36S1rYAQ+EwsMLz0vtkmFyP9IM0cPL/sr5r8iGO80R6VNPyrjBPHK/DAkoxYIQ5caMauVKtQO7/2qTUQAOqHhTONNS5zmqZcd0wXUTqj6lhZxi6euhQxNy5JJde1BPVm06Xs0lLfXqpjmBDpGbYRTmWEwP3tQlj/3oA1JgilMHoZY4f41cANZg1VrdFf7UneIaolLbS8buk2IthfVfErKmPI2FfQ+fSswEQ5hjVSZAOPq9ryyQf3JPZWbOfED68+z6J6VtRTbRr1IqIujxZD8uUg2EL3POEdidvShxrQPHbp4XemLpyAIItbA1fxVrs+ejDDIrRybdw==",
    "cardNumber": "KNh0ES4qzHfz6KyMopf04sNmBdZAe+2diPsCjYw8mqAmoJFlq5i8z0lI98MB2RJMTkEwdL1anLGkfxcAAjJQJAnFbLpWTQYO3EPoEy0jOmRF8L5R5RarjsKkAnZ4eajVYrSybfLYGkWSViBJVeOh3NANmHvQEVNr9UtYg9wkc67eHm0L+6DZOf0MO+XdDyEHo8eQ3+JKN8fpULATFtrIYsZ0mdFrl8lhb4OhD+ja4ZtkZfmuaxN+xjlK50aCxhEooOBPEvMhpPsyE4ETkf/pN+In/RLTsXlE4OZTyPJFxu5xliM15pCdIU+S6x/32zRBhGt+JnfupXnjk8NXgdUX2A==",
    "expiryYear": "Z1jLhLD+NWJptjDjP9YLVPyA+qyJ7OliVnNL9fTRLJNWIxaQBLzca0BIB6BHEkA1TIKZvs/0aBdgArTeJixT1OLm8hhWzghNdW0TqwcshYO6mEpIAEHWwXAmoyfRDE/P/RrUsqqsU8GSLL2s4NDQFLW95VcYL3NNNTLqfzuXieeZr3docDQOj3yPomPWNDqi2e4bH2G3s1Q9jGF5a7mMcKwlx07ePcYV1Y8sRqLN4gP8zncvaBeSrD+pcwb15nCAzA+WUNV9Bby6gdTRSLbNtwSpqySZeFSlaWNY18INusOjd98+t6l6zwrixorqZdGigCpCdB8/6RSyvYUIqcj2fQ==",
    "expiryMonth": "C99R1WEz7NxpycTX7X2IanH7J0TVGhEnrSdImJmUNLCx38+cMaMFygR5l+P2lgtK2LF/lC1FR8fK9AYPLo9GWush2SmPAvBbkUNGuzTJCmJPdWZmjG/7AeopEb1Ax2oWmvKPn0pHetxXrMBesdQtx0Ekx0kAds1D5zyXsCp8fq1/OoI+LiI1cncfkgER8d0AvyV7J2n/DWQBBuxrQ9sEhorIE5QlhcqVQCpAP/HIt0Ow7cHCmprw2wD/iYehYjQZwm/avizm8sVgDA5VnIAfqmZmLnWx7xq84WhFWEpsNEof3FNOm+Xm3TZfW74PVuhgPNNsfkQlNWQA2pD1SzBGaQ==",
    "countryCode": "AE",
    "state": "Abu",
    "city": "Dubai",
    "addressLine": "26th Floor Sky Tower",
    "senderInfoRequest": {
      "firstName": "YIQfkvSFngesF73UXWZr8ollDCAxNCutXSCgWLQrFTTatuKayT51mnShJJHmZl3r6R1Tv3fCGcPuVW/BT8uSVleOrscgNdpsfRRohptyZ4NKgNm+jCXNvb+hmESpocCg38TbwE1RNQeOz2T+b/mxOq5YdlHCLHPEdjkQz9+O3rxrzmR17u7wqu42a6w+REK29cnkpJF+o7GgyZzU7Id/wFrHK71nBE8Vr4aN5sDmXH8KK4JmHWj227OOaSokHDzhYo0JQ80VlhfkPkrPpaUP5u5nvmVWZJy+2Kn8aaKw14jrCuzTdqXUrwuLn8Z5vaGTO2B7NayPFb87i8kECdz88w==",
      "lastName": "LSBwCYeR/yKx+o3Gzh1CaesKEsCObTdWfy92xBAT7MitRnVqvwDWstMbN9YPcS24OHTtwIfS4SD555mBRIX9NRr36wlk3y0q59/cHGRiTWXXPXWHX/Vd8EEiTADwV1WDDxhok1zkIZA9hOJ29+q9gV3ubTaLXRnp0NbzkDucjLVMzO6YVzKp95ECyuquqFf+rvOrRU1b1Qe8wMWPvZJ7UnPVItdDyJM7QP45JWq78tYj8EISPXodkuo5PFeX4qcES1dcIGiRRlqzZUkoCWzQTpbt+zzFEc14atKBX9YrweiiaJBnaqauY6G/R/Zu57wuGj2T1MekSMqj6Nlh6nsmVg==",
      "countryCode": "AE",
      "state": "Abu",
      "zipCode": "123456",
      "city": "Dubai",
      "addressLine": "skytower",
      "reference": "100000348329",
      "dateOfBirth": "1999-01-01",
      "sourceOfFunds": "debit"
    }
  }
}

Response​

HTTP Headers​

Attributes

  • applyStatus String(16) Required

    • Request status result.
    • Example value: SUCCESS
    • Possible values:
      • SUCCESS: Application successful
      • FAIL: Application failed
      • ERROR: Exception occurred

  • code String(10) Required

    • Return error code.
    • Example value: 0

  • msg String(200)

    • Return message.

HTTP Body​

  • transferToBankCard TransferBankcardOrder Required
    • Complete transfer order details.

TransferBankcardOrder:

Attributes

  • requestTime Timestamp(3) Required

    • Request time passed by the merchant when placing the order.
    • Example value: 1581493898000

  • merchantOrderNo String(64) Required

    • Merchant's reference number for tracking the request.
    • Example value: S10000

  • orderNo String(32) Required

    • Botim Money's unique identification number of the order.
    • Example value: O1000

  • product String(200) Required

    • Product name of the API method used in the order.
    • Example value: Transfer Bank Card

  • status String Required

    • Status of the order.
    • Possible values: CREATED, SUCCESS, FAILURE, BANK_FAIL

  • amount Money Required

    • Amount to be transferred.

  • transferFee Money Required

    • Transfer fee.

    • Example value: 

    {
      "amount": 0,
      "currency": "AED"
    }

  • accountHolderType String(16) Required

    • Recipient account type. Currently only INDIVIDUAL is supported.
    • Example value: INDIVIDUAL

  • firstName String Required

    • Encrypted field. Recipient's first name.
    • Required when accountHolderType is INDIVIDUAL.

  • lastName String Required

    • Encrypted field. Recipient's last name.
    • Required when accountHolderType is INDIVIDUAL.

  • middleName String

    • Encrypted field. Recipient's middle name.

  • cardNumber String Required

    • Encrypted field. Card number.

  • expiryMonth String(2) Required

    • Card expiration month (1–12).
    • Example value: 09

  • expiryYear String(4) Required

    • Card expiration year.
    • Example value: 2027

  • countryCode String(2) Required

    • Recipient country code.
    • Example value: AE

  • state String(3)

    • Recipient state.
    • Example value: Abu

  • city String(50) Required

    • Recipient city.
    • Example value: Dubai

  • addressLine String(200) Required

    • Recipient full address.

  • memo String(50) Required

    • Transfer description or note.
    • Example value: Bonus

  • notifyUrl String(200)

    • URL where the merchant receives notifications.
    • Example value: http://yoursite.com/api/notification

  • failDes String(200)

    • Cause of order failure.

  • bankReference String(128)

    • Bank reference number.

  • paidTime Date Required

    • Time of deduction.

  • refundedTime Date

    • Time of refund.

  • senderInfo TransferBankCardSenderInfo

    • Sender information. If included, fields marked Required below must be provided.

    • firstName String Required

      • Encrypted field. Sender's first name.

    • lastName String Required

      • Encrypted field. Sender's last name.

    • countryCode String(2) Required

      • Sender country code.
      • Example value: AE

    • state String(3)

      • Sender state. Required when countryCode is US.
      • Example value: Abu

    • zipCode String(10)

      • Sender postal code.
      • Example value: 123456

    • city String(50) Required

      • Sender city. Required when countryCode is US.
      • Example value: Dubai

    • addressLine String(200) Required

      • Sender full address.
      • Example value: skytower

    • reference String(15) Required

      • Sender reference number.
      • Example value: 100000348329

    • sourceOfFunds Enum Required

      • Source of the transferred funds.
      • Possible values: credit, debit, prepaid, deposit_account, mobile_money_account, cash

    • dateOfBirth String

      • Sender date of birth in YYYY-MM-DD format.
      • Example value: 1999-01-01

Response Sample​

HTTP Headers​

{
    "sign": "Yv+C2lOQmfERdm5GF9b2V4Y98HmX/6CFyconeOW36AoPqcb7InRcP9E5GnvJLfMoCScuNP4FBdJ5tJpL0A7yPHUMfxARi05jFRSMG97JJazDbWTbRkNM1ZupmTubhUvxvRCgvJp1k0c5yrHph+F+++W5eYho92xnkNgd62BS27i0iDRGzGSmsaPpK7MFcdlvnbbnmDZZJ0LH6RhYiJLYKl+znllQx3jNfCRjV28o22FZ35Q43mZTsS4uAZWbZ/KfaqWoV3sN62Cjj8DSg3mD6GCGWSVbxLq58DUxAq+6GwJ7Gj0Dc9nMXP3gnFW7dodQ9AjL2iHnH6Zh1Pw2D5/ung=="
}

HTTP Body​

{
  "body": {
    "transferBankCardOrder": {
      "amount": {
        "amount": 1.0,
        "currency": "AED"
      },
      "partnerId": "200000088724",
      "notifyUrl": "http://yoursite.com/api/notification",
      "memo": "company single pay",
      "requestTime": 1777636068930,
      "transferFee": {
        "amount": 0.0,
        "currency": "AED"
      },
      "orderNo": "131777636068533842",
      "merchantOrderNo": "T1777636061770ZMAY",
      "product": "Transfer Bank Card",
      "status": "CREATED",
      "paidTime": 1777636070000,
      "accountHolderType": "INDIVIDUAL",
      "cardNumber": "b888aa5f23a817883d4d12c74044bab1ae6ee65dc8d6e11515394aba452b273b",
      "expiryMonth": "08",
      "expiryYear": "2028",
      "firstName": "46fbf700b56ded7c159e0edbe79e6d53082f48640da2806aaf238fd00c717c04",
      "lastName": "c85c2e16a566d82acc5f76f0694d3ae16c8481499e4a806aa64e424db158cddb",
      "middleName": "c6c094bc0054f9cbe34102ff49f86b3928b5ac09f3d2ac87e170d0500675921f",
      "countryCode": "AE",
      "state": "Abu",
      "city": "Dubai",
      "addressLine": "26th Floor Sky Tower",
      "senderInfo": {
        "firstName": "35e8062b71ff23f92bb6d4e881cee471a22c7d79c401685df0d312db7edb58e0",
        "lastName": "4f3ef4f55a2f52c91fc7ebe3f738beb9ceeffbede18d130f4028a084ce1c0875",
        "countryCode": "AE",
        "state": "Abu",
        "zipCode": "123456",
        "city": "Dubai",
        "addressLine": "skytower",
        "reference": "100000348329",
        "sourceOfFunds": "debit",
        "dateOfBirth": "1999-01-01"
      }
    }
  },
  "head": {
    "applyStatus": "SUCCESS",
    "code": "0",
    "msg": "SUCCESS",
    "traceCode": "587641"
  }
}

Response Codes​

CodeMessageCauseWorkaround
0SUCCESSRequest successful-
400INVALID_PARAMETERInvalid request parametersAdjust request parameters
400REQUESTTIME_TOO_EARLYRequest time is too earlyAdjust request time
400REQUESTTIME_TOO_LATERRequest time is too lateAdjust request time
402RATE_LIMIT_REJECTToo many requestsReduce request frequency
403UNAUTHORIZEDAPI not authorizedContact Botim Money
404SERVICE_NOT_AVAILABLEAPI service unavailableContact Botim Money
500SYSTEM_ERRORSystem errorContact Botim Money, retry later
504SERVICE_TIMEOUTService timeoutRetry later
601RISK_FAILRisk control validation failedAdjust business parameters
62002ORDER_FAILUREOrder has failedUse different merchant order number
62016MERCHANT_ORDER_NO_EXISTDuplicate order number with different parametersUse different order number
62026PRODUCT_IS_NOT_APPLIEDProduct not activatedApply for product access
62028ORDER_SUCCESSOrder already successfulUse different merchant order number
62029ORDER_CREATEDOrder already createdUse different merchant order number