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​

  • Staging Environment: https://uat.test2pay.com/sgs/api/transfer/placeTransferToBankCard
  • Production Environment: https://api.payby.com/sgs/api/transfer/placeTransferToBankCard

Request​

HTTP Headers​

Attributes

  • Content-Language String

    • The language in which the response message will be used, currently only English is supported.
    • Example value: en
    • Maximum length: 10

  • Content-Type String Required

    • The media type. Required for operations with a request body. The value is application/<format>, where format is json.
    • Example value: application/json

  • sign String Required

    Requests should be signed using private-key cryptography. This allows the payment gateway to verify that an incoming request is really from your application.

  • Partner-Id String Required

    • The merchant id of your account.
    • Example value: 200001200101
    • Maximum length: 12

HTTP Body​

  • Request Time (requestTime)

    • Required: Yes
    • Type: Timestamp (milliseconds, 3-digit precision)
    • Example: 1581493898000
    • Description: Time the request was initiated.

  • Business Content (bizContent)

    Attributes

    • Account Holder Type

      • Parameter Name: accountHolderType
      • Required: Yes
      • Type: String(16)
      • Example: INDIVIDUAL
      • Description: Account holder type: INDIVIDUAL or CORPORATE

    • Merchant Order Number

      • Parameter Name: merchantOrderNo
      • Required: Yes
      • Type: String(64)
      • Example: Me23484
      • Description: Unique order identifier from merchant

    • First Name

      • Parameter Name: firstName
      • Required: No
      • Type: String(50)
      • Example: -
      • Description: Encrypted field. Account holder's first name. Required when accountHolderType is INDIVIDUAL

    • Last Name

      • Parameter Name: lastName
      • Required: No
      • Type: String(50)
      • Example: -
      • Description: Encrypted field. Account holder's last name. Required when accountHolderType is INDIVIDUAL

    • Middle Name

      • Parameter Name: middleName
      • Required: No
      • Type: String(50)
      • Example: -
      • Description: Encrypted field. Account holder's middle name

    • Company Name

      • Parameter Name: companyName
      • Required: No
      • Type: String(50)
      • Example: Liwa Street off Khaliffa Street
      • Description: Encrypted field. Company name. Required when accountHolderType is CORPORATE. Must be a valid legal name. Cannot be a single character, all numeric, or all punctuation

    • Transfer Amount

      • Parameter Name: amount
      • Required: Yes
      • Type: Money
      • Example: 12.34
      • Description: Amount to transfer

    • Payment Memo

      • Parameter Name: memo
      • Required: No
      • Type: String(50)
      • Example: Bonus
      • Description: Transfer description or note

    • Notification URL

      • Parameter Name: notifyUrl
      • Required: No
      • Type: String(200)
      • Example: -
      • Description: URL to receive transfer status notifications

    • Expiry Year

      • Parameter Name: expiryYear
      • Required: Yes
      • Type: String(4)
      • Example: 2025
      • Description: Encrypted field. Card expiration year. Must be current year or later

    • Expiry Month

      • Parameter Name: expiryMonth
      • Required: Yes
      • Type: String(2)
      • Example: 12
      • Description: Encrypted field. Card expiration month (1–12). Combined year and month must be current month or later

    • Card Number

      • Parameter Name: cardNumber
      • Required: Yes
      • Type: String(50)
      • Example: -
      • Description: Encrypted field. Card number (12–19 digits, numeric only)

Request Sample​

