Purchase Virtual Number

This API is used to purchase a virtual number for your account. It supports both Credit Card and BECS Direct Debit payment methods.

Parameters for Purchasing Virtual Number

Headers Parameters

Parameters	Description
Authorization	Please add provided Bearer token - linked to your Cellcast account. Check here
Content-Type	application/json

Request Body Parameters

Common Parameters (Required for all payment types)

Name	Example	Description
product	prod_PFdN753rT3lNFW	Required. The product ID for the virtual number.
number	66ea98514f0c1a121c76ec17	Required. The ID of the virtual number to purchase.
recurring_time	month	Required. The billing cycle (month or year).
payment_type	card	Optional. Payment method type: card (default) or au_becs_debit.
resubscribe	false	Optional. Whether to resubscribe automatically.

Credit Card Payment Parameters

Name	Example	Description
card	card_1SQmzoGOdUwLPbU6ll0QwsyH	Required for frontend. The Stripe card ID for payment.
token	tok_1ABC123DEF456	Required for API-only. The Stripe token created from card details.

BECS Direct Debit Payment Parameters

Name	Example	Description
payment_method	pm_1ABC123DEF456	Required for frontend. The Stripe payment method ID created from frontend.
becs_email	[email protected]	Required. Email address for mandate and debit notifications.
becs_name	John Doe	Required. Bank account holder name.
becs_bsb_number	000000	Required for API-only. 6-digit BSB number.
becs_account_number	000123456	Required for API-only. Bank account number.

Important Note on Product ID

The product parameter must match the recurring_time value:

• For recurring_time: "month", use the monthlyProductId from the Get Available Virtual Numbers API response
• For recurring_time: "year", use the yearlyProductId from the Get Available Virtual Numbers API response

Using the incorrect product ID for the billing cycle will result in a purchase error.

BECS Direct Debit Notes

• BECS payments take 2-3 business days to process
• Stripe will send mandate and debit notification emails to the becs_email address
• For testing, use BSB: 000000 and Account: 000123456

Code Samples

Post https://api.cellcast.com/api/v1/virtual-number/purchase

Credit Card

curl --location 'https://api.cellcast.com/api/v1/apiClient/virtual-number/purchase' \
--header 'authorization: Bearer {{API_KEY}}' \
--header 'content-type: application/json' \
--data '{
    "payment_type": "card",
    "card": "card_1SQmzoGOdUwLPbU6ll0QwsyH",
    "product": "prod_PFdN753rT3lNFW",
    "number": "66ea98514f0c1a121c76ec17",
    "recurring_time": "month",
    "resubscribe": false
}'

BECS

curl --location 'https://api.cellcast.com/api/v1/apiClient/virtual-number/purchase' \
--header 'authorization: Bearer {{API_KEY}}' \
--header 'content-type: application/json' \
--data '{
    "payment_type": "au_becs_debit",
    "becs_email": "[email protected]",
    "becs_name": "John Doe",
    "becs_bsb_number": "000000",
    "becs_account_number": "000123456",
    "product": "prod_PFdN753rT3lNFW",
    "number": "66ea98514f0c1a121c76ec17",
    "recurring_time": "month",
    "resubscribe": false
}'

Replace with the actual API key that you own.

Responses

200 Success - Credit Card

{
  "app_type": "web",
  "app_version": "1.0",
  "maintainence": 0,
  "new_version": 0,
  "force_update": 0,
  "invalid_token": 0,
  "refresh_token": "",
  "show_message": 1,
  "is_enc": false,
  "status": true,
  "message": "Payment is Successful. Dedicated Number has been assigned you.",
  "message_type": "toast",
  "data": {},
  "error": {}
}

200 Success - BECS Direct Debit

{
  "app_type": "web",
  "app_version": "1.0",
  "maintainence": 0,
  "new_version": 0,
  "force_update": 0,
  "invalid_token": 0,
  "refresh_token": "",
  "show_message": 1,
  "is_enc": false,
  "status": true,
  "message": "BECS Direct Debit mandate accepted. Your dedicated number will be activated.",
  "message_type": "toast",
  "data": {},
  "error": {}
}

400 Bad Request - Missing Parameters

{
  "status": false,
  "message": "Either token or card parameter is required for card payments",
  "message_type": "inline",
  "data": {},
  "error": {
    "credit": "Either token or card parameter is required for card payments"
  }
}

400 Bad Request - Invalid Payment Type

{
  "status": false,
  "message": "payment_type must be either \"card\" or \"au_becs_debit\"",
  "message_type": "inline",
  "data": {},
  "error": {
    "payment_type": "payment_type must be either \"card\" or \"au_becs_debit\""
  }
}

401 Unauthorized

{
  "code": 401,
  "message": "Token expired",
  "stack": "APIError: Token expired ...."
}