Cloud API

Onboarding APIs

To receive payments on WhatsApp, you must have a payment configuration linked to the corresponding WhatsApp Business Account. Each payment configuration is associated with a unique name. As part of the order_details message, you can specify the payment configuration to use for a specific checkout.

Onboarding APIs allows you to progamatically perform certain operations:

  • Get all payment configurations linked to a WhatsApp Business Account.
  • Get a specific payment configuration linked to a WhatsApp Business Account.
  • Create a payment configuration.
  • Regenerate payment gateway oauth link to link payment configuration to a payment gateway.
  • Remove a payment configuration.

Get All Payment Configurations

Get a list of payment configurations linked to the WhatsApp Business Account.

Request Syntax

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/payment_configurations

Sample Request

curl 'https://graph.facebook.com/v16.0/102290129340398/payment_configurations' \
-H 'Authorization: Bearer EAAJB...'

Sample Response

{
  "data": [
    {
      "payment_configurations": [
  	{
  	  "configuration_name": "test-payment-configuration",
  	  "merchant_category_code": {
  	    "code": "0000",
            "description": "Test MCC Code"
  	   },
           "purpose_code": {
  	     "code": "00",
  	     "description": "Test Purpose Code"
  	    },
  	    "status": "Active",
   	    "provider_mid": "test-payment-gateway-mid",
  	    "provider_name": "RazorPay",
  	    "created_timestamp": 1720203204,
  	    "updated_timestamp": 1721088316
	  },
          ....
	]
     }
  ]
}
FieldDescription

configuration_name

string

Required.

The name of the payment configuration to be used in the Order Details message.

merchant_category_code

object

Required.

Merchant Category Code:

code string

  • Required. Will be a valid MCC code.

description string

  • Required. MCC code description.

purpose_code

object

Required.

Purpose Code:

code string

  • Required. Will be a valid purpose code.

description string

  • Required. Purpose code description.

status

string

Required.

Status of the payment configuration. Must be one of ["Active", "Needs_Connecting", "Needs_Testing"].

provider_mid

string

Optional.

Payment Gateway Merchant Identification Number (MID).

provider_name

string

Optional.

Payment Gateway Name. Must be one of ["razorpay", "payu", "zaakpay"].

merchant_vpa

string

Optional.

Merchant UPI handle.

created_timestamp

integer

Optional.

Time when payment configuration was created.

updated_timestamp

integer

Optional.

Time when payment configuration was last updated.

Get a specific Payment Configuration

Get a specific payment configuration linked to the WhatsApp Business Account.

Request Syntax

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/payment_configuration/{configuration-name}

Sample Request

curl 'https://graph.facebook.com/v16.0/102290129340398/payment_configuration/test-payment-configuration' \
-H 'Authorization: Bearer EAAJB...'

Sample Response

{
  "data": [
    {
      "configuration_name": "test-payment-configuration",
      "merchant_category_code": {
        "code": "0000",
        "description": "Test MCC Code"
      },
      "purpose_code": {
        "code": "00",
        "description": "Test Purpose Code"
      },
      "status": "Active",
      "provider_mid": "test-payment-gateway-mid",
      "provider_name": "RazorPay",
      "created_timestamp": 1720203204,
      "updated_timestamp": 1721088316
     }
  ]
}
FieldDescription

configuration_name

string

Required.

The name of the payment configuration to be used in the Order Details message.

merchant_category_code

object

Required.

Merchant Category Code:

code string

  • Required. Will be a valid MCC code.

description string

  • Required. MCC code description.

purpose_code

object

Required.

Purpose Code:

code string

  • Required. Will be a valid purpose code.

description string

  • Required. Purpose code description.

status

string

Required.

Status of the payment configuration. Must be one of ["Active", "Needs_Connecting", "Needs_Testing"].

provider_mid

string

Optional.

Payment Gateway Merchant Identification Number (MID).

provider_name

string

Optional.

Payment Gateway Name. Must be one of ["razorpay", "payu", "zaakpay"].

merchant_vpa

string

Optional.

Merchant UPI handle.

created_timestamp

integer

Optional.

Time when payment configuration was created.

updated_timestamp

integer

Optional.

Time when payment configuration was last updated.

Create a Payment Configuration

Create a payment configuration.

Request Syntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/payment_configuration

Sample Request

Payment Gateway type configuration

