• English
  • Initiate merchant payment

    Considerations

    1. If API does not return normally, a network or system error may occurr. Please do not directly treat it as a successful or failed order. Highly recommend to check the order status of through the API of querying transaction results.
    2. If calling the API of innitiating merchant payment with the same order number, the response will be MC100000 error. Highly recommend to check the order status of through the API of querying transaction results.

    Request Path

    /api/v2/merchant/payment/payout 

    Parameter List

    NameTypeLengthRequiredDescription
    orderIdString32yesThe unique Order Number of the merchant, which can be used to query transaction results.
    titleString100NoOrder title
    descriptionString200NoOrder description
    payeeNameString50NoName of the payee (If not passed, the default value is unknown)Please fill in this field in Pakistan.
    payeeBankCodeString50TZ OthersBank or MMO code of the payee
    payeeBankAccNoString50yesBank account or MoMo account of the payee. The account number is purely numeric, with no spaces or special characters.
    payeePhoneNoString50NoPayee phone number in the international format, starting with the country code, e.g. 023301234567890 For Ghana, this is used exclusively for the payee in Ghana to receive the transfer SMS notification.; For Pakistan, please fill in this field.
    payeeEmailString50NoPayee email. For Pakistan, please fill in this field.
    currencyString10yesCurrency(NGN) Data Dictionary
    amountLong20yesTransaction amount (minimum unit measurement), For example, "100" =1GHS/NGN/TZS
    currencyString10yesCurrency (GHS/NGN/TZS/KES/ZAR/PKR)
    notifyUrlString200yesThe url used to receive the payment notification.
    remarkString200yesRemark

    Return Value

    NameTypeLengthRequiredDescription
    currencyString10yesCurrency(NGN) Data Dictionary
    amountLong20yesOrder amount (minimum unit measurement) only when orderStatus = 2
    feefee20NoTotal fee amount (minimum unit) only when orderStatus = 1 or 2 fee:{ fee: 0, vat: 0}
    orderNoString32yesThe order number responded by the PalmPay.
    orderIdString32yesMerchant's original order number
    orderStatusInteger20yesOrder Status (see Order Status)
    sessionIdString128NoChannel Response Parameters. Note: Most of the non-NIBSS channels do not return sessionId, if there is any problem with this type of order, you need to provide the order number to PalmPay to confirm the actual arrival of the payee.
    messageString20NoOrder status description information
    errorMsgString200NoError message

    Error Code

    Error Code

    Postman Example

    request

    curl --location 'https://open-gw-sandbox.palmpay-inc.com/api/v2/merchant/payment/payout' \
    --header 'Accept: application/json, text/plain, */*' \
    --header 'CountryCode: NG' \
    --header 'Authorization: Bearer 10241024' \
    --header 'Signature: D11A3E8CB478C0B0F40276DDA5AFD898' \
    --header 'Content-Type: application/json' \
    --data '{
      "requestTime":1658568813705,
      "version":"V1.1",
      "nonceStr":"rNsxYX3R7H5tU5NG3IC4BwF8LGDvLugF",
      "orderId":"e7c3784d5e2242fc00afe89ac1234",
      "payeeName":"xuzheng",
      "payeeBankCode":"100033",
      "payeeBankAccNo":"8900000000",
      "payeePhoneNo":"0591990607"
      "amount":50000,
      "currency":"NGN",
      "notifyUrl":"https://palmpay.com/notify",
      "remark":""
    }'

    response

    {
      "respCode":"00000000",
      "respMsg":"success",
      "data":{
        "currency":"NGN",
        "amount":50000,
        "fee": {
          "fee": 402
        },
        "orderNo":"41220723093001",
        "orderId":"e7c3784d5e2242fc00afe89ac1234",
        "orderStatus":2,
        "sessionId": "100033240509135230000500932911",
        "message":"success"
      }
    }