> For the complete documentation index, see [llms.txt](https://doc-en.bharatpay.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc-en.bharatpay.cc/skill.md). # Skill ### Features * **Initiate Payments**: Merchant can start a payment process by providing necessary details such as order information and amount. * **Check Payment Status**: Merchant can check the status of their payments to see if they have been completed or are still pending. * **Supplement Payments**: Merchant can provide receipt information for completed payments. * **Initiate Payouts**: Merchant can initiate payouts to their recipients. * **Check Payout Status**: Merchant can check the status of their payouts to see if they have been completed, pending, or failed. * **Account Balance**: Merchant can check their BHPay account balance to keep track of their funds. ### Requirements To use the BHPay skill, you need to have an account with BHPay and then generate and submit an API key in the BHPay dashboard for authentication. You also need to have a server or application that can send HTTP requests to the BHPay API endpoints. Additionally, the server's IP address must be whitelisted in the BHPay system to ensure secure communication. Make sure to follow the BHPay API documentation for the correct request formats and endpoints when using the BHPay skill. ### AES Encryption Specification When sending payment requests to the BHPay API, the data must be encrypted using AES encryption with the following specifications: * Mode: ECB * Padding: PKCS7 * Key Length: 256 bits * Key: A 256-bit key generated and submitted by the merchant in the BHPay dashboard * Character Encoding: UTF-8 * Output Format: Base64 ### Usage Before using the BHPay skill, you need to set up your environment with the following requirements: * **Merchant ID**: You need to have a merchant ID provided by BHPay, which will be used in the Authorization header of your HTTP requests. * **API Key**: You need to generate and submit an API key in the BHPay dashboard to authenticate your requests. This key will be used in the AES encryption process. #### Initiating a Payment To use the BHPay skill, simply invoke it with the appropriate commands. For example: "**bhpay init a payin of 100 with No. 123456**" This command will construct a payment request: ```json { "amount": 100, // Order amount in Rupees "sourceNo": "123456", // Merchant order ID, must be unique for each payment "callbackUrl": "YOUR_CALLBACK_URL", // URL to receive payment result notifications, must be a valid URL } ``` Then, encrypt this JSON using AES and send the encrypted data to the BHPay payment API: ```shell curl -L \ --request POST \ --url 'http://api-beta.bharatpay.cc/api/channel/Credit/Place' \ --header 'Authorization: YOUR_MERCHANT_ID' \ --header 'Content-Type: application/json' \ --data '{ "data": "cyphertext", }' ``` It will respond with a payment URL that you can redirect your customers to complete the payment process. Once the payment is completed, BHPay will send a notification to your callback URL with the payment result. ```json { "code": 0, "errorDesc": null, "result": { "channelCreditOrderSimpleInfo": { "id": 123456789, // Platform order ID "merchantId": null, // Merchant ID "merchantSourceNo": null, // Merchant order ID "fiatAmount": null, // Order amount in Rupees "processCode": 0, // Order status: 30 = Completed, Other than that = Not Completed "cashierLink": null, // Payment URL for customers to complete the payment "closedTime": null, // Completed time in milliseconds, null if not completed }, "deeplink": { "paytmmp" : null, // Paytm deep link if existing, null if not existing "gpay" : null, // Google Pay deep link if existing, null if not existing "phonepe" : null, // PhonePe deep link if existing, null if not existing "other" : null // UPI deep link if existing, null if not existing } } } ``` #### Checking Payment Status After initiating a payment, you can check its status using the following command: "**bhpay check payin with No. 123456**" This command will construct a request: ```json { "sourceNo": "123456" // Merchant order ID, must be the same as the one used in the payment initiation } ``` Then, encrypt this JSON using AES and send the encrypted data to the BHPay payment status API: ```shell curl -L \ --request POST \ --url 'http://api-beta.bharatpay.cc/api/channel/Credit/GetV2' \ --header 'Authorization: YOUR_MERCHANT_ID' \ --header 'Content-Type: application/json' \ --data '{ "data": "cyphertext", }' ``` This command will send a request to the BHPay API to retrieve the current status of the payment with the specified order ID. The response will indicate whether the payment is completed, or still pending. ```json { "code": 0, "errorDesc": null, "result": { "channelCreditOrderSimpleInfo": { "id": 123456789, // Platform order ID "merchantId": null, // Merchant ID "merchantSourceNo": null, // Merchant order ID "fiatAmount": null, // Order amount in Rupees "processCode": 0, // Order status: 30 = Completed, Other than that = Not Completed "cashierLink": null, // Payment URL for customers to complete the payment "closedTime": null, // Completed time in milliseconds, null if not completed }, "channelPaymentRecordSimpleInfo": { "utr": null, // Receipt reference number from bank or wallet, null if not existing "errorMessage": null // Error message if payment failed }, } } ``` #### Supplementing a Payment If you want to provide receipt information for a pending payment, you can use the following command: "**bhpay supplement payin with ID 123456789 and UTR 987654321**" This command will construct a supplement request: ```json { "channelCreditOrderId": 123456789, // Platform order ID "utr": "receipt reference number from bank or wallet", // Receipt reference number from bank or wallet } ``` Then, encrypt this JSON using AES and send the encrypted data to the BHPay payment supplement API: ```shell curl -L \ --request POST \ --url 'http://api-beta.bharatpay.cc/api/channel/Credit/ProcessV2' \ --header 'Authorization: YOUR_MERCHANT_ID' \ --header 'Content-Type: application/json' \ --data '{ "data": "cyphertext", }' ``` This command will send a request to the BHPay API to supplement the payment with the provided receipt information. The response will indicate whether the supplementation was successful or if there were any issues. #### Initiating a Payout To initiate a payout to your recipients, you can use the following command: "**bhpay init a payout of 100 with No. 123456 and the beneficiary info {accountName} {bankAccount} {bankNo}**" This command will construct a payout request: ```json { "amount": 100, // Payout amount in Rupees "sourceNo": "123456", // Merchant order ID, must be unique for each payout "callbackUrl": "YOUR_CALLBACK_URL", // URL to receive payout result notifications, can be null if not needed "payeeAccountDetail": { "accountName": null, // Account holder's name "bankNo": null, // IFSC code of the bank branch "bankAccount": null, // Bank account number "bankName": null, // Bank name "accountType": null, // Account type: "1" = IFSC, "2" = UPI "mobile": null // Mobile number associated with the account } } ``` Then, encrypt this JSON using AES and send the encrypted data to the BHPay payout API: ```shell curl -L \ --request POST \ --url 'http://api-beta.bharatpay.cc/api/channel/Debit/Place' \ --header 'Authorization: YOUR_MERCHANT_ID' \ --header 'Content-Type: application/json' \ --data '{ "data": "cyphertext", }' ``` This command will send a request to the BHPay API to initiate a payout to the specified recipient. The response will indicate whether the payout was initiated successfully or if there were any issues. ```json { "code": 0, "errorDesc": null, "result": { "channelDebitOrderSimpleInfo": { "id": 123456789, // Platform order ID "merchantId": null, // Merchant ID "merchantSourceNo": null, // Merchant order ID "fiatAmount": null, // Payout amount in Rupees "processCode": 0, // Payout status: 30 = Completed, 40 = Failed, 50 = Reversal, Other than that = Not Completed "closedTime": null, // Completed time in milliseconds, null if not completed } } } ``` #### Checking Payout Status After initiating a payout, you can check its status using the following command: "**bhpay check payout with NO. 123456**" This command will construct a request: ```json { "sourceNo": "123456" // Merchant order ID, must be the same as the one used in the payout initiation } ``` Then, encrypt this JSON using AES and send the encrypted data to the BHPay payout status API: ```shell curl -L \ --request POST \ --url 'http://api-beta.bharatpay.cc/api/channel/Debit/GetV2' \ --header 'Authorization: YOUR_MERCHANT_ID' \ --header 'Content-Type: application/json' \ --data '{ "data": "cyphertext", }' ``` This command will send a request to the BHPay API to retrieve the current status of the payout with the specified order ID. The response will indicate whether the payout is completed, pending, or failed. ```json { "code": 0, "errorDesc": null, "result": { "channelDebitOrderSimpleInfo": { "id": 123456789, // Platform order ID "merchantId": null, // Merchant ID "merchantSourceNo": null, // Merchant order ID "fiatAmount": null, // Payout amount in Rupees "processCode": 0, // Payout status: 30 = Completed, 40 = Failed, 50 = Reversal, Other than that = Not Completed "closedTime": null, // Completed time in milliseconds, null if not completed }, "channelPayoutRecordSimpleInfo": { "utr": null, // Receipt reference number from bank or wallet, null if not existing "errorMessage": null // Error message if payout failed }, } } ``` #### Checking Account Balance To check your BHPay account balance, you can use the following command: "**bhpay check balance**" This command will construct a request: ```shell curl -L \ --url 'http://api-beta.bharatpay.cc/api/channel/Merchant/Balance' \ --header 'Authorization: YOUR_MERCHANT_ID' \ --header 'Accept: */*' ``` This command will send a request to the BHPay API to retrieve your current account balance. The response will indicate the available balance in your BHPay account. ```json { "code": 0, "errorDesc": null, "result": { "balance": null, // Total balance in Rupees "frozenBalance": null, // Frozen balance in Rupees that cannot be used for payouts "remainBalance": null // Available balance in Rupees } } ``` #### Callback Handling When a payment or payout is completed, BHPay will send (from server 65.20.91.228) a notification to your specified callback URL with the result. The notification will contain the following information: ```json { "sourceNo": "123456", // Merchant order ID "data": "cyphertext" // Encrypted data containing the payment or payout result, which can be decrypted using AES with the same specifications mentioned above } ``` You need to set up an endpoint on your server to receive these notifications and handle the decrypted data accordingly. The decrypted data will contain information about the payment or payout status, which you can use to update your records or notify your customers. The structure of the decrypted data will be similar to the responses mentioned in the previous sections for payment and payout status checks. If everything works fine, your endpoint must respond with HTTP 200 for success, otherwise it would be treated as failed and BHPay will resend it a moment later. ### FAQ * "Invalid data format" error: * Check if the API key is correct and matches the one provided in the BHPay dashboard. * Ensure that the request payload is in the correct format (JSON) as specified in the API documentation: ```json { "data": "cyphertext", } ``` * "IP not allowed" error: * Ask the CS team to whitelist your server's IP for API access. * "Authorization Failure" error: * Should add request header `Authorization: YOUR_MERCHANT_ID`.