Transfer

This interface provides merchants with the ability to transfer funds to the PayBy user account (Account registered with mobile phone number in PayBy or Botim APP).

API URL

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

Request

Http Header

Attributes

• Content-Language String

  • Language in which the response message will be used.
  • Currently, only English is supported.
  • 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/<format> (e.g., application/json)
  • Example value: application/json

• sign String Required

  • Request signature using private-key cryptography.
  • Ensures the payment gateway can verify the request origin.

• Partner-Id String Required

  • Merchant ID of your account.
  • 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

• merchantOrderNo String Required

  • The merchant's reference number of the request. Used to track every request.
  • Example value: M965739182419
  • Maximum length: 64

• beneficiaryIdentityType String Required

  • The fund can be transferred to the beneficiary through mobile phone number or PayBy member ID.
  • Possible values:
    • PHONE_NO: Transfer through mobile phone number
    • MEMBER_ID: Transfer through PayBy member ID
  • Maximum length: 20

• 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: 20

• beneficiaryFullName String

  • If provided, PayBy 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

• 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.

• memo String Required

  • Description of the transfer.
  • Maximum length: 200

• notifyUrl String

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

Request Sample

// Http Header
{
    "Content-Language": "en",
    "Content-Type": "application/json",
    "Partner-Id": "200000018132",
    "sign": "ODOK+d0os7q0FTWNKGTr6Yt3FlO6alfvIp+IhHfudxQZnAwU5FiTWvFVqgthcsvmIR5uYpcg8PT+ZMpaGnsyicmIDfutmUOh1qVwHddkWeUJr0/Mz8kZu01nyaBOaK3Onc6eR/oUnaVRnkelJIkY1T64+DWiihzcLHgsjIThpeYay/mEf8hajKlg2ciXyWpQiA1BOPA7VwQRlBArOA0FTMjJU02uWVj4eqHeBa4lED/p5hJGfSwmSWKMZ1QjqeJzFk1mpTyVLjPZLVltSxPsj/WSpRPXrVE9qKJxekiDVgalhtqB+/LKSMx4+Bb9z0zp2u8II3oTtaPGwwRtylyxdA=="
}

// Http Body
{
    "bizContent": {
        "amount": {
            "amount": 1.21,
            "currency": "AED"
        },
        "beneficiaryFullName": "SgsiXi2T//eEymXADGbK7o0EE9wmCTQxi4gLNp7y1JYTW0PbGbEmYk2rmsLc56kSOMbgAGUPf0Na0qs3uPwwhyfGSrHJsxNB8J2wBhcvBm8eSX2BjS45qT/hI8pW2KhpprWVXMmwCCh7NX36Imp0WcsDg8o4EHKBKgg1GLBOBkCh7tHAEDMPhwOllsGYioPb9eKmXHoRlgBAosD+wgEayvLS2LgGb18gGMM3w4ujwLKllQ2g2cr3HiCzvEcaroiBJ/1XSjGQ5rJNVomLpXec05Mr9Ql2oszh8uGbayCL3M4EhppXsA0KTYkHhxmZ5yM7pWmpHQH2tRtxE8EM5j7o3g==",
        "beneficiaryIdentity": "KUsQ3GNU/1p11hVHNljTQehKtjqhIvtED1aOcWuVqY2puGqiSs8ulAN51xLzaQ9mPcWnGry0Sqdun+mGdcroTOGZBP1zOXF3unps29JO7rkYCQK7pqAcelTV0QIi122QLqXmVpEKAcfT/zLRhQdxA9qf+XyOc4LfJTLVv02z+BRK02YvV+pwszbLzmqDJiffs0ffa32zqVDJFgM+sJgRYowW4v3QKvplpwjlEwjB6vnQO9mCBuLX/zz6q0wIQjjPiHLalUQRwOUzhXQU4aRYs7UBhNdy8wcn0dQNeWfZw1Pd30kwVAeDcPis48UsPET49wmDr/PDOdbFEqBPCLHxkA==",
        "beneficiaryIdentityType": "PHONE_NO",
        "memo": "Your memo",
        "merchantOrderNo": "M021482754853",
        "notifyUrl": "http://www.yoursite.com"
    },
    "requestTime": 1585142886252
}

Response

Http Header

sign String Required

When PayBy sends response, PayBy will use its own private key to sign the message, and the merchant uses PayBy 's public key to verify the signature. If the verification is passed, it proves that the response was sent by PayBy 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 PayBy 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.

