Payments API enables businesses to accept payments from their customers through all UPI Apps installed on their device via WhatsApp. Businesses can send invoice(order_details) messages to their customers, and then get notified about payment status updates via webhook notifications from Payment Gateway.



Prerequisites


  1. You should have a WhatsApp Business Account with the registered WhatsApp Phone Number.

  2. You should have a registered Payment Gateway account with PayU or RazorPay.

  3. You should have a system integrated with the WhatsApp Payment APIs.

  4. You should have the system to generate the order detail messages with a unique Order ID for each payment.


How It Works

  • Initiating Payment:

To kick off the payment process, the business sends an 'order_details' message to the consumer. This special message contains four main components: header, body, footer, and action. Inside the action component, the business includes all the necessary information for the customer to complete their payment.

  • Unique Reference ID:

Each 'order_details' message carries a unique reference_id provided by the business. This unique number is nothing but the order id or order number which is crucial throughout the entire process, acting as a tracking ID for the order. The reference_id is obtained from the UPI intent link generated for a business order through the Payment Gateway.

  • Tracking Order Status:

After sending the 'order_details' message, the business patiently awaits payment or transaction status updates directly from the Payment Gateway. Once a payment signal for an order is received, the business should promptly relay this information to the consumer through an interactive 'order_status' message.

  • Importance of Payment Signal Update (optional):

Updating the user about the payment signal is vital. This update modifies the 'order_details' message and the consumer's order details view, confirming the order from the merchant. We illustrate this process with an example in the subsequent sections.



Steps to be followed

Request Access

The Payment APIs needs to be enabled for the customer WhatsApp Business Account.

To get this enabled please raise a support ticket with the required information to Exotel support team to enable the Payment API for the Business (If you are already allowlisted for an older number, you may skip this step). 
Please follow the below steps to raise the ticket


Subject

Request access for the WhatsApp Payment APIs for the <WhatsApp business name>

To

[email protected] (and add your respective Customer Success Managers in the ticket in the cc)

Body

Hi Team,

I am writing to request access to enable the Payment APIs for our business account. Below are the details required for processing the request:


Business Name: [Your Business Name]

WhatsApp Business Account ID (WABA ID): [Your WABA ID]

WhatsApp Business Phone Number: [Your WhatsApp Business Phone Number]

Preferred Payment Gateway Name: [RazorPay or PayU]

Use Case: Explain the use you plan to build using the WhatsApp Payment APIs in a few lines

Best regards


Link Payment Gateway Account

To be done by the customer: Connect your WhatsApp Business Account with the Payment Gateway

For Seller owned WABA:

  1. Login to the WhatsApp Business Manager Account and your Payment Gateway Account.

  2. Navigate to the Payment methods section from the LHS navigation bar.

  3. https://business.facebook.com/wa/manage/direct-pay/ 



  1. Navigate to the relevant WABA and start the account linking process by “Adding a direct pay method”

  2. Put in the WABA ID and select the correct WABA ID.

  3. Put in a name, and note the payment configuration name in this step.

  4. Set the MCC to 000 to the relevant code.

  5. Set the Purpose code to the relevant code.

  6. Follow the steps and select Payment Gateway in the dropdown where you are asked for the payment gateway. Please see the screenshot below for your reference.


  1. Enter your password and you will be redirected to the payment gateway website

  2. Login using the credentials in step (1) and authorize “Whatsapp Payments India” to access the payment gateway account. You will need a Whatsapp-enabled phone number.

  3. Your payment gateway should now be linked to your WABA.


For BSP owned WABA (OBO)

  1. BSP logs into the Whatsapp Manager.

  2. Initiates creating a “Direct Pay Method”

  3. Follow the same steps as the Seller Owned WABA method above from step 5 to step 9.

  4. Share the link generated on submission of the above form to the seller.

  5. The seller logs in to the FB business manager account.

  6. The seller is redirected to PG website, where the seller will need to log in and approve allowing Meta to request payments on behalf of the seller.

Initiate Checkout

To be done by the customer: Please follow the steps below to send the order details message, and send the order status: 

Order details

  1. Construct Order Details message using the example in the Postman collection shared. Postman Collection.

  2. Set the: action.parameters.payment_configuration to the name of the payment configuration you created above.

  3. Note “action.parameters.payment_type” → “payment_gateway:<razorpay,payu>”

  4. Set “action.parameters.reference_id” → “some-id”


Here’s the pictorial representation of how the order message renders in the WhatsApp screen:


  1. POST it to - https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/messages 

    1. You can get the API Key, Token, Subdomain and SID from your Exotel Messaging Account under the Number Management section.

  2. Configure Webhook - Go to the Webhooks section on the Exotel messaging console and 

search for your Phone number.

  1. Click on the Edit icon, paste and save your Callback URL here.


Order status (optional)

  1. Order status information will already be available in the Webhooks but there is an alternate way to fetch the order status by calling the order status API.

  2. The order status will be “pending” by default and needs to be changed to the right status to avoid confusing the buyer.

  3. Once you receive the payment status for your order

  4. Update order status to the user and set it to “processing”

  5. Initiate order fulfillment.

  6. Once you receive a status from your order management system, update the user about the order’s status (If order fulfillment fails, let the user know what they can do).

  7. “action.parameters.reference_id” must match the corresponding order ID

  8. We show supported statuses, what they mean and a finite state machine.


Test and Launch

To be done by the customer: Please follow the steps below to test and launch the payment solution! 

  1. You can now construct the Send Message API with the details.

  2. As this is a session message, this should deliver the order details message, remember the phone needs to have interacted with this bot in the last 24 hours, for this to work as expected. Just send a “hi” from the number to not fail this check.

  3. On the phone: Click on “Review and Pay” and Hit “Continue”

  4. Pay using any of the UPI apps, you have. 

  5. Check your callback to look for a call from Whatsapp with payment status details for “some-id” or “reference-id” you provided.

  6. Now update the order status to “Complete” by using the “Order Status” example in the Postman collection.

  7. Note action.parameters.reference_id → “some-id”

  8. Note action.parameters.order.status → “completed”

  9. The user should now see an order status message, verify if it looks correct.

  10. This should align with payment IDs from the PG merchant website.

  11. Log into PG’s merchant account and match these payment IDs for reference.



For any further concerns, please write to [email protected].