{
    "bizContent": {
        "accountHolderType": "INDIVIDUAL",
        "amount": {
            "amount": 0.1,
            "currency": "AED"
        },
        "cardNumber": "aJwgWWe27+/d1e5B8jOhcKdW+cfMteX4mNwmBPvYGWDcXWuMWHKxwdQ89L0p6mij4Bu1xzwLbYzj/4Ou/hmwQrQ26/thcw4Ya1cDlPDu0EDjIMHdOk0INeOv4pueJohEzVkG3RpJdFadjKkgQwuhZmdyIX7b7QhDVegMrf18WzFcDdkTS7UA8/oQ96+ybzSx7uXWsN4xaWFBLnv0bJEYDFxgwSiqJD2EiqUtMTy4iEqXRE5kzlRZfA17jzXk4cCZ1nLrTnLIvivoCWFmw4A36e0ELZ5Jn506lFm5rZnd2aMWJN7OPCR6L4IA+7K5jHlN7QWdPQtNJBrSVOu0/3uujA==",
        "expiryMonth": "S9jFGF1bHU0nOKfLPGDy+euUn2IJVv7v/qiSF2P6GaD8eFLcKs+cJ6D9ou6T60xPA39UyNRnSwBosqbnh5eCD0Rw+jQmTFr72qeqXSqkXFFg/PNIc30VP3l1IyEzJhk4XJ0GQS09kZzs6CEFhb23BWhsSpuWGYba/BOYombxGhaA5td249ZI1G1VbTo5rIxPQjpghJhO9n/iPI0T2dpXE3RuJNeoxOCo2Iz4nhYvmazGuNtncoq2aQcng1Kf6BWb/LmoW2Xz2e3k87YAOcrov+7cm3vh6Af/Wrpk1tNPtN9dAeIYK4rK8gxWHYvn45YFF6HMaZsnFphJ3iDsUca/rg==",
        "expiryYear": "MK858D0uyjePVnBrRGO3qmiLcXLxxrzcdWZjoCqgozrWkzmCcVX3ncUi9RsZwlbTAJIPI0FsXrF9o40Kt7y3SwyjpnGD2uqvv2KkW+ntzGDCUN6jmv/t7QHFEvN5xTZVsf4sA8IMLae6zVprGfYbUjyvZrje2RFATuexZ5kKdesn7Sbzf9Uo1yKCysGtAe2wRQ4EzsXYPqttnl2mWOJ7vlxbTeMiWPCbONvDvhCRN8XhhPq0gJjLhi2xnMuIKHNe7xdZ0XqpGO81MKWqz4Xd5Z97Glsb9Qpa4G3+t6DyzGRJz9v2b8fuJw7D71w1WQDa1mdEhU5c1iwp1jXIZ2Qxhg==",
        "firstName": "HYtBz0aDVZ1GCzyov+B+OViYJ5pQg8B64RNwaxdPMqeTpY3PY4pAzsUHJD8+0SNKI5JF74lopEYIJLxCCiC5cUAJZayKSWMKis7N6y6vAi6s3/WVGg7tS2DJsE/LnKiYAkFkoBDfDhiIVTaBD38ubDT9X3BSPP1fCR/6+m5MyQpQEGRFdan/saF6h9vbdMBEW1N3BCKWvWOREy7lesJlQEg2kMIiaePWilHdzS+qiQGyiXiNze+pKZaamReX2RdJPcF/9rs1KVeCifF+aCejX81f1n8WnlywLIAlUKroF04YNAoPxSotmcwlfvBmHZP2Y+xbn1mJC8GkngOB1IcHvw==",
        "lastName": "FKCYj94zTP/mhGxlqF5SNAwYAx4kVGPgIHi4KdzQ+qmi2ND9iBPvQ5yCygCyxPlwpOdaDjb4zgF+fP6PjIwmFr+284opZVHgMQLCfiX0NRqFXNk6cjIpEmVRFQW5hysATEkZ5bA5slb7WzJACwuuTi/a3gzAsDxwHOdomPl67d1SGypb1nD7DCChGTyn/492diQwIZGeXBewywlyb5NfU/f2f68lMQA82C5eIEmOvM8iLSVjnMARW92BKuTdjhYW6JVJHuUdSG91A1X+GCap5SUklO0LYaXE/lOi+bPxg/KXzARhw4JEpIexV/6IP5hJv1LAq3KjCqo7tjpl6TJ6Gw==",
        "memo": "Bonus",
        "merchantOrderNo": "7a5b47a4-1824-4a4d-b581-9b0ebd5dd436",
        "middleName": "XAvhTN+7oWSj34hxLf6vQsoiPlFn5ysiAAXDasyxTO6w8BearyGSZfnQajtYO2cNSHgmFjXeJbJ7e+YiB5GsWHeVAU0D4tihJ3Yv1VwOoeataGwiBd/mnJ6m/8wK5LWhTBY18Vr5zpjVHTvheH3dMW7t6LucJ/dynKVx08DD0S+YkW+kakICDzCkZYQCXPhuPlMlQNjxTCL2maUSVj2VjzohY7ErRJAy8JHygv8XF0LoE57F3dauoBV9y/hnkuhI/WrxV63wtDtrh/gsFkJ04S/mSiYdzAEOiXkml37Qa5xr0qeBu6XgO5PWo3S7HJCLbe5YO71klDypccmEIxuylA==",
        "notifyUrl": "http://yoursite.com/api/notification"
    },
    "requestTime": 1741917446102
}

Response​

HTTP Headers​

Attributes

  • Request Status

    • Variable Name: applyStatus
    • Required: Yes
    • Type: String(16)
    • Example: SUCCESS
    • Description:
      • SUCCESS – Application successful
      • FAIL – Application failed
      • ERROR – Exception occurred

  • Return Error Code

    • Variable Name: code
    • Required: Yes
    • Type: String(10)
    • Example: 0
    • Description: Return code

  • Return Message

    • Variable Name: msg
    • Required: No
    • Type: String(200)
    • Example: -
    • Description: Return message

HTTP Body​

Order Information

  • Parameter Name: transferBankCardOrder
  • Required: Required
  • Type: TransferBankCardOrder
  • Description: Complete transfer order details