• transferOrder Object

  Attributes

  • requestTime Timestamp Required

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

  • merchantOrderNo String Required

    • The merchant's reference number of the request. Used to track every request.
    • Example value: M965739182419
    • Maximum length: 64

  • orderNo String Required

    • The PayBy's unique identification number of the order.
    • Example value: 131658300517875854

  • product String Required

    • The product name of the API method used in the order. Used for PayBy internal classification.
    • Maximum length: 100

  • status Enum Required

    • Possible values:
      • CREATED: The order has been created.
      • SUCCESS: The transfer completed.
      • FAILURE: The order has been cancelled or expired.

  • paymentInfo Object

    • payerFeeAmount Money Required
      • Fee that the payer needs to pay in this transfer.
    • arrivalTime Timestamp Required
      • Estimated time of fund arrival (not actual arrival time).
      • Example value: 1581493898000

  • beneficiaryIdentityType String Required

    • Method used to identify the beneficiary.
    • Possible values:
      • PHONE_NO: Transfer through mobile phone number
      • MEMBER_ID: Transfer through PayBy member ID
    • Maximum length: 20

  • beneficiaryIdentity String Required

    • Value passed based on the selected identity type.
    • Should be encrypted using SHA-256.
    • Example values:
      • +971-585812345 (for PHONE_NO)
      • 100006514321 (for MEMBER_ID)
    • Maximum length: 20

  • beneficiaryFullName String

    • If provided, PayBy verifies it against the beneficiary's KYC info.
    • If not provided, no verification is performed.
    • Should be encrypted using SHA-256.
    • Maximum length: 100

  • memo String Required

    • Description of the transfer.
    • Maximum length: 128

  • notifyUrl String

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

  • failCode String

    • Code identifying the reason for failure (if status is FAILURE).
    • Example value: 504

  • failDes String

    • Description of the failure reason (if status is FAILURE).
    • Example value: SERVICE_TIMEOUT

Response Sample

// Http Header
{
    "sign": "WzVWAdy4Z+tMhgqtuxle+R9P3R3Yn5uMeICj8jIFTBpfReJLviZY9Z5tecWpjXM8ESaxkhn052hE1TSYXncCzB0A/lFwwbP/ylJTw5y1kvhN8BMyO55kl7y1MRCwhNc5VrEFx96SJN1MvrpbzIxuLkf12GXoqXVO3VG9eKv+iErfPlEJ/7iYcjn7EI7s5Dk0iZ9jVvlK3CxSuJQkUmVz0UGHJBjd/912z54YjxAOdlxRmT4In9L2UXQZppihj79wf2xaH3Z1Pde3K4O1quFMbRXsHWvixIpsMcrfkOUoribXFo7e5+fMbEsIGA3t1EJNw7nKavmb3IrkP9CrW3Hfnw=="
}

// Http Body
{
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "1127"
    },
    "body": {
        "transferOrder": {
            "amount": {
                "amount": 1.21,
                "currency": "AED"
            },
            "beneficiaryFullName": "5a0d9e4fd01a40ff3ab89dfde84c2253b5ea07c4ba8b4e5f25b81df3b73b9db0",
            "beneficiaryIdentity": "a25c5bff2fabf6bccf8ff13a940f5d05d3927c1501373ac6fa129d4fa688417c",
            "beneficiaryIdentityType": "PHONE_NO",
            "memo": "company single pay",
            "merchantOrderNo": "M021482754853",
            "notifyUrl": "http://qa.test2pay.com/api/notification",
            "orderNo": "911585142879004849",
            "paymentInfo": {
                "arrivalTime": 1585142880000,
                "payerFeeAmount": {
                    "amount": 0,
                    "currency": "AED"
                }
            },
            "product": "Transfer",
            "requestTime": 1585142886252,
            "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 PayBy
404	SERVICE_NOT_AVAILABLE	API service unavailable	Contact PayBy
500	SYSTEM_ERROR	System error	Contact PayBy and retry later
504	SERVICE_TIMEOUT	Service timeout	Retry later
601	RISK_FAIL	Risk control validation failed	Adjust business logic
62002	ORDER_FAILURE	Order has failed	Adjust merchant order number
62016	MERCHANT_ORDER_NO_EXIST	Duplicate order number with different business parameters	Adjust order number
62020	PAYERMID_PAYEEMID_ARE_SAME	Payer and payee are the same	Adjust payer or payee
62023	NAME_NOT_MATCH	Payee name does not match	Correct the payee name
62026	PRODUCT_IS_NOT_APPLIED	Product not applied for	Apply for the product
62027	BENEFICIARY_NOT_EXIST	Payee does not exist	Adjust the payee
62028	ORDER_SUCCESS	Order has already succeeded	Adjust merchant order number
62029	ORDER_CREATED	Order has already been created	Adjust merchant order number