Transfer Validation

This interface provides merchants with the ability to validate transfers to Botim Money user before executing the transfer.

API URL

• UAT: https://uat.test2pay.com/sgs/api/transfer/transferToWalletValidation
• Production: https://api.payby.com/sgs/api/transfer/transferToWalletValidation

Request

Http Header

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

Request time of the order. If the request time is more than 15 minutes away from the current time, the request will be rejected. This parameter is used to prevent repeated requests for orders that should have been cancelled due to timeouts.

Example value: 1581493898000

bizContent Object

Attributes

• amount Money Required

  • The amount of AED to transfer. Currency must be AED.

  • Type of Limit:

    Limit Type	Amount
    Maximum per transaction	AED 10,000

  Note: If the beneficiary's account balance + transfer amount exceeds AED 20,000, the transfer will fail.

• merchantOrderNo String

  • The merchant's reference number of the request. Used to track every request.
  • If not provided, the system will generate one randomly.
  • Example value: M965739182419
  • Maximum length: 64

• notifyUrl String

  • URL to receive asynchronous notifications of order status updates.
  • Example value: https://www.yoursite.com
  • Maximum length: 32

• memo String

  • Description of the transfer.
  • Maximum length: 32

• beneficiaryIdentityType String Required

  • The fund can be transferred to the beneficiary through mobile phone number or Botim Money member ID.
  • Possible values:
    • PHONE_NO: Transfer through mobile phone number
    • MEMBER_ID: Transfer through Botim Money member ID

• beneficiaryIdentity String Required

  • Value to be passed after selecting the beneficiary identity type.
  • Should be encrypted using SHA-256.
  • Example values:
    • +971-585812345 (for PHONE_NO)
    • 100006514321 (for MEMBER_ID)
  • Maximum length: 200

• beneficiaryFullName String

  • If provided, Botim Money will verify it against the beneficiary's KYC information.
  • If not provided, no verification is performed.
  • Should be encrypted using SHA-256.
  • Maximum length: 100

• accountType String

  • Type of account for the transfer.
  • Possible values:
    • BASIC: Default account type
    • WPS_SALARY: WPS salary account type
  • Default value: BASIC

Request Sample

//Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000429066",
    "sign": "aMs582GhLeRv4fL3xqw7nN4dlzWS+ZVzdsNXT6rKwPpj7qOM4Y7qZBP3Yl6HogILy4IyX1tp8M7D92rK37hUgJg814odd1INIuy4l+KTRPA1Y3F8y0hVGXak0ddeVcOM3XNN+YEhvPClBx4EpmfWVqY3A2qNJTo3ugwr6uZiVGA38OjHRLZthGa+5nea0DtLaZYQnOGWaCI6fPIBZ7qr9HTiVkIsAp3N4m4cHR+3Rvpdbzu2TZoScA358D9wGmF5UOkbHCjwNV03I3O8HzaKUqMe4jnXZ+lJ0TMmxmqLrcMyMztJjZMQB9S4lXMW2+TqMrdNgLQv3GLiQ9IFvhUVEg=="
}

//Http Body
{
    "requestTime": 1581405399656,
    "bizContent": {
        "amount": {
            "amount": 1,
            "currency": "AED"
        },
        "beneficiaryIdentity": "P3376529",
        "beneficiaryIdentityType": "MEMBER_ID",
        "memo": "fundout test",
        "merchantOrderNo": "53d10fb743f2488dd4c746341a1c",
        "notifyUrl": "https://www.yoursite.com"
    }
}

Response

Http Header

sign String Required

When Botim Money sends response, Botim Money will use its own private key to sign the message, and the merchant uses Botim Money's public key to verify the signature. If the verification is passed, it proves that the response was sent by Botim Money and not faked by others.

Http Body

head

Attributes

• applyStatus Enum Required

  • The result of the request. Possible values:
    • SUCCESS: Application successful.
    • FAIL: Application failed. Check the code and msg for the exact reason.
    • ERROR: Application error. Signature verification failed. Ensure the private key used for the signature and the public key uploaded on the Botim Money portal are a valid key pair.

• code String Required

  • Response code.
  • Example value: 0
  • Maximum length: 10

• msg String

  • Description of the response code.
  • Maximum length: 200

• traceCode String

  • Internal code for locating the error.

body

Notice

Body is returned only when applystatus = success, and code = 0. If applystatus = error or failed; or applystatus = success, code !=0 , that indicates an error. Please check errors and try again.

• validateOrder Object

  Attributes

  • amount ExternalMoney Required

  ​ The transfer amount.

  • beneficiaryIdentity String Required

  ​ The identity of the beneficiary. This value is encrypted.

  • beneficiaryIdentityType Enum Required

  ​ The identity type of the beneficiary.

  ​ Valid values: PHONE_NO, MEMBER_ID

  • requestTime Long Required

  ​ Request time of the validation.

  • status String Required

  ​ The validation status.

Response Sample

// Http Header
{
    "sign": "nDdClX1tAyV3qcX/Epay6AXFNRGSsWd8ysWO9SgwPrNTetSePLA9C39mGp6qRbjJeqXLEnYLwSkBu5eKdtyVX3tflGLiV2kvRjVfYpTCjXdVL2Pcnv2w+ghjHe2jL988iklk7q5AjAgdtXNphpHcTes9pk6W3bVCbvijH6at0fExUtZ91L1LrnPGELT1IJm/lFW3w4KLh0Gxs7FzDPI9RDfUemObNlRzV8kCtkWahwPgs/hBnS69GyYDKN7ihQX2UiLuP239wl6IA+VG/ZZKHPhLs8bbuOS+LKWORIp6jRt+JsAx7c/Ot1RNyOnHKxPRKJ8bVTohEp39yUz/HwG8oA=="
}

// Http Body
{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS"
    },
    "body": {
        "validateOrder": {
            "amount": {
                "amount": 1.00,
                "currency": "AED"
            },
            "beneficiaryIdentity": "7b32e17903341eb4759f6b50711d45ff157db95361a16e2cacc608fbcce4deb1",
            "beneficiaryIdentityType": "MEMBER_ID",
            "requestTime": 1770204118747,
            "status": "SUCCESS"
        }
    }
}

Response Codes

Code	Message	Cause	Workaround
0	SUCCESS	Success
400	INVALID_PARAMETER	Invalid parameter	Adjust request parameters
400	REQUESTTIME_TOO_EARLY	Request time is too far in the past	Adjust request time
400	REQUESTTIME_TOO_LATER	Request time is too far in the future	Adjust request time
402	RATE_LIMIT_REJECT	Too many requests	Reduce request frequency
403	UNAUTHORIZED	API not authorized	Contact Botim Money
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact Botim Money
500	SYSTEM_ERROR	System error	Contact Botim Money and retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
62026	PRODUCT_IS_NOT_APPLIED	Product not applied for	Apply for the product
62114	WALLET_CANNOT_RECEIVE_FUNDS	Recipient KYC expired, amount limit exceeded, recipient status abnormal	Contact Botim Money
62115	WALLET_DOES_NOT_EXIST	Recipient KYC invalid	Contact Botim Money