curl -X  POST \
'https://graph.facebook.com/v15.0/WHATSAPP_BUSINESS_ACCOUNT_ID/payment_configuration' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
       "configuration_name": "test-payment-configuration",
       "purpose_code": "00",
       "merchant_category_code": "0000",
       "provider_name": "razorpay",
       "redirect_url": "https://test-redirect-url.com"
    }'

UPI Vpa type configuration

curl -X  POST \
'https://graph.facebook.com/v15.0/WHATSAPP_BUSINESS_ACCOUNT_ID/payment_configuration' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
       "configuration_name": "test-payment-configuration",
       "purpose_code": "00",
       "merchant_category_code": "0000",
       "provider_name": "upi_vpa",
       "merchant_vpa": "test-upi-merchant-vpa@test"
    }'
FieldDescription

configuration_name

string

Required.

The name of the payment configuration to be used in the Order Details message.

merchant_category_code

string

Optional.

Merchant Category Code.

purpose_code

object

Optional.

Purpose Code.

provider_name

string

Required.

Provider name of the payment configuration. Must be one of ["upi_vpa", "razorpay", "payu", "zaakpay"].

merchant_vpa

string

Optional.

Merchant UPI handle.

redirect_url

URI

Optional.

The url which merchant will be redirected to after successfully linking a payment configuration.

Sample Response

Payment Gateway type configuration

{
  "oauth_url": "https://www.facebook.com/payment/onboarding/init/",
  "expiration": 1721687287,
  "success": true
}

UPI Vpa type configuration

{
  "success": true
}
FieldDescription

oauth_url

string

Optional.

Oauth url to be used to link payment configuration to the payment gateway

expiration

integer

Optional.

Expiration time of the oauth url.

success

boolean

Required.

Boolean flag to denote if payment configuration creation was successful or not.

Regenerate Payment Configuration OAuth link

Regenerate oauth link of payment gateway type payment configuration.

Request Syntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/generate_payment_configuration_oauth_link

Sample Request

curl -X  POST \
'https://graph.facebook.com/v15.0/WHATSAPP_BUSINESS_ACCOUNT_ID/generate_payment_configuration_oauth_link' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
       "configuration_name": "test-payment-configuration",
       "redirect_url": "https://test-redirect-url.com"
    }'
FieldDescription

configuration_name

string

Required.

The name of the payment configuration to be used in the Order Details message.

redirect_url

URI

Optional.

The url which merchant will be redirected to after successfully linking a payment configuration.

Sample Response

{
  "oauth_url": "https://www.facebook.com/payment/onboarding/init/",
  "expiration": 1721687287
}
FieldDescription

oauth_url

string

Optional.

Oauth url to be used to link payment configuration to the payment gateway

expiration

integer

Optional.

Expiration time of the oauth url.

Remove a Payment Configuration

Remove a payment configuration.

Request Syntax

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/payment_configuration
FieldDescription

configuration_name

string

Required.

The name of the payment configuration to be used in the Order Details message.

Sample Request

curl -X  DELETE \
'https://graph.facebook.com/v15.0/WHATSAPP_BUSINESS_ACCOUNT_ID/payment_configuration' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
       "configuration_name": "test-payment-configuration"
    }'

Sample Response

{
  "success": true
}
FieldDescription

success

boolean

Required.

Boolean flag to denote if payment configuration removal was successful or not.

Payment Configuration Webhook

Businesses receive updates via WhatsApp webhooks when the status of the payment configuration changes.

To receive webhook, Businesses must subscribe to "payment_configuration_update" event for their respective application.

Webhook contains the following fields:

FieldDescription

configuration_name

string

Required.

The name of the payment configuration to be used in the Order Details message.

provider_name

string

Required.

Provider name of the payment configuration. Must be one of ["razorpay", "payu", "zaakpay"].

provider_mid

string

Required.

Payment gateway account merchant ID.

status

string

Required.

Status of the payment configuration. Must be one of ["Active", "Needs_Connecting", "Needs_Testing"].

created_timestamp

integer

Required.

Time when payment configuration was created.

updated_timestamp

integer

Required.

Time when payment configuration was last updated.

Sample Payment Configuration Webhook

{
  "entry": [
    {
      "id": "0",
      "time": 1725499886,
      "changes": [
        {
          "field": "payment_configuration_update",
          "value": {
            "configuration_name": "test-payment-configuration",
            "provider_name": "razorpay",
            "provider_mid": "test-provider-mid",
            "status": "Needs Testing",
            "created_timestamp": 123457678,
            "updated_timestamp": 123457678
          }
        }
      ]
    }
  ],
  "object": "whatsapp_business_account"
}