SMART_CARRIER_BILLING

The SMART_CARRIER_BILLING payment method allows users to make purchases directly through their mobile phone carrier. This is a widely adopted option in regions with high mobile penetration and low credit card usage, making it ideal for gaming, entertainment, and digital services.

The solution abstracts complex integrations with multiple telecom operators and third-party aggregators, providing a unified API for consistent and simplified carrier billing experiences across markets. It supports both one-time payments and recurring subscriptions.

Supported Carrier Billing Methods

Method	Markets Supported	Notes
Boku	Global	One-click payments, SMS-based billing, and direct billing. Supports recurring subscriptions.
Fortumo	Europe, LATAM, Asia, Africa	Local integrations enabling direct-to-carrier billing.
DOCOMO	Japan	Seamlessly integrated with Japanese telecom networks.
Smart, Globe	Philippines	Supports SMS-based payments and direct API carrier billing.
Telkomsel	Indonesia	Enables mobile billing with local regulatory compliance.
MTN, Vodacom	Africa (Nigeria, South Africa, etc.)	Provides USSD or SMS billing, varying by country and operator.
Telenor	Scandinavia, Eastern Europe	Popular for premium content and subscription billing.

Payload Fields

Field	Type	Required?	Description
`paymentMethod`	ApmMethod	Yes	Must always be set to `SMART_CARRIER_BILLING`.
`paymentType`	ApmFlowType	Yes	Must always be `CARRIER_BILLING`.
`msisdn`	String	Required	The user’s mobile phone number in E.164 international format (e.g., `+1234567890`).
`accountIdentifier`	String	Optional	Internal identifier for mapping recurring payments or tracking references.
`customerName`	String	Optional	The full name of the customer for verification or record-keeping purposes.
`mobileOperator`	String	Optional	Name of the mobile carrier (e.g., MTN, Vodafone).
`operatorCountryCode`	String	Optional	ISO Alpha-2 country code for the mobile operator (e.g., `US`, `NG`).
`recurringId`	String	Optional	Unique identifier used for subscription renewals or linked recurring billing profiles.

Response Fields

Field	Type	Required?	Description
`paymentMethod`	ApmMethod	Yes	Always returns `SMART_CARRIER_BILLING`.
`paymentType`	ApmFlowType	Yes	Always returns `CARRIER_BILLING`.
`redirectUrl`	String?	Optional	URL where the user is redirected to the carrier’s page to complete the payment flow.
`iframeUrl`	String?	Optional	URL for an embedded iframe checkout experience (if the carrier supports it).
`providerTransactionId`	String	Yes	Unique identifier for the transaction as assigned by the carrier or aggregator.
`sessionToken`	String?	Optional	Token used for resuming an interrupted session or performing follow-up requests.
`carrierMetadata`	Map<String, String>?	Optional	Additional carrier-specific information (e.g., billing flow type, operator details) useful for reconciliation or reporting.

Best Practices

Phone Number Standardization: Always normalize and store msisdn values in E.164 format for cross-market consistency.
Validation: Validate the mobile number and ensure it matches the allowed carriers and countries supported by your integration.
Recurring Billing: Store and reuse the recurringId for subscription management and automated renewals.
Metadata Usage: Leverage carrierMetadata to capture extra information like operator-specific billing references, which aids in reconciliation, dispute resolution, and advanced reporting.