• English
  • Create Order

    Request Path

    [POST] /api/v2/bill-payment/order/create

    Parameter List

    Parameter List

    NameTypeLengthRequiredDescription
    sceneCodeString-YesBusiness scenario code【see detailed scenario codes】
    outOrderNoString64YesMerchant order number, customized by the merchant, up to 32 characters, supports letters, numbers, underscores, and must be unique within the merchant system
    amountLong-YesTotal order amount (unit: cents)
    notifyUrlString200YesPayment notification callback URL
    billerIdString32YesOperator ID
    itemIdString32YesPackage ID
    rechargeAccountString15YesRecharge account (fill in the phone number)
    titleString50NoOrder title
    descriptionString200NoOrder description
    relationIdString64NoUser-defined associated ID

    Return Values

    NameTypeLengthRequiredDescription
    outOrderNoString64YesMerchant order number
    orderNoString32YesPalmPay platform order number
    orderStatusInteger2YesOrder status (see detailed order status)
    msgString8NoStatus description
    amountLong-YesTotal order amount (unit: cents)
    sceneCodeString-YesBusiness scenario code (see detailed scenario codes)

    Postman Request Example

    request

    curl --location 'https://open-gw-sandbox.palmpay-inc.com/api/v2/bill-payment/order/create' \
    --header 'Accept: application/json, text/plain, */*' \
    --header 'CountryCode: NG' \
    --header 'Authorization: Bearer 10241024' \
    --header 'Signature: D11A3E8CB478C0B0F40276DDA5AFD898' \
    --header 'Content-Type: application/json' \
    --data '{
        "requestTime": 1713943883031,
        "nonceStr": "w7WDWFze8rfBcy25yb6pXbFf7XirM2DK",
        "version": "V2",
        "outOrderNo": "MKiPaeQWMk2drrQrBBd6WPtx8wP8aNjx",
        "sceneCode": "airtime",
        "billerId": "MTN",
        "itemId": "5267001812000",
        "rechargeAccount": "023409551234900",
        "relationId": "isRXw8r68PsQmkSrJJJAtcSrDSCTWPyE",
        "amount": 10000,
        "notifyUrl": "http://xxx.cn"
    }'

    response

    {
      "respCode": "00000000",
      "respMsg": "success",
      "data": {
        "outOrderNo": "P86iMr6AGr2Mzx84QnNP3HC636pFcA10",
        "orderNo": "y421t3k8000",
        "orderStatus": 1,
        "msg": "SUCCESS",
        "amount": 8800,
        "sceneCode": "airtime"
      }
    }

    Common Error Codes

    Please refer to the document

    Business Error Codes

    Error CodeError DescriptionSolution
    SBP.INVALID_PARAMETERInvalid parameterCheck the request parameters and resend after making corrections
    SBP.INVALID_SCENE_CODEInvalid scenario codeCheck the scenario code and resend after making corrections
    SBP.BILLER_DISABLEOperator unavailableCheck if the Operator ID is correct or if the Operator status is available
    SBP.ITEM_DISABLEItem unavailableCheck if the Item ID is correct or if the Operator status is available
    SBP.BILLER_ITEM_MISMATCHOperator and package mismatchCheck if the Operator ID matches with the Package ID
    SBP.AMOUNT_ABOVE_MAX_LIMITRecharge amount above maximum limitEnsure the recharge amount is below the maximum amount
    SBP.AMOUNT_BELOW_MIN_LIMITRecharge amount below minimum limitEnsure the recharge amount is above the minimum amount
    SBP.AMOUNT_MISMATCHRecharge amount does not match the item amountEnsure the recharge amount matches the fixed amount of the item if applicable
    SBP.MERCHANT_ERRORMerchant errorCheck if the merchant is operating normally
    SBP.MERCHANT_ACCOUNT_ERRORMerchant account errorCheck if the merchant account status is normal
    SBP.MERCHANT_ACCOUNT_STATUS_ERRORMerchant account status errorCheck if the merchant account status is normal
    SBP.MERCHANT_ACCOUNT_BALANCE_NOT_ENOUGHMerchant account balance insufficientEnsure the merchant account has sufficient balance
    SBP.TRADE_HAD_DEALExternal merchant order number duplicateCheck the transaction number provided and resend after making corrections 求