TransferBankCardOrder

Attributes

TransferBankCardOrder

  • Request Time (requestTime)

    • Required: Yes
    • Type: Timestamp(3)
    • Example: 1581493898000

  • Merchant Order Number (merchantOrderNo)

    • Required: Yes
    • Type: String(64)
    • Example: S10000

  • PayBy Order Number (orderNo)

    • Required: Yes
    • Type: String(32)
    • Example: O1000

  • Product Name (product)

    • Required: Yes
    • Type: String(200)
    • Example: Transfer Bank Card

  • Order Status (status)

    • Required: Yes
    • Type: String
    • Example: CREATED, SUCCESS, FAILURE, BANK_FAIL
    • Description: The status of order

  • Amount (amount)

    • Required: Yes
    • Type: Money

  • Account Holder Type (accountHolderType)

    • Required: Yes
    • Type: String(16)
    • Example: INDIVIDUAL
    • Description: INDIVIDUAL or CORPORATE

  • First Name (firstName)

    • Required: Optional
    • Type: String(200)
    • Description: SHA256 of original text, required if INDIVIDUAL

  • Last Name (lastName)

    • Required: Optional
    • Type: String(200)
    • Description: SHA256 of original text, required if INDIVIDUAL

  • Middle Name (middleName)

    • Required: Optional
    • Type: String(200)
    • Description: SHA256 of original text

  • Company Name (companyName)

    • Required: Optional
    • Type: String(200)
    • Description: SHA256 of original text, required if CORPORATE

  • Card Number (cardNumber)

    • Required: Yes
    • Type: String(64)
    • Description: SHA256 of original text

  • Expiry Month (expiryMonth)

    • Required: Yes
    • Type: String(2)
    • Example: 09
    • Description: The card's expiration month of the expiration year. The number must between 1 and 12, and the year + month should be larger or equal to current month.

  • Expiry Year (expiryYear)

    • Required: Yes
    • Type: String(4)
    • Example: 2027
    • Description: The card's expiration year

  • Payment Memo (memo)

    • Required: Optional
    • Type: String(128)
    • Example: Bonus

  • Notification URL (notifyUrl)

    • Required: Optional
    • Type: String(200)
    • Example: http://yoursite.com/api/notification
    • Description: The URL where the merchant receives notifications

  • Failure Description (failDes)

    • Required: Optional
    • Type: String(200)
    • Example: -
    • Description: Cause of order failure

  • Bank Reference Number (bankReference)

    • Required: Optional
    • Type: String(128)

  • Payer Fee Amount (payerFeeAmount)

    • Required: Yes
    • Type: Money
    • Example: { "amount": 0, "currency": "AED" },
    • Description: The fee paid by the payer

  • Fee Payer ID (payerFeeMemberId)

    • Required: Yes
    • Type: String(32)
    • Example: 200000429066
    • Description: ID of the party paying the fee

  • Payment Time (paidTime)

    • Required: Yes
    • Type: Date
    • Description: Time of deduction

  • Refund Time (refundedTime)

    • Required: Optional
    • Type: Date
    • Description: Time of refund

Response Sample​

HTTP Headers​

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

HTTP Body​

{
    "body": {
        "transferToBankCard": {
            "amount": {
                "amount": 0.1,
                "currency": "AED"
            },
            "partnerId": "200000429066",
            "notifyUrl": "http://yoursite.com/api/notification",
            "memo": "Bonus",
            "createdTime": 1741917501666,
            "payerFeeAmount": {
                "amount": 0,
                "currency": "AED"
            },
            "payerFeeMemberId": "200000429066",
            "orderNo": "131741917501042130",
            "merchantOrderNo": "7a5b47a4-1824-4a4d-b581-9b0ebd5dd436",
            "product": "Transfer Bank Card",
            "status": "CREATED",
            "paidTime": 1741917502000,
            "accountHolderType": "INDIVIDUAL",
            "cardNumber": "6b59af6dcc4fb841d5f053a852ed917fd5eecad0cc2c3e3507540c065f520a4c",
            "expiryMonth": "08",
            "expiryYear": "2028",
            "firstName": "c6f27629d041725bb227a0d718641d220d69356cd82b3b7230f1d0dff950de5f",
            "lastName": "15d6dacb4fbda825195e5873c175a9b093daa32345c708ac18411365f6fc6038",
            "middleName": "15d6dacb4fbda825195e5873c175a9b093daa32345c708ac18411365f6fc6038"
        }
    },
    "head": {
        "applyStatus": "SUCCESS",
        "code": "0",
        "msg": "SUCCESS",
        "traceCode": "974825"
    }
}

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 PayBy
404SERVICE_NOT_AVAILABLEAPI service unavailableContact PayBy
500SYSTEM_ERRORSystem errorContact PayBy, 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